You are viewing the latest unreleased documentation v3.2.dev0. You may prefer a stable version.

iris.fileformats.netcdf

Module to support the loading of a NetCDF file into an Iris cube.

See also: netCDF4 python

Also refer to document ‘NetCDF Climate and Forecast (CF) Metadata Conventions’.

In this module:

iris.fileformats.netcdf.load_cubes(filenames, callback=None, constraints=None)[source]

Loads cubes from a list of NetCDF filenames/URLs.

Args:

  • filenames (string/list):

    One or more NetCDF filenames/DAP URLs to load from.

Kwargs:

Returns

Generator of loaded NetCDF iris.cube.Cube.

↑ top ↑

iris.fileformats.netcdf.parse_cell_methods(nc_cell_methods)[source]

Parse a CF cell_methods attribute string into a tuple of zero or more CellMethod instances.

Args:

  • nc_cell_methods (str):

    The value of the cell methods attribute to be parsed.

Returns:

Multiple coordinates, intervals and comments are supported. If a method has a non-standard name a warning will be issued, but the results are not affected.

↑ top ↑

iris.fileformats.netcdf.save(cube, filename, netcdf_format='NETCDF4', local_keys=None, unlimited_dimensions=None, zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian='native', least_significant_digit=None, packing=None, fill_value=None)[source]

Save cube(s) to a netCDF file, given the cube and the filename.

  • Iris will write CF 1.7 compliant NetCDF files.

  • The attributes dictionaries on each cube in the saved cube list will be compared and common attributes saved as NetCDF global attributes where appropriate.

  • Keyword arguments specifying how to save the data are applied to each cube. To use different settings for different cubes, use the NetCDF Context manager (Saver) directly.

  • The save process will stream the data payload to the file using dask, enabling large data payloads to be saved and maintaining the ‘lazy’ status of the cube’s data payload, unless the netcdf_format is explicitly specified to be ‘NETCDF3’ or ‘NETCDF3_CLASSIC’.

Args:

Kwargs:

  • netcdf_format (string):

    Underlying netCDF file format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. Default is ‘NETCDF4’ format.

  • local_keys (iterable of strings):

    An interable of cube attribute keys. Any cube attributes with matching keys will become attributes on the data variable rather than global attributes.

  • unlimited_dimensions (iterable of strings and/or
    iris.coords.Coord objects):

    List of coordinate names (or coordinate objects) corresponding to coordinate dimensions of cube to save with the NetCDF dimension variable length ‘UNLIMITED’. By default, no unlimited dimensions are saved. Only the ‘NETCDF4’ format supports multiple ‘UNLIMITED’ dimensions.

  • zlib (bool):

    If True, the data will be compressed in the netCDF file using gzip compression (default False).

  • complevel (int):

    An integer between 1 and 9 describing the level of compression desired (default 4). Ignored if zlib=False.

  • shuffle (bool):

    If True, the HDF5 shuffle filter will be applied before compressing the data (default True). This significantly improves compression. Ignored if zlib=False.

  • fletcher32 (bool):

    If True, the Fletcher32 HDF5 checksum algorithm is activated to detect errors. Default False.

  • contiguous (bool):

    If True, the variable data is stored contiguously on disk. Default False. Setting to True for a variable with an unlimited dimension will trigger an error.

  • chunksizes (tuple of int):

    Used to manually specify the HDF5 chunksizes for each dimension of the variable. A detailed discussion of HDF chunking and I/O performance is available here: https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/netcdf_perf_chunking.html. Basically, you want the chunk size for each dimension to match as closely as possible the size of the data block that users will read from the file. chunksizes cannot be set if contiguous=True.

  • endian (string):

    Used to control whether the data is stored in little or big endian format on disk. Possible values are ‘little’, ‘big’ or ‘native’ (default). The library will automatically handle endian conversions when the data is read, but if the data is always going to be read on a computer with the opposite format as the one used to create the file, there may be some performance advantage to be gained by setting the endian-ness.

  • least_significant_digit (int):

    If least_significant_digit is specified, variable data will be truncated (quantized). In conjunction with zlib=True this produces ‘lossy’, but significantly more efficient compression. For example, if least_significant_digit=1, data will be quantized using numpy.around(scale*data)/scale, where scale = 2**bits, and bits is determined so that a precision of 0.1 is retained (in this case bits=4). From http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml: “least_significant_digit – power of ten of the smallest decimal place in unpacked data that is a reliable value”. Default is None, or no quantization, or ‘lossless’ compression.

  • packing (type or string or dict or list): A numpy integer datatype

    (signed or unsigned) or a string that describes a numpy integer dtype (i.e. ‘i2’, ‘short’, ‘u4’) or a dict of packing parameters as described below or an iterable of such types, strings, or dicts. This provides support for netCDF data packing as described in https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/best_practices.html#bp_Packed-Data-Values If this argument is a type (or type string), appropriate values of scale_factor and add_offset will be automatically calculated based on cube.data and possible masking. For more control, pass a dict with one or more of the following keys: dtype (required), scale_factor and add_offset. Note that automatic calculation of packing parameters will trigger loading of lazy data; set them manually using a dict to avoid this. The default is None, in which case the datatype is determined from the cube and no packing will occur. If this argument is a list it must have the same number of elements as cube if cube is a :class:`iris.cube.CubeList, or one element, and each element of this argument will be applied to each cube separately.

  • fill_value (numeric or list):

    The value to use for the _FillValue attribute on the netCDF variable. If packing is specified the value of fill_value should be in the domain of the packed data. If this argument is a list it must have the same number of elements as cube if cube is a :class:`iris.cube.CubeList, or a single element, and each element of this argument will be applied to each cube separately.

Returns

None.

Note

The zlib, complevel, shuffle, fletcher32, contiguous, chunksizes and endian keywords are silently ignored for netCDF 3 files that do not use HDF5.

See also

NetCDF Context manager (Saver).

↑ top ↑

Provide a simple CF name to CF coordinate mapping.

class iris.fileformats.netcdf.CFNameCoordMap[source]

Provide a simple CF name to CF coordinate mapping.

append(name, coord)[source]

Append the given name and coordinate pair to the mapping.

Args:

  • name:

    CF name of the associated coordinate.

  • coord:

    The coordinate of the associated CF name.

Returns

None.

coord(name)[source]

Return the coordinate, given a CF name, or None if not recognised.

Args:

  • name:

    CF name of the associated coordinate, or None if not recognised.

Returns

CF name or None.

name(coord)[source]

Return the CF name, given a coordinate, or None if not recognised.

Args:

  • coord:

    The coordinate of the associated CF name.

Returns

Coordinate or None.

property coords

Return all the coordinates.

property names

Return all the CF names.

↑ top ↑

A reference to the data payload of a single NetCDF file variable.

class iris.fileformats.netcdf.NetCDFDataProxy(shape, dtype, path, variable_name, fill_value)[source]

A reference to the data payload of a single NetCDF file variable.

dtype
fill_value
property ndim
path
shape
variable_name

↑ top ↑

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

class iris.fileformats.netcdf.OrderedAddableList(*args, **kwargs)[source]
add(msg)[source]
append(object, /)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)

Insert object before index.

pop(index=- 1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

↑ top ↑

A manager for saving netcdf files.

class iris.fileformats.netcdf.Saver(filename, netcdf_format)[source]

A manager for saving netcdf files.

Args:

  • filename (string):

    Name of the netCDF file to save the cube.

  • netcdf_format (string):

    Underlying netCDF file format, one of ‘NETCDF4’, ‘NETCDF4_CLASSIC’, ‘NETCDF3_CLASSIC’ or ‘NETCDF3_64BIT’. Default is ‘NETCDF4’ format.

Returns

None.

For example:

# Initialise Manager for saving
with Saver(filename, netcdf_format) as sman:
    # Iterate through the cubelist.
    for cube in cubes:
        sman.write(cube)
__exit__(type, value, traceback)[source]

Flush any buffered data to the CF-netCDF file before closing.

static cf_valid_var_name(var_name)[source]

Return a valid CF var_name given a potentially invalid name.

Args:

  • var_name (str):

    The var_name to normalise

Returns

A var_name suitable for passing through for variable creation.

static check_attribute_compliance(container, data_dtype)[source]
update_global_attributes(attributes=None, **kwargs)[source]

Update the CF global attributes based on the provided iterable/dictionary and/or keyword arguments.

Args:

  • attributes (dict or iterable of key, value pairs):

    CF global attributes to be updated.

write(cube, local_keys=None, unlimited_dimensions=None, zlib=False, complevel=4, shuffle=True, fletcher32=False, contiguous=False, chunksizes=None, endian='native', least_significant_digit=None, packing=None, fill_value=None)[source]

Wrapper for saving cubes to a NetCDF file.

Args:

Kwargs:

  • local_keys (iterable of strings):

    An interable of cube attribute keys. Any cube attributes with matching keys will become attributes on the data variable rather than global attributes.

  • unlimited_dimensions (iterable of strings and/or
    iris.coords.Coord objects):

    List of coordinate names (or coordinate objects) corresponding to coordinate dimensions of cube to save with the NetCDF dimension variable length ‘UNLIMITED’. By default, no unlimited dimensions are saved. Only the ‘NETCDF4’ format supports multiple ‘UNLIMITED’ dimensions.

  • zlib (bool):

    If True, the data will be compressed in the netCDF file using gzip compression (default False).

  • complevel (int):

    An integer between 1 and 9 describing the level of compression desired (default 4). Ignored if zlib=False.

  • shuffle (bool):

    If True, the HDF5 shuffle filter will be applied before compressing the data (default True). This significantly improves compression. Ignored if zlib=False.

  • fletcher32 (bool):

    If True, the Fletcher32 HDF5 checksum algorithm is activated to detect errors. Default False.

  • contiguous (bool):

    If True, the variable data is stored contiguously on disk. Default False. Setting to True for a variable with an unlimited dimension will trigger an error.

  • chunksizes (tuple of int):

    Used to manually specify the HDF5 chunksizes for each dimension of the variable. A detailed discussion of HDF chunking and I/O performance is available here: https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/netcdf_perf_chunking.html. Basically, you want the chunk size for each dimension to match as closely as possible the size of the data block that users will read from the file. chunksizes cannot be set if contiguous=True.

  • endian (string):

    Used to control whether the data is stored in little or big endian format on disk. Possible values are ‘little’, ‘big’ or ‘native’ (default). The library will automatically handle endian conversions when the data is read, but if the data is always going to be read on a computer with the opposite format as the one used to create the file, there may be some performance advantage to be gained by setting the endian-ness.

  • least_significant_digit (int):

    If least_significant_digit is specified, variable data will be truncated (quantized). In conjunction with zlib=True this produces ‘lossy’, but significantly more efficient compression. For example, if least_significant_digit=1, data will be quantized using numpy.around(scale*data)/scale, where scale = 2**bits, and bits is determined so that a precision of 0.1 is retained (in this case bits=4). From http://www.esrl.noaa.gov/psd/data/gridded/conventions/cdc_netcdf_standard.shtml: “least_significant_digit – power of ten of the smallest decimal place in unpacked data that is a reliable value”. Default is None, or no quantization, or ‘lossless’ compression.

  • packing (type or string or dict or list): A numpy integer datatype

    (signed or unsigned) or a string that describes a numpy integer dtype(i.e. ‘i2’, ‘short’, ‘u4’) or a dict of packing parameters as described below. This provides support for netCDF data packing as described in https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/best_practices.html#bp_Packed-Data-Values If this argument is a type (or type string), appropriate values of scale_factor and add_offset will be automatically calculated based on cube.data and possible masking. For more control, pass a dict with one or more of the following keys: dtype (required), scale_factor and add_offset. Note that automatic calculation of packing parameters will trigger loading of lazy data; set them manually using a dict to avoid this. The default is None, in which case the datatype is determined from the cube and no packing will occur.

  • fill_value:

    The value to use for the _FillValue attribute on the netCDF variable. If packing is specified the value of fill_value should be in the domain of the packed data.

Returns

None.

Note

The zlib, complevel, shuffle, fletcher32, contiguous, chunksizes and endian keywords are silently ignored for netCDF 3 files that do not use HDF5.

↑ top ↑

Base class for warning categories.

class iris.fileformats.netcdf.UnknownCellMethodWarning[source]
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args