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

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:

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:

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 to long_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.

xml_element(doc)[source]

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.

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

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.

↑ top ↑

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:

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:

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 to long_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.