iris.cube#

Classes for representing multi-dimensional data with metadata.

class iris.cube.Cube(data, standard_name=None, long_name=None, var_name=None, units=None, attributes=None, cell_methods=None, dim_coords_and_dims=None, aux_coords_and_dims=None, aux_factories=None, cell_measures_and_dims=None, ancillary_variables_and_dims=None)[source]#

Bases: CFVariableMixin

A single Iris cube of data and metadata.

Typically obtained from iris.load(), iris.load_cube(), iris.load_cubes(), or from the manipulation of existing cubes.

For example:

>>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
>>> print(cube)
air_temperature / (K)               (latitude: 73; longitude: 96)
    Dimension coordinates:
        latitude                             x              -
        longitude                            -              x
    Scalar coordinates:
        forecast_period             6477 hours, bound=(-28083.0, 6477.0) hours
        forecast_reference_time     1998-03-01 03:00:00
        pressure                    1000.0 hPa
        time                        1998-12-01 00:00:00, bound=(1994-12-01 00:00:00, 1998-12-01 00:00:00)
    Cell methods:
        0                           time: mean within years
        1                           time: mean over years
    Attributes:
        STASH                       m01s16i203
        source                      'Data from Met Office Unified Model'

See the user guide for more information.

Creates a cube with data and optional metadata.

Not typically used - normally cubes are obtained by loading data (e.g. iris.load()) or from manipulating existing cubes.

Args:

data
This object defines the shape of the cube and the phenomenon value in each cell.

data can be a dask.array.Array, a numpy.ndarray, a NumPy array subclass (such as numpy.ma.MaskedArray), or array_like (as described in numpy.asarray()).

See Cube.data.

Kwargs:

standard_name
The standard name for the Cube’s data.
long_name
An unconstrained description of the cube.
var_name
The NetCDF variable name for the cube.
units
The unit of the cube, e.g. "m s-1" or "kelvin".
attributes
A dictionary of cube attributes
cell_methods
A tuple of CellMethod objects, generally set by Iris, e.g. (CellMethod("mean", coords='latitude'), ).
dim_coords_and_dims
A list of coordinates with scalar dimension mappings, e.g [(lat_coord, 0), (lon_coord, 1)].
aux_coords_and_dims
A list of coordinates with dimension mappings, e.g [(lat_coord, 0), (lon_coord, (0, 1))]. See also Cube.add_dim_coord() and Cube.add_aux_coord().
aux_factories
A list of auxiliary coordinate factories. See iris.aux_factory.
cell_measures_and_dims
A list of CellMeasures with dimension mappings.
ancillary_variables_and_dims
A list of AncillaryVariables with dimension mappings.

For example::

>>> from iris.coords import DimCoord
>>> from iris.cube import Cube
>>> latitude = DimCoord(np.linspace(-90, 90, 4),
...                     standard_name='latitude',
...                     units='degrees')
>>> longitude = DimCoord(np.linspace(45, 360, 8),
...                      standard_name='longitude',
...                      units='degrees')
>>> cube = Cube(np.zeros((4, 8), np.float32),
...             dim_coords_and_dims=[(latitude, 0),
...                                  (longitude, 1)])

__copy__()[source]#: Shallow copying is disallowed for Cubes.

__getitem__(keys)[source]#: Cube indexing (through use of square bracket notation) has been implemented at the data level. That is, the indices provided to this method should be aligned to the data of the cube, and thus the indices requested must be applicable directly to the cube.data attribute. All metadata will be subsequently indexed appropriately.

add_ancillary_variable(ancillary_variable, data_dims=None)[source]#

Adds a CF ancillary variable to the cube.

Args:

ancillary_variable
The iris.coords.AncillaryVariable instance to be added to the cube

Kwargs:

data_dims
Integer or iterable of integers giving the data dimensions spanned by the ancillary variable.

Raises a ValueError if an ancillary variable with identical metadata already exists on the cube.

add_aux_coord(coord, data_dims=None)[source]#

Adds a CF auxiliary coordinate to the cube.

Args:

coord
The iris.coords.DimCoord or iris.coords.AuxCoord instance to add to the cube.

Kwargs:

data_dims
Integer or iterable of integers giving the data dimensions spanned by the coordinate.

Raises a ValueError if a coordinate with identical metadata already exists on the cube.

See also

Cube.coords() for matching zero or more coordinates.

Kwargs:

name_or_coord:
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a coordinate or metadata instance equal to that of the desired coordinate e.g., DimCoord or CoordMetadata.
standard_name:
The CF standard name of the desired coordinate. If None, does not check for standard name.
long_name:
An unconstrained description of the coordinate. If None, does not check for long_name.
var_name:
The NetCDF variable name of the desired coordinate. If None, does not check for var_name.
attributes:
A dictionary of attributes desired on the coordinates. If None, does not check for attributes.
axis:
The desired coordinate axis, see iris.util.guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).
contains_dimension:
The desired coordinate contains the data dimension. If None, does not check for the dimension.
dimensions:
The exact data dimensions of the desired coordinate. Coordinates with no data dimension can be found with an empty tuple or list i.e., () or []. If None, does not check for dimensions.
coord_system:
Whether the desired coordinates have a coordinate system equal to the given coordinate system. If None, no check is done.
dim_coords:
Set to True to only return coordinates that are the cube’s dimension coordinates. Set to False to only return coordinates that are the cube’s auxiliary, mesh and derived coordinates. If None, returns all coordinates.
mesh_coords:
Set to True to return only coordinates which are MeshCoords. Set to False to return only non-mesh coordinates. If None, returns all coordinates.

Returns: The coordinate that matches the provided criteria.

coord_dims(coord)[source]#

Returns a tuple of the data dimensions relevant to the given coordinate.

When searching for the given coordinate in the cube the comparison is made using coordinate metadata equality. Hence the given coordinate instance need not exist on the cube, and may contain different coordinate values.

Args:

coord (string or coord)
The (name of the) coord to look for.

coord_system(spec=None)[source]#

Find the coordinate system of the given type.

If no target coordinate system is provided then find any available coordinate system.

Kwargs:

spec:
The the name or type of a coordinate system subclass. E.g.
cube.coord_system("GeogCS") cube.coord_system(iris.coord_systems.GeogCS)
If spec is provided as a type it can be a superclass of any coordinate system found.

If spec is None, then find any available coordinate systems within the iris.cube.Cube.

Returns: The iris.coord_systems.CoordSystem or None.

coords(name_or_coord=None, standard_name=None, long_name=None, var_name=None, attributes=None, axis=None, contains_dimension=None, dimensions=None, coord_system=None, dim_coords=None, mesh_coords=None)[source]#

Return a list of coordinates from the Cube that match the provided criteria.

See also

Cube.coord() for matching exactly one coordinate.

Kwargs:

name_or_coord:
Either,
- a standard_name, long_name, or var_name which is compared against the name().
- a coordinate or metadata instance equal to that of the desired coordinate e.g., DimCoord or CoordMetadata.
standard_name:
The CF standard name of the desired coordinate. If None, does not check for standard name.
long_name:
An unconstrained description of the coordinate. If None, does not check for long_name.
var_name:
The NetCDF variable name of the desired coordinate. If None, does not check for var_name.
attributes:
A dictionary of attributes desired on the coordinates. If None, does not check for attributes.
axis:
The desired coordinate axis, see iris.util.guess_coord_axis(). If None, does not check for axis. Accepts the values X, Y, Z and T (case-insensitive).
contains_dimension:
The desired coordinate contains the data dimension. If None, does not check for the dimension.
dimensions:
The exact data dimensions of the desired coordinate. Coordinates with no data dimension can be found with an empty tuple or list i.e., () or []. If None, does not check for dimensions.
coord_system:
Whether the desired coordinates have a coordinate system equal to the given coordinate system. If None, no check is done.
dim_coords:
Set to True to only return coordinates that are the cube’s dimension coordinates. Set to False to only return coordinates that are the cube’s auxiliary, mesh and derived coordinates. If None, returns all coordinates.
mesh_coords:
Set to True to return only coordinates which are MeshCoords. Set to False to return only non-mesh coordinates. If None, returns all coordinates.

Returns: A list containing zero or more coordinates matching the provided criteria.

copy(data=None)[source]#

Returns a deep copy of this cube.

Kwargs:

data:
Replace the data of the cube copy with provided data payload.

Returns: A copy instance of the Cube.

core_data()[source]#

Retrieve the data array of this Cube in its current state, which will either be real or lazy.

If this Cube has lazy data, accessing its data array via this method will not realise the data array. This means you can perform operations using this method that work equivalently on real or lazy data, and will maintain lazy data if present.

extract(constraint)[source]#: Filter the cube by the given constraint using iris.Constraint.extract() method.

has_lazy_data()[source]#

Details whether this Cube has lazy data.

Returns: Boolean.

interpolate(sample_points, scheme, collapse_scalar=True)[source]#

Interpolate from this Cube to the given sample points using the given interpolation scheme.

Args:

sample_points:
A sequence of (coordinate, points) pairs over which to interpolate. The values for coordinates that correspond to dates or times may optionally be supplied as datetime.datetime or cftime.datetime instances. The N pairs supplied will be used to create an N-d grid of points that will then be sampled (rather than just N points).
scheme:
An instance of the type of interpolation to use to interpolate from this Cube to the given sample points. The interpolation schemes currently available in Iris are:
iris.analysis.Linear, and

iris.analysis.Nearest.

Kwargs:

collapse_scalar:
Whether to collapse the dimension of scalar sample points in the resulting cube. Default is True.

Returns: A cube interpolated at the given sample points. If collapse_scalar is True then the dimensionality of the cube will be the number of original cube dimensions minus the number of scalar coordinates.

For example:

>>> import datetime
>>> import iris
>>> path = iris.sample_data_path('uk_hires.pp')
>>> cube = iris.load_cube(path, 'air_potential_temperature')
>>> print(cube.summary(shorten=True))
air_potential_temperature / (K)     (time: 3; model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
>>> print(cube.coord('time'))
DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
    points: [2009-11-19 10:00:00, 2009-11-19 11:00:00, 2009-11-19 12:00:00]
    shape: (3,)
    dtype: float64
    standard_name: 'time'
>>> print(cube.coord('time').points)
[349618. 349619. 349620.]
>>> samples = [('time', 349618.5)]
>>> result = cube.interpolate(samples, iris.analysis.Linear())
>>> print(result.summary(shorten=True))
air_potential_temperature / (K)     (model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
>>> print(result.coord('time'))
DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
    points: [2009-11-19 10:30:00]
    shape: (1,)
    dtype: float64
    standard_name: 'time'
>>> print(result.coord('time').points)
[349618.5]
>>> # For datetime-like coordinates, we can also use
>>> # datetime-like objects.
>>> samples = [('time', datetime.datetime(2009, 11, 19, 10, 30))]
>>> result2 = cube.interpolate(samples, iris.analysis.Linear())
>>> print(result2.summary(shorten=True))
air_potential_temperature / (K)     (model_level_number: 7; grid_latitude: 204; grid_longitude: 187)
>>> print(result2.coord('time'))
DimCoord :  time / (hours since 1970-01-01 00:00:00, standard calendar)
    points: [2009-11-19 10:30:00]
    shape: (1,)
    dtype: float64
    standard_name: 'time'
>>> print(result2.coord('time').points)
[349618.5]
>>> print(result == result2)
True

intersection(*args, **kwargs)[source]#

Return the intersection of the cube with specified coordinate ranges.

Coordinate ranges can be specified as:

positional arguments: instances of iris.coords.CoordExtent, or equivalent tuples of 3-5 items:
- coord
  Either a iris.coords.Coord, or coordinate name (as defined in iris.cube.Cube.coords())
- minimum
  The minimum value of the range to select.
- maximum
  The maximum value of the range to select.
- min_inclusive
  If True, coordinate values equal to minimum will be included in the selection. Default is True.
- max_inclusive
  If True, coordinate values equal to maximum will be included in the selection. Default is True.
keyword arguments, where the keyword name specifies the name of the coordinate, and the value defines the corresponding range of coordinate values as a tuple. The tuple must contain two, three, or four items, corresponding to (minimum, maximum, min_inclusive, max_inclusive) as defined above.

Kwargs:

ignore_bounds:
Intersect based on points only. Default False.
threshold:
Minimum proportion of a bounded cell that must overlap with the specified range. Default 0.

Note

For ranges defined over “circular” coordinates (i.e. those where the units attribute has a modulus defined) the cube will be “rolled” to fit where necessary. When requesting a range that covers the entire modulus, a split cell will preferentially be placed at the minimum end.

Warning

Currently this routine only works with “circular” coordinates (as defined in the previous note.)

For example:

>>> import iris
>>> cube = iris.load_cube(iris.sample_data_path('air_temp.pp'))
>>> print(cube.coord('longitude').points[::10])
[   0.           37.49999237   74.99998474  112.49996948  149.99996948
  187.49995422  224.99993896  262.49993896  299.99993896  337.49990845]
>>> subset = cube.intersection(longitude=(30, 50))
>>> print(subset.coord('longitude').points)
[ 33.74999237  37.49999237  41.24998856  44.99998856  48.74998856]
>>> subset = cube.intersection(longitude=(-10, 10))
>>> print(subset.coord('longitude').points)
[-7.50012207 -3.75012207  0.          3.75        7.5       ]

Returns: A new Cube giving the subset of the cube which intersects with the requested coordinate intervals.

is_compatible(other, ignore=None)[source]#

Return whether the cube is compatible with another.

Compatibility is determined by comparing iris.cube.Cube.name(), iris.cube.Cube.units, iris.cube.Cube.cell_methods and iris.cube.Cube.attributes that are present in both objects.

Args:

other:
An instance of iris.cube.Cube or iris.cube.CubeMetadata.
ignore:
A single attribute key or iterable of attribute keys to ignore when comparing the cubes. Default is None. To ignore all attributes set this to other.attributes.

Returns: Boolean.

See also

iris.util.describe_diff()

Note

This function does not indicate whether the two cubes can be merged, instead it checks only the four items quoted above for equality. Determining whether two cubes will merge requires additional logic that is beyond the scope of this method.

lazy_data()[source]#

Return a “lazy array” representing the Cube data. A lazy array describes an array whose data values have not been loaded into memory from disk.

Accessing this method will never cause the Cube data to be loaded. Similarly, calling methods on, or indexing, the returned Array will not cause the Cube data to be loaded.

If the Cube data have already been loaded (for example by calling data()), the returned Array will be a view of the loaded cube data represented as a lazy array object. Note that this does _not_ make the Cube data lazy again; the Cube data remains loaded in memory.

Returns: A lazy array, representing the Cube data.

mesh_dim()[source]#

Return the cube dimension of the mesh, if the cube has any MeshCoords, or None if it has none.

Returns:

mesh_dim (int, or None):
the cube dimension which the cube MeshCoords map to, or None.

regrid(grid, scheme)[source]#

Regrid this Cube on to the given target grid using the given regridding scheme.

Args:

grid:
A Cube that defines the target grid.
scheme:
An instance of the type of regridding to use to regrid this cube onto the target grid. The regridding schemes in Iris currently include:
iris.analysis.Linear*,

iris.analysis.Nearest*,

iris.analysis.AreaWeighted*,

iris.analysis.UnstructuredNearest,

iris.analysis.PointInCell,
* Supports lazy regridding.

Returns

A cube defined with the horizontal dimensions of the target grid and the other dimensions from this cube. The data values of this cube will be converted to values on the new grid according to the given regridding scheme.

The returned cube will have lazy data if the original cube has lazy data and the regridding scheme supports lazy regridding.

Note

Both the source and target cubes must have a CoordSystem, otherwise this function is not applicable.

remove_ancillary_variable(ancillary_variable)[source]#

Removes an ancillary variable from the cube.

Args:

ancillary_variable (string or AncillaryVariable)
The (name of the) AncillaryVariable to remove from the cube.

remove_aux_factory(aux_factory)[source]#: Removes the given auxiliary coordinate factory from the cube.

remove_cell_measure(cell_measure)[source]#

Removes a cell measure from the cube.

Args:

cell_measure (string or cell_measure)
The (name of the) cell measure to remove from the cube. As either

(a) a standard_name, long_name, or var_name. Defaults to value of default (which itself defaults to unknown) as defined in iris.common.CFVariableMixin.

(b) a cell_measure instance with metadata equal to that of the desired cell_measures.

Note

If the argument given does not represent a valid cell_measure on the cube, an iris.exceptions.CellMeasureNotFoundError is raised.

See also

Cube.add_cell_measure()

remove_coord(coord)[source]#

Removes a coordinate from the cube.

Args:

coord (string or coord)
The (name of the) coordinate to remove from the cube.

replace_coord(new_coord)[source]#: Replace the coordinate whose metadata matches the given coordinate.

rolling_window(coord, aggregator, window, **kwargs)[source]#

Perform rolling window aggregation on a cube given a coordinate, an aggregation method and a window size.

Args:

coord (string/iris.coords.Coord):
The coordinate over which to perform the rolling window aggregation.
aggregator (iris.analysis.Aggregator):
Aggregator to be applied to the data.
window (int):
Size of window to use.

Kwargs:

kwargs:
Aggregator and aggregation function keyword arguments. The weights argument to the aggregator, if any, should be a 1d array, cube, or (names of) coords(), cell_measures(), or ancillary_variables() with the same length as the chosen window.

Returns: iris.cube.Cube.

Note

This operation does not yet have support for lazy evaluation.

For example:

>>> import iris, iris.analysis
>>> fname = iris.sample_data_path('GloSea4', 'ensemble_010.pp')
>>> air_press = iris.load_cube(fname, 'surface_temperature')
>>> print(air_press)
surface_temperature / (K)           (time: 6; latitude: 145; longitude: 192)
    Dimension coordinates:
        time                             x            -               -
        latitude                         -            x               -
        longitude                        -            -               x
    Auxiliary coordinates:
        forecast_period                  x            -               -
    Scalar coordinates:
        forecast_reference_time     2011-07-23 00:00:00
        realization                 10
    Cell methods:
        0                           time: mean (interval: 1 hour)
    Attributes:
        STASH                       m01s00i024
        source                      'Data from Met Office Unified Model'
        um_version                  '7.6'

>>> print(air_press.rolling_window('time', iris.analysis.MEAN, 3))
surface_temperature / (K)           (time: 4; latitude: 145; longitude: 192)
    Dimension coordinates:
        time                             x            -               -
        latitude                         -            x               -
        longitude                        -            -               x
    Auxiliary coordinates:
        forecast_period                  x            -               -
    Scalar coordinates:
        forecast_reference_time     2011-07-23 00:00:00
        realization                 10
    Cell methods:
        0                           time: mean (interval: 1 hour)
        1                           time: mean
    Attributes:
        STASH                       m01s00i024
        source                      'Data from Met Office Unified Model'
        um_version                  '7.6'

Notice that the forecast_period dimension now represents the 4 possible windows of size 3 from the original cube.

slices(ref_to_slice, ordered=True)[source]#

Return an iterator of all subcubes given the coordinates or dimension indices desired to be present in each subcube.

Args:

ref_to_slice (string, coord, dimension index or a list of these):
Determines which dimensions will be returned in the subcubes (i.e. the dimensions that are not iterated over). A mix of input types can also be provided. They must all be orthogonal (i.e. point to different dimensions).

Kwargs:

ordered: if True, the order which the coords to slice or data_dims
are given will be the order in which they represent the data in the resulting cube slices. If False, the order will follow that of the source cube. Default is True.

Returns: An iterator of subcubes.

For example, to get all 2d longitude/latitude subcubes from a multi-dimensional cube:

for sub_cube in cube.slices(['longitude', 'latitude']):
    print(sub_cube)

See also

iris.cube.Cube.slices_over().

slices_over(ref_to_slice)[source]#

Return an iterator of all subcubes along a given coordinate or dimension index, or multiple of these.

Args:

ref_to_slice (string, coord, dimension index or a list of these):
Determines which dimensions will be iterated along (i.e. the dimensions that are not returned in the subcubes). A mix of input types can also be provided.

Returns: An iterator of subcubes.

For example, to get all subcubes along the time dimension:

for sub_cube in cube.slices_over('time'):
    print(sub_cube)

See also

iris.cube.Cube.slices().

Note

The order of dimension references to slice along does not affect the order of returned items in the iterator; instead the ordering is based on the fastest-changing dimension.

subset(coord)[source]#: Get a subset of the cube by providing the desired resultant coordinate. If the coordinate provided applies to the whole cube; the whole cube is returned. As such, the operation is not strict.

summary(shorten=False, name_padding=35)[source]#

String summary of the Cube with name+units, a list of dim coord names versus length and, optionally, a summary of all other components.

Kwargs:

shorten (bool):
If set, produce a one-line summary of minimal width, showing only the cube name, units and dimensions. When not set (default), produces a full multi-line summary string.
name_padding (int):
Control the minimum width of the cube name + units, i.e. the indent of the dimension map section.

transpose(new_order=None)[source]#

Re-order the data dimensions of the cube in-place.

new_order - list of ints, optional: By default, reverse the dimensions, otherwise permute the axes according to the values given.

Note

If defined, new_order must span all of the data dimensions.

Example usage:

# put the second dimension first, followed by the third dimension,
# and finally put the first dimension third::

    >>> cube.transpose([1, 2, 0])

xml(checksum=False, order=True, byteorder=True)[source]#: Returns a fully valid CubeML string representation of the Cube.

property aux_coords#: Return a tuple of all the auxiliary coordinates, ordered by dimension(s).

property aux_factories#: Return a tuple of all the coordinate factories.

property cell_methods#: Tuple of iris.coords.CellMethod representing the processing done on the phenomenon.

property data#

The numpy.ndarray representing the multi-dimensional data of the cube.

Note

Cubes obtained from NetCDF, PP, and FieldsFile files will only populate this attribute on its first use.

To obtain the shape of the data without causing it to be loaded, use the Cube.shape attribute.

Example::

>>> fname = iris.sample_data_path('air_temp.pp')
>>> cube = iris.load_cube(fname, 'air_temperature')
>>> # cube.data does not yet have a value.
...
>>> print(cube.shape)
(73, 96)
>>> # cube.data still does not have a value.
...
>>> cube = cube[:10, :20]
>>> # cube.data still does not have a value.
...
>>> data = cube.data
>>> # Only now is the data loaded.
...
>>> print(data.shape)
(10, 20)

property derived_coords#: Return a tuple of all the coordinates generated by the coordinate factories.

property dim_coords#: Return a tuple of all the dimension coordinates, ordered by dimension.

Note

The length of the returned tuple is not necessarily the same as Cube.ndim as there may be dimensions on the cube without dimension coordinates. It is therefore unreliable to use the resulting tuple to identify the dimension coordinates for a given dimension - instead use the Cube.coord() method with the dimensions and dim_coords keyword arguments.

property dtype#: The data type of the values in the data array of this Cube.

property location#

Return the mesh “location” of the cube data, if the cube has any MeshCoords, or None if it has none.

Returns:

location (str or None):
The mesh location of the cube MeshCoords (i.e. one of ‘face’ / ‘edge’ / ‘node’), or None.

property mesh#

Return the unstructured Mesh associated with the cube, if the cube has any MeshCoords, or None if it has none.

Returns:

mesh (iris.experimental.ugrid.mesh.Mesh or None):
The mesh of the cube MeshCoords, or None.

property ndim#: The number of dimensions in the data of this cube.

property shape#: The shape of the data of this cube.

class iris.cube.CubeList(*args, **kwargs)[source]#

Bases: list

All the functionality of a standard list with added “Cube” context.

Given an iterable of cubes, return a CubeList instance.

__getitem__(keys)[source]#: x.__getitem__(y) <==> x[y]

__getslice__(start, stop)[source]#

x.__getslice__(i, j) <==> x[i:j]

Use of negative indices is not supported.

__iadd__(other_cubes)[source]#: Add a sequence of cubes to the cubelist in place.

__repr__()[source]#: Runs repr on every cube.

__setitem__(key, cube_or_sequence)[source]#: Set self[key] to cube or sequence of cubes

__str__()[source]#: Runs short Cube.summary() on every cube.

append(cube)[source]#: Append a cube.

concatenate(check_aux_coords=True, check_cell_measures=True, check_ancils=True, check_derived_coords=True)[source]#

Concatenate the cubes over their common dimensions.

Kwargs:

check_aux_coords
Checks if the points and bounds of auxiliary coordinates of the cubes match. This check is not applied to auxiliary coordinates that span the dimension the concatenation is occurring along. Defaults to True.
check_cell_measures
Checks if the data of cell measures of the cubes match. This check is not applied to cell measures that span the dimension the concatenation is occurring along. Defaults to True.
check_ancils
Checks if the data of ancillary variables of the cubes match. This check is not applied to ancillary variables that span the dimension the concatenation is occurring along. Defaults to True.
check_derived_coords
Checks if the points and bounds of derived coordinates of the cubes match. This check is not applied to derived coordinates that span the dimension the concatenation is occurring along. Note that differences in scalar coordinates and dimensional coordinates used to derive the coordinate are still checked. Checks for auxiliary coordinates used to derive the coordinates can be ignored with check_aux_coords. Defaults to True.

Returns: A new iris.cube.CubeList of concatenated iris.cube.Cube instances.

This combines cubes with a common dimension coordinate, but occupying different regions of the coordinate value. The cubes are joined across that dimension.

For example:

>>> print(c1)
some_parameter / (unknown)          (y_vals: 2; x_vals: 4)
     Dimension coordinates:
          y_vals                           x          -
          x_vals                           -          x
>>> print(c1.coord('y_vals').points)
[4 5]
>>> print(c2)
some_parameter / (unknown)          (y_vals: 3; x_vals: 4)
     Dimension coordinates:
          y_vals                           x          -
          x_vals                           -          x
>>> print(c2.coord('y_vals').points)
[ 7  9 10]
>>> cube_list = iris.cube.CubeList([c1, c2])
>>> new_cube = cube_list.concatenate()[0]
>>> print(new_cube)
some_parameter / (unknown)          (y_vals: 5; x_vals: 4)
     Dimension coordinates:
          y_vals                           x          -
          x_vals                           -          x
>>> print(new_cube.coord('y_vals').points)
[ 4  5  7  9 10]
>>>

Contrast this with iris.cube.CubeList.merge(), which makes a new dimension from values of an auxiliary scalar coordinate.

Note

Cubes may contain ‘extra’ dimensional elements such as auxiliary coordinates, cell measures or ancillary variables. For a group of similar cubes to concatenate together into one output, all such elements which do not map to the concatenation axis must be identical in every input cube : these then appear unchanged in the output. Similarly, those elements which do map to the concatenation axis must have matching properties, but may have different data values : these then appear, concatenated, in the output cube. If any cubes in a group have dimensional elements which do not match correctly, the group will not concatenate to a single output cube.

Note

If time coordinates in the list of cubes have differing epochs then the cubes will not be able to be concatenated. If this occurs, use iris.util.unify_time_units() to normalise the epochs of the time coordinates so that the cubes can be concatenated.

Note

Concatenation cannot occur along an anonymous dimension.

concatenate_cube(check_aux_coords=True, check_cell_measures=True, check_ancils=True, check_derived_coords=True)[source]#

Return the concatenated contents of the CubeList as a single Cube.

If it is not possible to concatenate the CubeList into a single Cube, a ConcatenateError will be raised describing the reason for the failure.

Kwargs:

check_aux_coords
Checks if the points and bounds of auxiliary coordinates of the cubes match. This check is not applied to auxiliary coordinates that span the dimension the concatenation is occurring along. Defaults to True.
check_cell_measures
Checks if the data of cell measures of the cubes match. This check is not applied to cell measures that span the dimension the concatenation is occurring along. Defaults to True.
check_ancils
Checks if the data of ancillary variables of the cubes match. This check is not applied to ancillary variables that span the dimension the concatenation is occurring along. Defaults to True.
check_derived_coords
Checks if the points and bounds of derived coordinates of the cubes match. This check is not applied to derived coordinates that span the dimension the concatenation is occurring along. Note that differences in scalar coordinates and dimensional coordinates used to derive the coordinate are still checked. Checks for auxiliary coordinates used to derive the coordinates can be ignored with check_aux_coords. Defaults to True.

Note

Concatenation cannot occur along an anonymous dimension.

copy()[source]#: Return a CubeList when CubeList.copy() is called.

extend(other_cubes)[source]#

Extend cubelist by appending the cubes contained in other_cubes.

Args:

other_cubes:
A cubelist or other sequence of cubes.

extract(constraints)[source]#

Filter each of the cubes which can be filtered by the given constraints.

This method iterates over each constraint given, and subsets each of the cubes in this CubeList where possible. Thus, a CubeList of length n when filtered with m constraints can generate a maximum of m * n cubes.

Args:

constraints (Constraint or iterable of constraints):
A single constraint or an iterable.

extract_cube(constraint)[source]#

Extract a single cube from a CubeList, and return it. Raise an error if the extract produces no cubes, or more than one.

Args:

constraint (Constraint):
The constraint to extract with.

extract_cubes(constraints)[source]#

Extract specific cubes from a CubeList, one for each given constraint. Each constraint must produce exactly one cube, otherwise an error is raised.

Args:

constraints (iterable of, or single, Constraint):
The constraints to extract with.

extract_overlapping(coord_names)[source]#

Returns a CubeList of cubes extracted over regions where the coordinates overlap, for the coordinates in coord_names.

Args:

coord_names:
A string or list of strings of the names of the coordinates over which to perform the extraction.

insert(index, cube)[source]#: Insert a cube before index.

merge(unique=True)[source]#

Returns the CubeList resulting from merging this CubeList.

Kwargs:

unique:
If True, raises iris.exceptions.DuplicateDataError if duplicate cubes are detected.

This combines cubes with different values of an auxiliary scalar coordinate, by constructing a new dimension.

For example:

>>> print(c1)
some_parameter / (unknown)          (x_vals: 3)
     Dimension coordinates:
          x_vals                           x
     Scalar coordinates:
          y_vals: 100
>>> print(c2)
some_parameter / (unknown)          (x_vals: 3)
     Dimension coordinates:
          x_vals                           x
     Scalar coordinates:
          y_vals: 200
>>> cube_list = iris.cube.CubeList([c1, c2])
>>> new_cube = cube_list.merge()[0]
>>> print(new_cube)
some_parameter / (unknown)          (y_vals: 2; x_vals: 3)
     Dimension coordinates:
          y_vals                           x          -
          x_vals                           -          x
>>> print(new_cube.coord('y_vals').points)
[100 200]
>>>

Contrast this with iris.cube.CubeList.concatenate(), which joins cubes along an existing dimension.

Note

Cubes may contain additional dimensional elements such as auxiliary coordinates, cell measures or ancillary variables. A group of similar cubes can only merge to a single result if all such elements are identical in every input cube : they are then present, unchanged, in the merged output cube.

Note

If time coordinates in the list of cubes have differing epochs then the cubes will not be able to be merged. If this occurs, use iris.util.unify_time_units() to normalise the epochs of the time coordinates so that the cubes can be merged.

merge_cube()[source]#

Return the merged contents of the CubeList as a single Cube.

If it is not possible to merge the CubeList into a single Cube, a MergeError will be raised describing the reason for the failure.

For example:

>>> cube_1 = iris.cube.Cube([1, 2])
>>> cube_1.add_aux_coord(iris.coords.AuxCoord(0, long_name='x'))
>>> cube_2 = iris.cube.Cube([3, 4])
>>> cube_2.add_aux_coord(iris.coords.AuxCoord(1, long_name='x'))
>>> cube_2.add_dim_coord(
...     iris.coords.DimCoord([0, 1], long_name='z'), 0)
>>> single_cube = iris.cube.CubeList([cube_1, cube_2]).merge_cube()
Traceback (most recent call last):
...
iris.exceptions.MergeError: failed to merge into a single cube.
  Coordinates in cube.dim_coords differ: z.
  Coordinate-to-dimension mapping differs for cube.dim_coords.

realise_data()[source]#

Fetch ‘real’ data for all cubes, in a shared calculation.

This computes any lazy data, equivalent to accessing each cube.data. However, lazy calculations and data fetches can be shared between the computations, improving performance.

For example:

# Form stats.
a_std = cube_a.collapsed(['x', 'y'], iris.analysis.STD_DEV)
b_std = cube_b.collapsed(['x', 'y'], iris.analysis.STD_DEV)
ab_mean_diff = (cube_b - cube_a).collapsed(['x', 'y'],
                                           iris.analysis.MEAN)
std_err = (a_std * a_std + b_std * b_std) ** 0.5

# Compute these stats together (avoiding multiple data passes).
CubeList([a_std, b_std, ab_mean_diff, std_err]).realise_data()

Note

Cubes with non-lazy data are not affected.

xml(checksum=False, order=True, byteorder=True)[source]#: Return a string of the XML that this list of cubes represents.