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)[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:
- callback (callable function):
Function which can be passed on to
iris.io.run_callback()
.
- Returns
Generator of loaded NetCDF
iris.cubes.Cube
.
-
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:
- cell_methods
An iterable of
iris.coords.CellMethod
.
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.
-
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:
- cube (
iris.cube.Cube
oriris.cube.CubeList
): A
iris.cube.Cube
,iris.cube.CubeList
or other iterable of cubes to be saved to a netCDF file.
- cube (
- filename (string):
Name of the netCDF file to save the cube(s).
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 http://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.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
).
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.
Args:
- name:
CF name of the associated coordinate.
- Returns
CF name.
name
(coord)[source]¶Return the CF name, given a coordinate
Args:
- coord:
The coordinate of the associated CF name.
- Returns
Coordinate.
- property
coords
¶Return all the coordinates.
- property
names
¶Return all the CF names.
A reference to the data payload of a single NetCDF file variable.
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.
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:
- cube (
iris.cube.Cube
):A
iris.cube.Cube
to be saved to a netCDF file.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 http://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.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.
Base class for warning categories.