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)#
- dimensions: Dict[str, NcDimension]#
group/dataset dimensions
- variables: Dict[str, NcVariable]#
group/dataset variables
- attributes: Dict[str, NcAttribute]#
group/dataset global attributes
- copy()#
Copy self.
This duplicates structure with all-new ncdata core objects, but does not duplicate variable data arrays. See
ncdata.utils.ncdata_copy()
.
- get_attrval(name)#
Get the Python value of a named attribute in self.attributes.
If no such attribute exists, returns None.
- Parameters:
name (str)
- class ncdata.NcDimension#
Bases:
object
An object representing a netcdf dimension.
Associates a name with a length, and also an ‘unlimited’ flag.
- 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’.
- data#
variable data (an array-like, typically a dask or numpy array)
- copy()#
Copy self.
Does not duplicate arrays in data content. See
ncdata.utils.ncdata_copy()
.
- get_attrval(name)#
Get the Python value of a named attribute in self.attributes.
If no such attribute exists, returns None.
- Parameters:
name (str)
- class ncdata.NcAttribute#
Bases:
object
An object representing a netcdf variable or dataset attribute.
Associates a name to a value which is a numpy scalar or 1-D array.
We expect the value to be 0- or 1-dimensional, and an allowed dtype. However none of this is checked.
In an actual netcdf dataset, a “scalar” is actually just an array of length 1.
- property value#
attribute value
- as_python_value()#
Return the content, but converting any character data to Python strings.
An array of 1 value returns as a single scalar value, since this is how attributes behave in actual netcdf data.
We don’t bother converting numeric data, since numpy scalars are generally interchangeable in use with Python ints or floats.
- 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()
andNameMap.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)
- 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:
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:
- 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).
- __new__(**kwargs)#
- clear() None. Remove all items from D. #
- fromkeys(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() a set-like object providing a view on D's items #
- keys() a set-like object providing a view on D'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() an object providing a view on D's values #