You are viewing the latest unreleased documentation 3.10.0.dev14. You can switch to a stable version.

# 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:
Return type:

Notes

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

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:
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:

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:
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:
Return type:

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:

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:
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:
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:
Return type:

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:
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:
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.