Ctrl+K

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.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 must have (key == arg[key].name) for all keys.

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 dict/iterable E and F.#

If E is present and has a .keys() method, then does: for k in E: 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#
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.

__init__(name, value)#
Parameters:

name (str) –

name: str#

attribute name

value: ndarray#

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.

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#

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

get_attrval(name)#

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

If no such attribute exists, returns None.

Parameters:

name (str) –

set_attrval(name, value)#

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

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

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#

variable name

dimensions: Tuple[str]#

variable dimension names (a list of strings, not a dict of objects)

data#

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

attributes: NameMap#

variable attributes

group: NcData | None#

parent group

get_attrval(name)#

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

If no such attribute exists, returns None.

Parameters:

name (str) –

set_attrval(name, value)#

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

Parameters:

name (str) –

Return type:

NcAttribute

Subpackages#

Submodules#

On this page
Show Source