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 adask.array.Array
, anumpy.ndarray
, a NumPy array subclass (such asnumpy.ma.MaskedArray
), or array_like (as described innumpy.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 alsoCube.add_dim_coord()
andCube.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)])
- __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
oriris.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.remove_coord()
.
- add_aux_factory(aux_factory)[source]#
Adds an auxiliary coordinate factory to the cube.
Args:
- aux_factory
The
iris.aux_factory.AuxCoordFactory
instance to add.
- add_cell_measure(cell_measure, data_dims=None)[source]#
Adds a CF cell measure to the cube.
Args:
- cell_measure
The
iris.coords.CellMeasure
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 cell_measure with identical metadata already exists on the cube.
See also
Cube.remove_cell_measure()
.
- add_cell_method(cell_method)[source]#
Add a
CellMethod
to the Cube.
- add_dim_coord(dim_coord, data_dim)[source]#
Add a CF coordinate to the cube.
Args:
- dim_coord
The
iris.coords.DimCoord
instance to add to the cube.
- data_dim
Integer giving the data dimension spanned by the coordinate.
Raises a ValueError if a coordinate with identical metadata already exists on the cube or if a coord already exists for the given dimension.
See also
Cube.remove_coord()
.
- aggregated_by(coords, aggregator, climatological=False, **kwargs)[source]#
Perform aggregation over the cube given one or more “group coordinates”.
A “group coordinate” is a coordinate where repeating values represent a single group, such as a month coordinate on a daily time slice. Repeated values will form a group even if they are not consecutive.
The group coordinates must all be over the same cube dimension. Each common value group identified over all the group-by coordinates is collapsed using the provided aggregator.
Weighted aggregations (
iris.analysis.WeightedAggregator
) may also be supplied. These includeMEAN
andSUM
.Weighted aggregations support an optional weights keyword argument. If set, this can be supplied as an array, cube, or (names of)
coords()
,cell_measures()
, orancillary_variables()
. In all cases, the weights should be 1d or match the shape of the cube. When weights are not given as arrays, units are correctly handled for weighted sums, i.e., the original unit of the cube is multiplied by the units of the weights.- Parameters
coords ((list of coord names or
iris.coords.Coord
instances)) – One or more coordinates over which group aggregation is to be performed.aggregator (
iris.analysis.Aggregator
) – Aggregator to be applied to each group.climatological (bool) – Indicates whether the output is expected to be climatological. For any aggregated time coord(s), this causes the climatological flag to be set and the point for each cell to equal its first bound, thereby preserving the time of year.
kwargs – Aggregator and aggregation function keyword arguments.
- Return type
Examples
>>> import iris >>> import iris.analysis >>> import iris.coord_categorisation as cat >>> fname = iris.sample_data_path('ostia_monthly.nc') >>> cube = iris.load_cube(fname, 'surface_temperature') >>> cat.add_year(cube, 'time', name='year') >>> new_cube = cube.aggregated_by('year', iris.analysis.MEAN) >>> print(new_cube) surface_temperature / (K) (time: 5; latitude: 18; longitude: 432) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_reference_time x - - year x - - Scalar coordinates: forecast_period 0 hours Cell methods: 0 month: year: mean 1 year: mean Attributes: Conventions 'CF-1.5' STASH m01s00i024
- ancillary_variable(name_or_ancillary_variable=None)[source]#
Return a single ancillary_variable given the same arguments as
Cube.ancillary_variables()
.Note
If the arguments given do not result in precisely 1 ancillary_variable being matched, an
iris.exceptions.AncillaryVariableNotFoundError
is raised.See also
Cube.ancillary_variables()
for full keyword documentation.
- ancillary_variable_dims(ancillary_variable)[source]#
Returns a tuple of the data dimensions relevant to the given AncillaryVariable.
- ancillary_variable (string or AncillaryVariable)
The (name of the) AncillaryVariable to look for.
- ancillary_variables(name_or_ancillary_variable=None)[source]#
Return a list of ancillary variable in this cube fitting the given criteria.
Kwargs:
- name_or_ancillary_variable
Either
(a) a
standard_name
,long_name
, orvar_name
. Defaults to value of default (which itself defaults to unknown) as defined iniris.common.CFVariableMixin
.(b) a ancillary_variable instance with metadata equal to that of the desired ancillary_variables.
See also
Cube.ancillary_variable()
.
- aux_factory(name=None, standard_name=None, long_name=None, var_name=None)[source]#
Returns the single coordinate factory that matches the criteria, or raises an error if not found.
Kwargs:
- name
If not None, matches against factory.name().
- standard_name
The CF standard name of the desired coordinate factory. If None, does not check for standard name.
- long_name
An unconstrained description of the coordinate factory. If None, does not check for long_name.
- var_name
The NetCDF variable name of the desired coordinate factory. If None, does not check for var_name.
Note
If the arguments given do not result in precisely 1 coordinate factory being matched, an
iris.exceptions.CoordinateNotFoundError
is raised.
- cell_measure(name_or_cell_measure=None)[source]#
Return a single cell_measure given the same arguments as
Cube.cell_measures()
.Note
If the arguments given do not result in precisely 1 cell_measure being matched, an
iris.exceptions.CellMeasureNotFoundError
is raised.See also
Cube.cell_measures()
for full keyword documentation.
- cell_measure_dims(cell_measure)[source]#
Returns a tuple of the data dimensions relevant to the given CellMeasure.
- cell_measure (string or CellMeasure)
The (name of the) cell measure to look for.
- cell_measures(name_or_cell_measure=None)[source]#
Return a list of cell measures in this cube fitting the given criteria.
Kwargs:
- name_or_cell_measure
Either
(a) a
standard_name
,long_name
, orvar_name
. Defaults to value of default (which itself defaults to unknown) as defined iniris.common.CFVariableMixin
.(b) a cell_measure instance with metadata equal to that of the desired cell_measures.
See also
Cube.cell_measure()
.
- collapsed(coords, aggregator, **kwargs)[source]#
Collapse one or more dimensions over the cube given the coordinate/s and an aggregation.
Examples of aggregations that may be used include
COUNT
andMAX
.Weighted aggregations (
iris.analysis.WeightedAggregator
) may also be supplied. These includeMEAN
and sumSUM
.Weighted aggregations support an optional weights keyword argument. If set, this can be supplied as an array, cube, or (names of)
coords()
,cell_measures()
, orancillary_variables()
. In all cases, the weights should be 1d (for collapsing over a 1d coordinate) or match the shape of the cube. When weights are not given as arrays, units are correctly handled for weighted sums, i.e., the original unit of the cube is multiplied by the units of the weights. Values for latitude-longitude area weights may be calculated usingiris.analysis.cartography.area_weights()
.Some Iris aggregators support “lazy” evaluation, meaning that cubes resulting from this method may represent data arrays which are not computed until the data is requested (e.g. via
cube.data
oriris.save
). If lazy evaluation exists for the given aggregator it will be used wherever possible when this cube’s data is itself a deferred array.Args:
- coords (string, coord or a list of strings/coords):
Coordinate names/coordinates over which the cube should be collapsed.
- aggregator (
iris.analysis.Aggregator
): Aggregator to be applied for collapse operation.
- aggregator (
Kwargs:
- kwargs:
Aggregation function keyword arguments.
- Returns
Collapsed cube.
For example:
>>> import iris >>> import iris.analysis >>> path = iris.sample_data_path('ostia_monthly.nc') >>> cube = iris.load_cube(path) >>> new_cube = cube.collapsed('longitude', iris.analysis.MEAN) >>> print(new_cube) surface_temperature / (K) (time: 54; latitude: 18) Dimension coordinates: time x - latitude - x Auxiliary coordinates: forecast_reference_time x - Scalar coordinates: forecast_period 0 hours longitude 180.0 degrees, bound=(0.0, 360.0) degrees Cell methods: 0 month: year: mean 1 longitude: mean Attributes: Conventions 'CF-1.5' STASH m01s00i024
Note
Some aggregations are not commutative and hence the order of processing is important i.e.:
tmp = cube.collapsed('realization', iris.analysis.VARIANCE) result = tmp.collapsed('height', iris.analysis.VARIANCE)
is not necessarily the same result as:
tmp = cube.collapsed('height', iris.analysis.VARIANCE) result2 = tmp.collapsed('realization', iris.analysis.VARIANCE)
Conversely operations which operate on more than one coordinate at the same time are commutative as they are combined internally into a single operation. Hence the order of the coordinates supplied in the list does not matter:
cube.collapsed(['longitude', 'latitude'], iris.analysis.VARIANCE)
is the same (apart from the logically equivalent cell methods that may be created etc.) as:
cube.collapsed(['latitude', 'longitude'], iris.analysis.VARIANCE)
- convert_units(unit)[source]#
Change the cube’s units, converting the values in the data array.
For example, if a cube’s
units
are kelvin then:cube.convert_units('celsius')
will change the cube’s
units
attribute to celsius and subtract 273.15 from each value indata
.This operation preserves lazy data.
- coord(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 single coordinate from the
Cube
that matches the provided criteria.Note
If the arguments given do not result in precisely one coordinate, then a
CoordinateNotFoundError
is raised.See also
Cube.coords()
for matching zero or more coordinates.Kwargs:
- name_or_coord:
Either,
a
standard_name
,long_name
, orvar_name
which is compared against thename()
.a coordinate or metadata instance equal to that of the desired coordinate e.g.,
DimCoord
orCoordMetadata
.
- standard_name:
The CF standard name of the desired coordinate. If
None
, does not check forstandard name
.
- long_name:
An unconstrained description of the coordinate. If
None
, does not check forlong_name
.
- var_name:
The NetCDF variable name of the desired coordinate. If
None
, does not check forvar_name
.
- attributes:
A dictionary of attributes desired on the coordinates. If
None
, does not check forattributes
.
- axis:
The desired coordinate axis, see
iris.util.guess_coord_axis()
. IfNone
, does not check foraxis
. Accepts the valuesX
,Y
,Z
andT
(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
orlist
i.e.,()
or[]
. IfNone
, 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 toFalse
to only return coordinates that are the cube’s auxiliary, mesh and derived coordinates. IfNone
, returns all coordinates.
- mesh_coords:
Set to
True
to return only coordinates which areMeshCoord
s. Set toFalse
to return only non-mesh coordinates. IfNone
, 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
, orvar_name
which is compared against thename()
.a coordinate or metadata instance equal to that of the desired coordinate e.g.,
DimCoord
orCoordMetadata
.
- standard_name:
The CF standard name of the desired coordinate. If
None
, does not check forstandard name
.
- long_name:
An unconstrained description of the coordinate. If
None
, does not check forlong_name
.
- var_name:
The NetCDF variable name of the desired coordinate. If
None
, does not check forvar_name
.
- attributes:
A dictionary of attributes desired on the coordinates. If
None
, does not check forattributes
.
- axis:
The desired coordinate axis, see
iris.util.guess_coord_axis()
. IfNone
, does not check foraxis
. Accepts the valuesX
,Y
,Z
andT
(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
orlist
i.e.,()
or[]
. IfNone
, 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 toFalse
to only return coordinates that are the cube’s auxiliary, mesh and derived coordinates. IfNone
, returns all coordinates.
- mesh_coords:
Set to
True
to return only coordinates which areMeshCoord
s. Set toFalse
to return only non-mesh coordinates. IfNone
, 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.
- 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:
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 iniris.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
andiris.cube.Cube.attributes
that are present in both objects.Args:
- other:
An instance of
iris.cube.Cube
oriris.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
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
MeshCoord
s, orNone
if it has none.Returns:
- mesh_dim (int, or None):
the cube dimension which the cube
MeshCoord
s map to, orNone
.
- 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:
* 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
, orvar_name
. Defaults to value of default (which itself defaults to unknown) as defined iniris.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
- 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.
See also
Cube.add_dim_coord()
andCube.add_aux_coord()
.
- 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.
- coord (string/
- aggregator (
iris.analysis.Aggregator
): Aggregator to be applied to the data.
- aggregator (
- 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()
, orancillary_variables()
with the same length as the chosen window.
- Returns
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
- 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
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 theCube.coord()
method with thedimensions
anddim_coords
keyword arguments.
- property location#
Return the mesh “location” of the cube data, if the cube has any
MeshCoord
s, orNone
if it has none.Returns:
- location (str or None):
The mesh location of the cube
MeshCoord
s (i.e. one of ‘face’ / ‘edge’ / ‘node’), orNone
.
- property mesh#
Return the unstructured
Mesh
associated with the cube, if the cube has anyMeshCoord
s, orNone
if it has none.Returns:
- mesh (
iris.experimental.ugrid.mesh.Mesh
or None): The mesh of the cube
MeshCoord
s, orNone
.
- mesh (
- 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.
- __getslice__(start, stop)[source]#
x.__getslice__(i, j) <==> x[i:j]
Use of negative indices is not supported.
- __str__()[source]#
Runs short
Cube.summary()
on every 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 concatenatediris.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 singleCube
.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.
- 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.
- constraints (
- 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.
- constraint (
- 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.
- constraints (iterable of, or single,
- 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.
- merge(unique=True)[source]#
Returns the
CubeList
resulting from merging thisCubeList
.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 singleCube
.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.