iris.aux_factory¶
Definitions of derived coordinates.
In this module:
Represents a “factory” which can manufacture an additional auxiliary coordinate on demand, by combining the values of other coordinates.
Each concrete subclass represents a specific formula for deriving values from other coordinates.
The standard_name, long_name, var_name, units, attributes and coord_system of the factory are used to set the corresponding properties of the resulting auxiliary coordinates.
- class
iris.aux_factory.
AuxCoordFactory
[source]¶Represents a “factory” which can manufacture an additional auxiliary coordinate on demand, by combining the values of other coordinates.
Each concrete subclass represents a specific formula for deriving values from other coordinates.
The standard_name, long_name, var_name, units, attributes and coord_system of the factory are used to set the corresponding properties of the resulting auxiliary coordinates.
derived_dims
(coord_dims_func)[source]¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
- abstract
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
- abstract
update
(old_coord, new_coord=None)[source]¶Notifies the factory of a removal/replacement of a dependency.
Args:
- old_coord:
The dependency coordinate to be removed/replaced.
- new_coord:
If None, the dependency using old_coord is removed, otherwise the dependency is updated to use new_coord.
updated
(new_coord_mapping)[source]¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- abstract property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶Descriptive name of the coordinate made by the factory
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶netCDF variable name for the coordinate made by the factory
- Defines a hybrid-height coordinate factory with the formula:
z = a + b * orog
- class
iris.aux_factory.
HybridHeightFactory
(delta=None, sigma=None, orography=None)[source]¶
- Creates a hybrid-height coordinate factory with the formula:
z = a + b * orog
At least one of delta or orography must be provided.
Args:
- delta: Coord
The coordinate providing the a term.
- sigma: Coord
The coordinate providing the b term.
- orography: Coord
The coordinate providing the orog term.
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
- Defines a hybrid-pressure coordinate factory with the formula:
p = ap + b * ps
- class
iris.aux_factory.
HybridPressureFactory
(delta=None, sigma=None, surface_air_pressure=None)[source]¶
- Creates a hybrid-height coordinate factory with the formula:
p = ap + b * ps
At least one of delta or surface_air_pressure must be provided.
Args:
- delta: Coord
The coordinate providing the ap term.
- sigma: Coord
The coordinate providing the b term.
- surface_air_pressure: Coord
The coordinate providing the ps term.
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
Defines an Ocean s-coordinate factory.
- class
iris.aux_factory.
OceanSFactory
(s=None, eta=None, depth=None, a=None, b=None, depth_c=None)[source]¶Creates an Ocean s-coordinate factory with the formula:
- z(n,k,j,i) = eta(n,j,i)*(1+s(k)) + depth_c*s(k) +
(depth(j,i)-depth_c)*C(k)
- where:
- C(k) = (1-b) * sinh(a*s(k)) / sinh(a) +
b * [tanh(a * (s(k) + 0.5)) / (2 * tanh(0.5*a)) - 0.5]
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
Defines an Ocean s-coordinate, generic form 1 factory.
- class
iris.aux_factory.
OceanSg1Factory
(s=None, c=None, eta=None, depth=None, depth_c=None)[source]¶Creates an Ocean s-coordinate, generic form 1 factory with the formula:
z(n,k,j,i) = S(k,j,i) + eta(n,j,i) * (1 + S(k,j,i) / depth(j,i))
- where:
S(k,j,i) = depth_c * s(k) + (depth(j,i) - depth_c) * C(k)
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
Defines an Ocean s-coordinate, generic form 2 factory.
- class
iris.aux_factory.
OceanSg2Factory
(s=None, c=None, eta=None, depth=None, depth_c=None)[source]¶Creates an Ocean s-coordinate, generic form 2 factory with the formula:
z(n,k,j,i) = eta(n,j,i) + (eta(n,j,i) + depth(j,i)) * S(k,j,i)
- where:
- S(k,j,i) = (depth_c * s(k) + depth(j,i) * C(k)) /
(depth_c + depth(j,i))
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
Defines an ocean sigma coordinate factory.
- class
iris.aux_factory.
OceanSigmaFactory
(sigma=None, eta=None, depth=None)[source]¶Creates an ocean sigma coordinate factory with the formula:
- z(n, k, j, i) = eta(n, j, i) + sigma(k) *
(depth(j, i) + eta(n, j, i))
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.
Defines an ocean sigma over z coordinate factory.
- class
iris.aux_factory.
OceanSigmaZFactory
(sigma=None, eta=None, depth=None, depth_c=None, nsigma=None, zlev=None)[source]¶Creates an ocean sigma over z coordinate factory with the formula:
- if k < nsigma:
- z(n, k, j, i) = eta(n, j, i) + sigma(k) *
(min(depth_c, depth(j, i)) + eta(n, j, i))
- if k >= nsigma:
z(n, k, j, i) = zlev(k)
The zlev and ‘nsigma’ coordinates must be provided, and at least either eta, or ‘sigma’ and depth and depth_c coordinates.
derived_dims
(coord_dims_func)¶Returns the cube dimensions for the derived coordinate.
Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
- Returns
A sorted list of cube dimension numbers.
make_coord
(coord_dims_func)[source]¶Returns a new
iris.coords.AuxCoord
as defined by this factory.Args:
- coord_dims_func:
A callable which can return the list of dimensions relevant to a given coordinate. See
iris.cube.Cube.coord_dims()
.
name
(default=None, token=False)¶Returns a string name representing the identity of the metadata.
First it tries standard name, then it tries the long name, then the NetCDF variable name, before falling-back to a default value, which itself defaults to the string ‘unknown’.
Kwargs:
- default:
The fall-back string representing the default name. Defaults to the string ‘unknown’.
- token:
If True, ensures that the name returned satisfies the criteria for the characters required by a valid NetCDF name. If it is not possible to return a valid name, then a ValueError exception is raised. Defaults to False.
- Returns
String.
rename
(name)¶Changes the human-readable name.
If ‘name’ is a valid standard name it will assign it to
standard_name
, otherwise it will assign it tolong_name
.
update
(old_coord, new_coord=None)[source]¶Notifies the factory of the removal/replacement of a coordinate which might be a dependency.
Args:
- old_coord:
The coordinate to be removed/replaced.
- new_coord:
If None, any dependency using old_coord is removed, otherwise any dependency using old_coord is updated to use new_coord.
updated
(new_coord_mapping)¶Creates a new instance of this factory where the dependencies are replaced according to the given mapping.
Args:
- new_coord_mapping:
A dictionary mapping from the object IDs potentially used by this factory, to the coordinate objects that should be used instead.
xml_element
(doc)¶Returns a DOM element describing this coordinate factory.
- property
attributes
¶
- property
climatological
¶Always returns False, as a factory itself can never have points/bounds and therefore can never be climatological by definition.
- property
coord_system
¶The coordinate-system (if any) of the coordinate made by the factory.
- property
dependencies
¶Returns a dictionary mapping from constructor argument names to the corresponding coordinates.
- property
long_name
¶The CF Metadata long name for the object.
- property
metadata
¶
- property
standard_name
¶The CF Metadata standard name for the object.
- property
units
¶The S.I. unit of the object.
- property
var_name
¶The NetCDF variable name for the object.