iris.fileformats.cf

Provide capability to load netCDF files and interpret them.

Provides the capability to load netCDF files and interpret them according to the ‘NetCDF Climate and Forecast (CF) Metadata Conventions’.

References

[CF] NetCDF Climate and Forecast (CF) Metadata conventions. [NUG] NetCDF User’s Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/

class iris.fileformats.cf.CFAncillaryDataVariable(name, data)

Bases: CFVariable

CF-netCDF ancillary data variable.

A CF-netCDF ancillary data variable is a variable that provides metadata about the individual values of another data variable.

Identified by the CF-netCDF variable attribute ‘ancillary_variables’.

Ref: [CF] Section 3.4. Ancillary Data.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'ancillary_variables'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFAuxiliaryCoordinateVariable(name, data)

Bases: CFVariable

CF-netCDF auxiliary coordinate variable.

A CF-netCDF auxiliary coordinate variable is any netCDF variable that contains coordinate data, but is not a CF-netCDF coordinate variable by definition.

There is no relationship between the name of a CF-netCDF auxiliary coordinate variable and the name(s) of its dimension(s).

Identified by the CF-netCDF variable attribute ‘coordinates’. Also see iris.fileformats.cf.CFLabelVariable.

Ref:

• [CF] Chapter 5. Coordinate Systems.

• [CF] Section 6.2. Alternative Coordinates.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'coordinates'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFBoundaryVariable(name, data)

Bases: CFVariable

CF-netCDF boundary variable.

A CF-netCDF boundary variable is associated with a CF-netCDF variable that contains coordinate data. When a data value provides information about conditions in a cell occupying a region of space/time or some other dimension, the boundary variable provides a description of cell extent.

A CF-netCDF boundary variable will have one more dimension than its associated CF-netCDF coordinate variable or CF-netCDF auxiliary coordinate variable.

Identified by the CF-netCDF variable attribute ‘bounds’.

Ref: [CF] Section 7.1. Cell Boundaries.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'bounds'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFClimatologyVariable(name, data)

Bases: CFVariable

CF-netCDF climatology variable.

A CF-netCDF climatology variable is associated with a CF-netCDF variable that contains coordinate data. When a data value provides information about conditions in a cell occupying a region of space/time or some other dimension, the climatology variable provides a climatological description of cell extent.

A CF-netCDF climatology variable will have one more dimension than its associated CF-netCDF coordinate variable.

Identified by the CF-netCDF variable attribute ‘climatology’.

Ref: [CF] Section 7.4. Climatological Statistics

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'climatology'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable (CFVariable) – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFCoordinateVariable(name, data)

Bases: CFVariable

A CF-netCDF coordinate variable.

A CF-netCDF coordinate variable is a one-dimensional variable with the same name as its dimension, and it is defined as a numeric data type with values that are ordered monotonically. Missing values are not allowed in CF-netCDF coordinate variables. Also see [NUG] Section 2.3.1.

Identified by the above criterion, there is no associated CF-netCDF variable attribute.

Ref: [CF] 1.2. Terminology.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = None

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True, monotonic=False)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFDataVariable(name, data)

Bases: CFVariable

A CF-netCDF variable containing data pay-load that maps to an Iris iris.cube.Cube.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = None

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFGridMappingVariable(name, data)

Bases: CFVariable

CF-netCDF grid mapping variable.

A CF-netCDF grid mapping variable contains a list of specific attributes that define a particular grid mapping. A CF-netCDF grid mapping variable must contain the attribute ‘grid_mapping_name’.

Based on the value of the ‘grid_mapping_name’ attribute, there are associated standard names of CF-netCDF coordinate variables that contain the mapping’s independent variables.

Identified by the CF-netCDF variable attribute ‘grid_mapping’.

Ref:

• [CF] Section 5.6. Horizontal Coordinate Reference Systems, Grid Mappings, and Projections.

• [CF] Appendix F. Grid Mappings.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'grid_mapping'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFGroup

Bases: MutableMapping

Collection of ‘NetCDF CF Metadata Conventions variables and netCDF global attributes.

Represents a collection of ‘NetCDF Climate and Forecast (CF) Metadata Conventions’ variables and netCDF global attributes.

property ancillary_variables

Collection of CF-netCDF ancillary variables.

property auxiliary_coordinates

Collection of CF-netCDF auxiliary coordinate variables.

property bounds

Collection of CF-netCDF boundary variables.

property cell_measures

Collection of CF-netCDF measure variables.

clear() → None.  Remove all items from D.

property climatology

Collection of CF-netCDF climatology variables.

property connectivities

Collection of CF-UGRID connectivity variables.

property coordinates

Collection of CF-netCDF coordinate variables.

property data_variables

Collection of CF-netCDF data pay-load variables.

property formula_terms

Collection of CF-netCDF variables that participate in a CF-netCDF formula term.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

global_attributes

Collection of netCDF global attributes

property grid_mappings

Collection of CF-netCDF grid mapping variables.

items() → a set-like object providing a view on D's items

keys()

Return the names of all the CF-netCDF variables in the group.

property labels

Collection of CF-netCDF label variables.

property meshes

Collection of CF-UGRID mesh variables.

property non_data_variable_names

set names of the CF-netCDF variables that are not the data pay-load.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

promoted

Collection of CF-netCDF variables promoted to a CFDataVariable.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

property ugrid_coords

Collection of CF-UGRID-relevant auxiliary coordinate variables.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

class iris.fileformats.cf.CFLabelVariable(name, data)

Bases: CFVariable

Cariable is any netCDF variable that contain string textual information, or labels.

A CF-netCDF CF label variable is any netCDF variable that contain string textual information, or labels.

Identified by the CF-netCDF variable attribute ‘coordinates’. Also see iris.fileformats.cf.CFAuxiliaryCoordinateVariable.

Ref: [CF] Section 6.1. Labels.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'coordinates'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_label_data(cf_data_var)

Return the associated CF-netCDF label variable strings.

Parameters:

cf_data_var (iris.fileformats.cf.CFDataVariable) – The CF-netCDF data variable which the CF-netCDF label variable describes.

Return type:

str labels

cf_label_dimensions(cf_data_var)

Return the name of the associated CF-netCDF label variable data dimensions.

Parameters:

cf_data_var (iris.fileformats.cf.CFDataVariable) – The CF-netCDF data variable which the CF-netCDF label variable describes.

Return type:

Tuple of label data dimension names.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFMeasureVariable(name, data, measure)

Bases: CFVariable

A CF-netCDF measure variable is a variable that contains cell areas or volumes.

Identified by the CF-netCDF variable attribute ‘cell_measures’.

Ref: [CF] Section 7.2. Cell Measures.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'cell_measures'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_measure

Associated cell measure of the cell variable

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFReader(file_source, warn=False, monotonic=False)

Bases: object

Allows the contents of a netCDF file to be interpreted.

This class allows the contents of a netCDF file to be interpreted according to the ‘NetCDF Climate and Forecast (CF) Metadata Conventions’.

class CFGroup

Bases: MutableMapping

Collection of ‘NetCDF CF Metadata Conventions variables and netCDF global attributes.

Represents a collection of ‘NetCDF Climate and Forecast (CF) Metadata Conventions’ variables and netCDF global attributes.

property ancillary_variables

Collection of CF-netCDF ancillary variables.

property auxiliary_coordinates

Collection of CF-netCDF auxiliary coordinate variables.

property bounds

Collection of CF-netCDF boundary variables.

property cell_measures

Collection of CF-netCDF measure variables.

clear() → None.  Remove all items from D.

property climatology

Collection of CF-netCDF climatology variables.

property connectivities

Collection of CF-UGRID connectivity variables.

property coordinates

Collection of CF-netCDF coordinate variables.

property data_variables

Collection of CF-netCDF data pay-load variables.

property formula_terms

Collection of CF-netCDF variables that participate in a CF-netCDF formula term.

get(k[, d]) → D[k] if k in D, else d.  d defaults to None.

global_attributes

Collection of netCDF global attributes

property grid_mappings

Collection of CF-netCDF grid mapping variables.

items() → a set-like object providing a view on D's items

keys()

Return the names of all the CF-netCDF variables in the group.

property labels

Collection of CF-netCDF label variables.

property meshes

Collection of CF-UGRID mesh variables.

property non_data_variable_names

set names of the CF-netCDF variables that are not the data pay-load.

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

promoted

Collection of CF-netCDF variables promoted to a CFDataVariable.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

property ugrid_coords

Collection of CF-UGRID-relevant auxiliary coordinate variables.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → an object providing a view on D's values

cf_group

Collection of CF-netCDF variables associated with this netCDF file

property filename

The file that the CFReader is reading.

class iris.fileformats.cf.CFUGridAuxiliaryCoordinateVariable(name, data)

Bases: CFVariable

A CF-UGRID auxiliary coordinate variable.

A CF-UGRID auxiliary coordinate variable is a CF-netCDF auxiliary coordinate variable representing the element (node/edge/face/volume) locations (latitude, longitude or other spatial coordinates, and optional elevation or other coordinates). These auxiliary coordinate variables will have length n-elements.

For elements other than nodes, these auxiliary coordinate variables may have in turn a bounds attribute that specifies the bounding coordinates of the element (thereby duplicating the data in the node_coordinates variables).

Identified by the CF-netCDF variable attribute node_/edge_/face_/volume_coordinates.

See also

The UGRID Conventions, https://ugrid-conventions.github.io/ugrid-conventions/

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identities = ['node_coordinates', 'edge_coordinates', 'face_coordinates', 'volume_coordinates']

cf_identity: ClassVar[str | None] = NotImplemented

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFUGridConnectivityVariable(name, data)

Bases: CFVariable

A CF_UGRID connectivity variable.

A CF_UGRID connectivity variable points to an index variable identifying for every element (edge/face/volume) the indices of its corner nodes. The connectivity array will thus be a matrix of size n-elements x n-corners. For the indexing one may use either 0- or 1-based indexing; the convention used should be specified using a start_index attribute to the index variable.

For face elements: the corner nodes should be specified in anticlockwise direction as viewed from above. For volume elements: use the additional attribute volume_shape_type which points to a flag variable that specifies for every volume its shape.

Identified by a CF-netCDF variable attribute equal to any one of the values in UGRID_CF_ROLES.

See also

The UGRID Conventions, https://ugrid-conventions.github.io/ugrid-conventions/

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identities = ['edge_node_connectivity', 'face_node_connectivity', 'face_edge_connectivity', 'face_face_connectivity', 'edge_face_connectivity', 'boundary_node_connectivity', 'volume_node_connectivity', 'volume_edge_connectivity', 'volume_face_connectivity', 'volume_volume_connectivity']

cf_identity: ClassVar[str | None] = NotImplemented

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFUGridMeshVariable(name, data)

Bases: CFVariable

A CF-UGRID mesh variable is a dummy variable for storing topology information as attributes.

A CF-UGRID mesh variable is a dummy variable for storing topology information as attributes. The mesh variable has the cf_role ‘mesh_topology’.

The UGRID conventions describe define the mesh topology as the interconnection of various geometrical elements of the mesh. The pure interconnectivity is independent of georeferencing the individual geometrical elements, but for the practical applications for which the UGRID CF extension is defined, coordinate data will always be added.

Identified by the CF-netCDF variable attribute ‘mesh’.

See also

The UGRID Conventions, https://ugrid-conventions.github.io/ugrid-conventions/

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = 'mesh'

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

classmethod identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

class iris.fileformats.cf.CFVariable(name, data)

Bases: object

Abstract base class wrapper for a CF-netCDF variable.

add_formula_term(root, term)

Register the participation of this CF-netCDF variable in a CF-netCDF formula term.

Parameters:

• root (str) – The name of CF-netCDF variable that defines the CF-netCDF formula_terms attribute.

• term (str) – The associated term name of this variable in the formula_terms definition.

Return type:

None

cf_attrs()

Return a list of all attribute name and value pairs of the CF-netCDF variable.

cf_attrs_ignored()

Return a list of all ignored attribute name and value pairs of the CF-netCDF variable.

cf_attrs_reset()

Reset the history of accessed attribute names of the CF-netCDF variable.

cf_attrs_unused()

Return a list of all non-accessed attribute name and value pairs of the CF-netCDF variable.

cf_attrs_used()

Return a list of all accessed attribute name and value pairs of the CF-netCDF variable.

cf_data

NetCDF4 Variable data instance.

cf_group

Collection of CF-netCDF variables associated with this variable.

cf_identity: ClassVar[str | None] = None

Name of the netCDF variable attribute that identifies this CF-netCDF variable.

cf_name

NetCDF variable name.

cf_terms_by_root

CF-netCDF formula terms that his variable participates in.

has_formula_terms()

Determine whether this CF-netCDF variable participates in a CF-netcdf formula term.

Return type:

bool

abstract identify(variables, ignore=None, target=None, warn=True)

Identify all variables that match the criterion for this CF-netCDF variable class.

Parameters:

• variables – Dictionary of netCDF4.Variable instance by variable name.

• ignore (optional) – List of variable names to ignore.

• target (optional) – Name of a single variable to check.

• warn (bool, default=True) – Issue a warning if a missing variable is referenced.

Return type:

Dictionary of CFVariable instance by variable name.

spans(cf_variable)

Determine dimensionality coverage.

Determine whether the dimensionality of this variable is a subset of the specified target variable.

Note that, by default scalar variables always span the dimensionality of the target variable.

Parameters:

cf_variable – Compare dimensionality with the CFVariable.

Return type:

bool

iris.fileformats.cf.reference_terms = {'atmosphere_hybrid_height_coordinate': ['orog'], 'atmosphere_hybrid_sigma_pressure_coordinate': ['ps'], 'atmosphere_sigma_coordinate': ['ps'], 'atmosphere_sleve_coordinate': ['zsurf1', 'zsurf2'], 'ocean_s_coordinate': ['eta', 'depth'], 'ocean_s_coordinate_g1': ['eta', 'depth'], 'ocean_s_coordinate_g2': ['eta', 'depth'], 'ocean_sigma_coordinate': ['eta', 'depth'], 'ocean_sigma_z_coordinate': ['eta', 'depth']}

Supported dimensionless vertical coordinate reference surface/phemomenon formula terms. Ref: [CF] Appendix D.