ncdata package#

An abstract representation of Netcdf data with groups, variables + attributes.

As provided by the NetCDF “Common Data Model” : https://docs.unidata.ucar.edu/netcdf-java/5.3/userguide/common_data_model_overview.html

It is also provided with read/write conversion interfaces to Xarray, Iris and netCDF4, thus acting as an efficient exchange channel between any of those forms.

class ncdata.NcData#

Bases: _AttributeAccessMixin

An object representing a netcdf group- or dataset-level container.

Containing dimensions, variables, attributes and sub-groups.

__init__(name=None, dimensions=None, variables=None, attributes=None, groups=None)#

Parameters:

name (str | None)
dimensions (Mapping | Iterable)
variables (Mapping | Iterable)
attributes (Mapping | Iterable)
groups (Mapping | Iterable)

name: str#: a group/dataset name (optional)

dimensions: Dict[str, NcDimension]#: group/dataset dimensions

variables: Dict[str, NcVariable]#: group/dataset variables

attributes: Dict[str, NcAttribute]#: group/dataset global attributes

groups: Dict[str, NcData]#: sub-groups

copy()#

Copy self.

This duplicates structure with all-new ncdata core objects, but does not duplicate variable data arrays. See ncdata.utils.ncdata_copy().

slicer(*dim_names)#

Make a Slicer object to index the data.

This creates a slicer which can then be indexed to sub-index the data. See: Extract a subsection by indexing

Parameters:: dim_names (list(str)) – Names of dimensions to slice.
Return type:: Slicer

Examples

>>> subregion = ncdata.slicer('x', 'y')[3, 2:4]

property avals#

A convenience view of an NcData or NcVariable’s attribute values.

The .avals property acts as a more convenient view onto the .attributes, providing a simple “{name: value}” map.

( Meanwhile, the attributes are actually stored in the .attributes property, but this is a “{name: NcAttribute}” map ).

The values of the .avals map are the values of the .attributes, but converted to convenience forms, as described in NcAttribute.as_python_value().

get_attrval(name)#

Get the Python value of a named attribute in self.attributes.

If no such attribute exists, returns None.

Warning

This legacy method is now deprecated, and will be removed in a future release.

Parameters:: name (str)
Return type:: Any

set_attrval(name, value)#

Set the Python value of a named attribute in self.attributes.

Warning

This legacy method is now deprecated, and will be removed in a future release.

Parameters:: name (str)
Return type:: NcAttribute

class ncdata.NcDimension#

Bases: object

An object representing a netcdf dimension.

Associates a name with a length, and also an ‘unlimited’ flag.

__init__(name, size, unlimited=None)#

Parameters:

name (str)
size (int)
unlimited (bool | None)

name: str#: dimension name

size: int#: dimension size (current size, if unlimited)

unlimited: bool#: whether dimension is unlimited

copy()#: Copy self.

class ncdata.NcVariable#

Bases: _AttributeAccessMixin

An object representing a netcdf variable.

With dimensions, dtype and data, and attributes.

‘data’ may be None, but if not is expected to be an array : either numpy (real) or Dask (lazy).

The ‘dtype’ will presumably match the data, if any.

It has no ‘shape’ property, in practice this might be inferred from either the data or dimensions. If the dims are empty, it is a scalar.

A variable makes no effort to ensure that its dimensions, dtype + data are consistent. This is to be managed by the creator.

__init__(name, dimensions=(), data=None, dtype=None, attributes=None, group=None)#

Create a variable.

The ‘dtype’ arg is relevant only when no data is provided : If ‘data’ is provided, it is converted to an array if needed, and its dtype replaces any provided ‘dtype’.

Parameters:

name (str)
dimensions (Iterable[str])
data (ndarray | dask.array.array | None)
dtype (dtype)
attributes (Mapping | Iterable)
group (NcData)

name: str#: variable name

dimensions: Tuple[str]#: variable dimension names (a list of strings, not a dict of objects)

dtype: dtype#

data#: variable data (an array-like, typically a dask or numpy array)

attributes: NameMap#: variable attributes

group: NcData | None#: parent group

copy()#

Copy self.

Does not duplicate arrays in data content. See ncdata.utils.ncdata_copy().

property avals#

A convenience view of an NcData or NcVariable’s attribute values.

The .avals property acts as a more convenient view onto the .attributes, providing a simple “{name: value}” map.

( Meanwhile, the attributes are actually stored in the .attributes property, but this is a “{name: NcAttribute}” map ).

The values of the .avals map are the values of the .attributes, but converted to convenience forms, as described in NcAttribute.as_python_value().

get_attrval(name)#

Get the Python value of a named attribute in self.attributes.

If no such attribute exists, returns None.

Warning

This legacy method is now deprecated, and will be removed in a future release.

Parameters:: name (str)
Return type:: Any

set_attrval(name, value)#

Set the Python value of a named attribute in self.attributes.

Warning

This legacy method is now deprecated, and will be removed in a future release.

Parameters:: name (str)
Return type:: NcAttribute

class ncdata.NcAttribute#

Bases: object

An object representing a netcdf variable, group or dataset attribute.

Associates a name to a value which is always a numpy scalar or 1-D array, of an allowed dtype. See Attribute Values.

In an actual netcdf dataset, a “scalar” is actually just an array of length 1.

__init__(name, value)#

Parameters:: name (str)

name: str#: attribute name

property value#: attribute value, constrained to a suitable numpy array object.

as_python_value()#

Return the attribute value, converted for convenient use in Python code.

An array of one element returns as a single scalar value, since this is how attributes behave in actual netcdf data.

Single numeric values are returned as numpy scalars, i.e. integers or floats. The advantage of this is that they retain an exact dtype, e.g. np.int16 or np.float32, but are still mostly interchangeable with Python ints and floats.
A single string value is returned as a Python string object. See Attribute Values.
Multiple numeric values are returned as a 1-D numpy array (which is mostly interchangeable with a list).
Multiple strings are returned as a list of strings.

Note

However, an attribute in an actual NetCDF file cannot currently contain multiple strings, due to shortcomings in the netCDF implementation: they will be concatenated into a single string.

copy()#: Copy self, including any array value content.

class ncdata.NameMap#

Bases: dict

A specialised dictionary type for data manipulation convenience.

All values (aka ‘content items’) are expected to have a “.name” property which is a string, and we aim to ensure that “value.name == key” for each key, value pair.

This “item key relation” is not rigorously enforced, but we provide convenience methods which make use of it and help to maintain it : See NameMap.add(), NameMap.addall() NameMap.from_items() and NameMap.rename().

__init__(*args, item_type=None, **kwargs)#

Create a NameMap with dict-style constructor behaviour.

For example, from key/value pairs.

Notes

A keyword-only ‘item_type’ arg sets the ‘item_type’ property.

Creation using NameMap.from_items() is generally more convenient.

item_type#: expected type of all content items (if not None)

copy()#

Produce a new NameMap with same content and item_type.

Return type:: NameMap

add(item)#

Enter a content item under its ‘.name’.

If the NameMap has a non-None ‘item_type’, the added item is type checked.

addall(items)#: Add a number of content items with self.add().

rename(name, new_name)#

Rename a content item.

Parameters:

name (str) – name of an existing item. If not, a KeyError will occur.
new_name (str) – new name for the selected item. Both the container key and its “.name” will be changed.

Notes

The order of items is preserved.

If “new_name == name”, has no effect. Otherwise, if new_name already exists, the old item of that name is removed, but the renamed item remains in its original order place.

Examples

>>> mymap = NameMap.from_items([NcAttribute(x, x.upper()) for x in "abcd"])
>>> mymap
{'a': NcAttribute('a', 'A'), 'b': NcAttribute('b', 'B'), 'c': NcAttribute('c', 'C'), 'd': NcAttribute('d', 'D')}
>>> mymap.rename('b', 'qqq')
>>> mymap
{'a': NcAttribute('a', 'A'), 'qqq': NcAttribute('qqq', 'B'), 'c': NcAttribute('c', 'C'), 'd': NcAttribute('d', 'D')}
>>> mymap.rename('a', 'c')
>>> mymap
{'c': NcAttribute('c', 'A'), 'qqq': NcAttribute('qqq', 'B'), 'd': NcAttribute('d', 'D')}

classmethod from_items(arg, item_type=None)#

Convert an iterable or mapping of items to a NameMap.

Parameters:

arg (Iterable | Mapping) – an iterable or mapping of ‘content items’.
item_type – if not None, we expect all contents to be of this type.

Returns:

a NameMap with the given ‘item_type’

Return type:

map

Notes

All content items must have a “.name” property. If ‘item_type’ is not None, all items must be of the given type.

If ‘arg’ is an iterable, its contents are added.

If ‘arg’ is a mapping, it normally must have (key == arg[key].name) for all keys. As a special case, only if item_type == NcAttribute, a plain name: value map can be provided, which is converted to name: NcAttribute(name, value).

If ‘arg’’ is a NameMap of the same ‘item_type’ (including None), then ‘arg’ is returned unchanged as the result.

If the input is a NameMap of a different ‘item_type’, it is converted to a new NameMap of the required ‘item_type’ (assuming contents match the requirement).

classmethod __new__(*args, **kwargs)#

clear()#: Remove all items from the dict.

classmethod fromkeys(iterable, value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#: Return the value for key if key is in the dictionary, else default.

items()#: Return a set-like object providing a view on the dict’s items.

keys()#: Return a set-like object providing a view on the dict’s keys.

pop(k[, d]) → v, remove specified key and return the corresponding value.#: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from mapping/iterable E and F.#: If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()#: Return an object providing a view on the dict’s values.

Subpackages#

ncdata.utils package

ncdata package#

Subpackages#

Submodules#