iris.fileformats.netcdf#

Module to support the loading and saving of NetCDF files, also using the CF conventions for metadata interpretation.

See : NetCDF User’s Guide and netCDF4 python module.

Also : CF Conventions.

In this module:

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 ↑

iris.fileformats.netcdf.CF_CONVENTIONS_VERSION#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

↑ top ↑

iris.fileformats.netcdf.DEBUG#

bool(x) -> bool

Returns True when the argument x is true, False otherwise. The builtins True and False are the only two instances of the class bool. The class bool is a subclass of the class int, and cannot be subclassed.

↑ top ↑

iris.fileformats.netcdf.MESH_ELEMENTS#

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

↑ 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 ↑

iris.fileformats.netcdf.SPATIO_TEMPORAL_AXES#

Built-in mutable sequence.

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

↑ 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#

↑ top ↑

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

Loads cubes from a list of NetCDF filenames/OPeNDAP URLs.

Args:

  • filenames (string/list):

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

Kwargs:

Returns

Generator of loaded NetCDF iris.cube.Cube.

↑ top ↑

iris.fileformats.netcdf.logger#

Instances of the Logger class represent a single logging channel. A “logging channel” indicates an area of an application. Exactly how an “area” is defined is up to the application developer. Since an application can have any number of areas, logging channels are identified by a unique string. Application areas can be nested (e.g. an area of “input processing” might include sub-areas “read CSV files”, “read XLS files” and “read Gnumeric files”). To cater for this natural nesting, channel names are organized into a namespace hierarchy where levels are separated by periods, much like the Java or Python package namespace. So in the instance given above, channel names might be “input” for the upper level, and “input.csv”, “input.xls” and “input.gnu” for the sub-levels. There is no arbitrary limit to the depth of nesting.

↑ 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).

previous

iris.fileformats.name_loaders

next

iris.fileformats.netcdf.loader