iris.analysis.maths#

Basic mathematical and statistical operations.

class iris.analysis.maths.IFunc(data_func, units_func)[source]#

Bases: object

IFunc class for functions that can be applied to an iris cube.

Create an ifunc from a data function and units function.

Parameters:

data_func – Function to be applied to one or two data arrays, which are given as positional arguments. Should return another data array, with the same shape as the first array. May also have keyword arguments.
units_func – Function to calculate the units of the resulting cube. Should take the cube/s as input and return an instance of cf_units.Unit.

Return type:

ifunc

Examples

Example usage 1 Using an existing numpy ufunc, such as numpy.sin for the data function and a simple lambda function for the units function:

sine_ifunc = iris.analysis.maths.IFunc(
    numpy.sin, lambda cube: cf_units.Unit('1'))
sine_cube = sine_ifunc(cube)

Example usage 2 Define a function for the data arrays of two cubes and define a units function that checks the units of the cubes for consistency, before giving the resulting cube the same units as the first cube:

def ws_data_func(u_data, v_data):
    return numpy.sqrt( u_data**2 + v_data**2 )

def ws_units_func(u_cube, v_cube):
    if u_cube.units != getattr(v_cube, 'units', u_cube.units):
        raise ValueError("units do not match")
    return u_cube.units

ws_ifunc = iris.analysis.maths.IFunc(ws_data_func, ws_units_func)
ws_cube = ws_ifunc(u_cube, v_cube, new_name='wind speed')

Example usage 3 Using a data function that allows a keyword argument:

cs_ifunc = iris.analysis.maths.IFunc(numpy.cumsum,
    lambda a: a.units)
cs_cube = cs_ifunc(cube, axis=1)

__call__(cube, other=None, dim=None, in_place=False, new_name=None, **kwargs_data_func)[source]#

Apply the ifunc to the cube(s).

Parameters:

cube – An instance of iris.cube.Cube, whose data is used as the first argument to the data function.
other (optional) – A cube, coord, ndarray, dask array or number whose data is used as the second argument to the data function.
dim (optional) – Dimension along which to apply other if it’s a coordinate that is not found in cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.
new_name (optional) – Name for the resulting Cube.
**kwargs_data_func – Keyword arguments that get passed on to the data_func.

Return type:

iris.cube.Cube

iris.analysis.maths.abs(cube, in_place=False)[source]#

Calculate the absolute values of the data in the Cube provided.

Parameters:

cube – An instance of iris.cube.Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube.

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.add(cube, other, dim=None, in_place=False)[source]#

Calculate the sum.

Calculate the sum of two cubes, or the sum of a cube and a coordinate or array or scalar value.

When summing two cubes, they must both have the same coordinate systems and data resolution.

When adding a coordinate to a cube, they must both share the same number of elements along a shared axis.

Parameters:

cube (iris.cube.Cube) – First operand to add.
other (iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array) – Second operand to add.
dim (int, optional) – If other is a coord which does not exist on the cube, specify the dimension to which it should be mapped.
in_place (bool, default=False) – If True, alters the input cube. Otherwise a new cube is created.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.apply_ufunc(ufunc, cube, other=None, new_unit=None, new_name=None, in_place=False)[source]#

Apply a numpy universal function to a cube.

Apply a numpy universal function to a cube or pair of cubes.

Note

Many of the numpy.ufunc have been implemented explicitly in Iris e.g. numpy.abs(), numpy.add() are implemented in iris.analysis.maths.abs(), iris.analysis.maths.add(). It is usually preferable to use these functions rather than iris.analysis.maths.apply_ufunc() where possible.

Parameters:

ufunc – An instance of numpy.ufunc() e.g. numpy.sin(), numpy.mod().
cube – An instance of iris.cube.Cube.
other (iris.cube.Cube, optional) – An instance of iris.cube.Cube to be given as the second argument to numpy.ufunc().
new_unit (optional) – Unit for the resulting Cube.
new_name (optional) – Name for the resulting Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube.

Examples

cube = apply_ufunc(numpy.sin, cube, in_place=True)

Note

This function maintains laziness when called; it does not realise data. This is dependent on ufunc argument being a numpy operation that is compatible with lazy operation. See more at Real and Lazy Data.

iris.analysis.maths.divide(cube, other, dim=None, in_place=False)[source]#

Calculate the ratio.

Calculate the ratio of two cubes, or the ratio of a cube and a coordinate or array or scalar value.

When dividing a cube by another cube, they must both have the same coordinate systems and data resolution.

When dividing a cube by a coordinate, they must both share the same number of elements along a shared axis.

Parameters:

cube (iris.cube.Cube) – Numerator.
other (iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array) – Denominator.
dim (int, optional) – If other is a coord which does not exist on the cube, specify the dimension to which it should be mapped.
in_place (bool, default=False) – If True, alters the input cube. Otherwise a new cube is created.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.exp(cube, in_place=False)[source]#

Calculate the exponential (exp(x)) of the cube.

Parameters:

cube – An instance of iris.cube.Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube.

Notes

Taking an exponential will return a cube with dimensionless units.

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.exponentiate(cube, exponent, in_place=False)[source]#

Return the result of the given cube to the power of a scalar.

Parameters:

cube – An instance of iris.cube.Cube.
exponent –
The integer or floating point exponent.

Note

When applied to the cube’s unit, the exponent must result in a unit that can be described using only integer powers of the basic units.

e.g. Unit(‘meter^-2 kilogram second^-1’)
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube.

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.intersection_of_cubes(cube, other_cube)[source]#

Return the two Cubes of intersection given two Cubes.

Note

The intersection of cubes function will ignore all single valued coordinates in checking the intersection.

Parameters:

cube – An instance of iris.cube.Cube.
other_cube – An instance of iris.cube.Cube.

Returns:

A pair of iris.cube.Cube instances in a tuple corresponding to the original cubes restricted to their intersection.

Return type:

A paired tuple of iris.cube.Cube

Notes

Deprecated since version 3.2.0: Instead use iris.cube.CubeList.extract_overlapping(). For example, rather than calling

cube1, cube2 = intersection_of_cubes(cube1, cube2)

replace with

cubes = CubeList([cube1, cube2])
coords = ["latitude", "longitude"]    # Replace with relevant coords
intersections = cubes.extract_overlapping(coords)
cube1, cube2 = (intersections[0], intersections[1])

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.log(cube, in_place=False)[source]#

Calculate the natural logarithm (base-e logarithm) of the cube.

Parameters:

cube – An instance of iris.cube.Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.log10(cube, in_place=False)[source]#

Calculate the base-10 logarithm of the cube.

Parameters:

cube – An instance of iris.cube.Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube.

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.log2(cube, in_place=False)[source]#

Calculate the base-2 logarithm of the cube.

Parameters:

cube – An instance of iris.cube.Cube.
in_place (bool, default=False) – Whether to create a new Cube, or alter the given “cube”.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.multiply(cube, other, dim=None, in_place=False)[source]#

Calculate the product.

Calculate the product of two cubes, or the product of a cube and a coordinate or array or scalar value.

When multiplying two cubes, they must both have the same coordinate systems and data resolution.

When mulplying a cube by a coordinate, they must both share the same number of elements along a shared axis.

Parameters:

cube (iris.cube.Cube) – First operand to multiply.
other (iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array) – Second operand to multiply.
dim (int, optional) – If other is a coord which does not exist on the cube, specify the dimension to which it should be mapped.
in_place (bool, default=False) – If True, alters the input cube. Otherwise a new cube is created.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.

iris.analysis.maths.subtract(cube, other, dim=None, in_place=False)[source]#

Calculate the difference.

Calculate the difference between two cubes, or the difference between a cube and a coordinate or array or scalar value.

When differencing two cubes, they must both have the same coordinate systems and data resolution.

When subtracting a coordinate from a cube, they must both share the same number of elements along a shared axis.

Parameters:

cube (iris.cube.Cube) – Cube from which to subtract.
other (iris.cube.Cube, iris.coords.Coord, number, numpy.ndarray or dask.array.Array) – Object to subtract from the cube.
dim (int, optional) – If other is a coord which does not exist on the cube, specify the dimension to which it should be mapped.
in_place (bool, default=False) – If True, alters the input cube. Otherwise a new cube is created.

Return type:

iris.cube.Cube

Notes

This function maintains laziness when called; it does not realise data. See more at Real and Lazy Data.