# iris.analysis.maths¶

Basic mathematical and statistical operations.

In this module:

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

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

Args:

Kwargs:

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

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

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

Args:

Kwargs:

• dim:

If supplying a coord with no match on the cube, you must supply the dimension to process.

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

Args:

• ufunc:

An instance of `numpy.ufunc()` e.g. `numpy.sin()`, `numpy.mod()`.

• cube:

An instance of `iris.cube.Cube`.

Kwargs:

• other:

An instance of `iris.cube.Cube` to be given as the second argument to `numpy.ufunc()`.

• new_unit:

Unit for the resulting Cube.

• new_name:

Name for the resulting Cube.

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

Example:

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

↑ top ↑

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

Calculate the division of a cube by a cube or coordinate.

Args:

Kwargs:

• dim:

If supplying a coord with no match on the cube, you must supply the dimension to process.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

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

Args:

Note

Taking an exponential will return a cube with dimensionless units.

Kwargs:

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

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

Args:

• 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’)

Kwargs:

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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.

Args:

Returns

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

↑ top ↑

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

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

Args:

Kwargs:

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

Calculate the base-10 logarithm of the cube.

Args:

Kwargs:

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

Calculate the base-2 logarithm of the cube.

Args:

Kwargs:lib/iris/tests/unit/analysis/maths/test_subtract.py

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

Calculate the product of a cube and another cube or coordinate.

Args:

Kwargs:

• dim:

If supplying a coord with no match on the cube, you must supply the dimension to process.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

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

When subtracting two cubes, they must both have the same coordinate systems & data resolution.

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

Args:

Kwargs:

• dim:

If supplying a coord with no match on the cube, you must supply the dimension to process.

• in_place:

Whether to create a new Cube, or alter the given “cube”.

Returns

An instance of `iris.cube.Cube`.

↑ top ↑

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

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

Create an ifunc from a data function and units function.

Args:

• 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`.

Returns

An ifunc.

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]

Applies the ifunc to the cube(s).

Args:

Kwargs:

• other

A cube, coord, ndarray or number whose data is used as the second argument to the data function.

• new_name:

Name for the resulting Cube.

• in_place:

Whether to create a new Cube, or alter the given “cube”.

• dim:

Dimension along which to apply other if it’s a coordinate that is not found in cube

• kwargs_data_func:

Keyword arguments that get passed on to the data_func.

Returns

An instance of `iris.cube.Cube`.