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:
- cube:
An instance of
iris.cube.Cube
.
Kwargs:
- in_place:
Whether to create a new Cube, or alter the given “cube”.
- Returns
An instance of
iris.cube.Cube
.
-
iris.analysis.maths.
add
(cube, other, dim=None, in_place=False)[source]¶ 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:
- cube:
An instance of
iris.cube.Cube
.
- other:
An instance of
iris.cube.Cube
oriris.coords.Coord
, or a number ornumpy.ndarray
.
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
.
-
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 iniris.analysis.maths.abs()
,iris.analysis.maths.add()
. It is usually preferable to use these functions rather thaniris.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 tonumpy.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)
-
iris.analysis.maths.
divide
(cube, other, dim=None, in_place=False)[source]¶ Calculate the division of a cube by a cube or coordinate.
Args:
- cube:
An instance of
iris.cube.Cube
.
- other:
An instance of
iris.cube.Cube
oriris.coords.Coord
, or a number ornumpy.ndarray
.
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
.
-
iris.analysis.maths.
exp
(cube, in_place=False)[source]¶ Calculate the exponential (exp(x)) of the cube.
Args:
- cube:
An instance of
iris.cube.Cube
.
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
.
-
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
.
-
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:
- 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.
-
iris.analysis.maths.
log
(cube, in_place=False)[source]¶ Calculate the natural logarithm (base-e logarithm) of the cube.
Args:
- cube:
An instance of
iris.cube.Cube
.
Kwargs:
- in_place:
Whether to create a new Cube, or alter the given “cube”.
- Returns
An instance of
iris.cube.Cube
.
-
iris.analysis.maths.
log10
(cube, in_place=False)[source]¶ Calculate the base-10 logarithm of the cube.
Args:
- cube:
An instance of
iris.cube.Cube
.
Kwargs:
- in_place:
Whether to create a new Cube, or alter the given “cube”.
- Returns
An instance of
iris.cube.Cube
.
-
iris.analysis.maths.
log2
(cube, in_place=False)[source]¶ Calculate the base-2 logarithm of the cube.
Args:
- cube:
An instance of
iris.cube.Cube
.
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
.
-
iris.analysis.maths.
multiply
(cube, other, dim=None, in_place=False)[source]¶ Calculate the product of a cube and another cube or coordinate.
Args:
- cube:
An instance of
iris.cube.Cube
.
- other:
An instance of
iris.cube.Cube
oriris.coords.Coord
, or a number ornumpy.ndarray
.
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
.
-
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:
- cube:
An instance of
iris.cube.Cube
.
- other:
An instance of
iris.cube.Cube
oriris.coords.Coord
, or a number ornumpy.ndarray
.
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
.
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:
- cube
An instance of
iris.cube.Cube
, whose data is used as the first argument to the data function.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
.