iris.common.resolve#
Resolve metadata common between two cubes.
Provides the infrastructure to support the analysis, identification and
combination of metadata common between two Cube
operands into a single resultant Cube
, which will be
auto-transposed, and with the appropriate broadcast shape.
- class iris.common.resolve.Resolve(lhs=None, rhs=None)[source]#
Bases:
object
Resolve the metadata of two cubes into one cube.
At present,
Resolve
is used by Iris solely during cube maths to combine a left-handCube
operand and a right-handCube
operand into a resultantCube
with common metadata, suitably auto-transposed dimensions, and an appropriate broadcast shape.However, the capability and benefit provided by
Resolve
may be exercised as a general means to easily and consistently combine the metadata of twoCube
operands together into a single resultantCube
. This is highlighted through the following use case patterns.Firstly, creating a
resolver
instance with specificCube
operands, and then supplyingdata
with suitable dimensionality and shape to create the resultant resolvedCube
, e.g.,>>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'A1B' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'E1' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> print(data.shape) (240, 37, 49) >>> resolver = Resolve(cube1, cube2) >>> result = resolver.cube(data) >>> print(result) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05'
Secondly, creating an empty
resolver
instance, that may be called multiple times with differentCube
operands and differentdata
, e.g.,>>> resolver = Resolve() >>> result1 = resolver(cube1, cube2).cube(data1) >>> result2 = resolver(cube3, cube4).cube(data2)
Lastly, creating a
resolver
instance with specificCube
operands, and then supply differentdata
multiple times, e.g.,>>> payload = (data1, data2, data3) >>> resolver = Resolve(cube1, cube2) >>> results = [resolver.cube(data) for data in payload]
Resolve the cube operands.
Resolve the provided
lhs
Cube
operand andrhs
Cube
operand to determine the metadata that is common between them, and the auto-transposed, broadcast shape of the resultantCube
.This includes the identification of common
CubeMetadata
,DimCoord
,AuxCoord
, andAuxCoordFactory
metadata.Note
Resolving common
AncillaryVariable
andCellMeasure
metadata is not supported at this time. (Issue #3839)Note
A
Resolve
instance is callable, allowing two newlhs
andrhs
Cube
operands to be resolved. Note that,Resolve
only supports resolving two operands at a time, and no more.Warning
Resolve
attempts to preserve commutativity, but this may not be possible when auto-transposition or extended broadcasting is involved during the operation.- Parameters:
Examples
>>> cube1 <iris 'Cube' of air_temperature / (K) (time: 240; latitude: 37; longitude: 49)> >>> cube2 <iris 'Cube' of air_temperature / (K) (longitude: 49; latitude: 37)> >>> result1 = Resolve(cube1, cube2).cube(data) >>> result2 = Resolve(cube2, cube1).cube(data) >>> result1 == result2 True
- __call__(lhs, rhs)[source]#
Resolve the cube operands.
Resolve the
lhs
Cube
operand andrhs
Cube
operand metadata.Involves determining all the common coordinate metadata shared between the operands, and the metadata that is local to each operand. Given the common metadata, the broadcast shape of the resultant resolved
Cube
, which may be auto-transposed, can be determined.
- category_common#
Categorised dim, aux and scalar coordinate items common to both the
lhs
Cube
and therhs
Cube
.
- cube(data, in_place=False)[source]#
Create the resultant resolved cube.
Create the resultant
Cube
from the resolvedlhs
andrhs
Cube
operands, using the provideddata
.- Parameters:
data – The data payload for the resultant
Cube
, which must match the expected resolvedshape
.in_place (bool, default=False) – If
True
, thedata
is inserted into thetgt
Cube
. The existing metadata of thetgt
Cube
is replaced with the resolved metadata from thelhs
andrhs
Cube
operands. Otherwise, a newCube
instance is returned. Default isFalse
.
- Return type:
Notes
Note
Resolve
will determine whether thelhs
Cube
operand is mapped to therhs
Cube
operand, or vice versa. In general, the lower rank operand (src
) is mapped to the higher rank operand (tgt
). Therefore, thesrc
Cube
may be either thelhs
or therhs
Cube
operand, given the direction of the mapping. Seemap_rhs_to_lhs
.Warning
It may not be possible to perform an
in_place
operation, due to any transposition or extended broadcasting that requires to be performed i.e., thetgt
Cube
must match the expected resolvedshape
.Examples
>>> resolver = Resolve(cube1, cube2) >>> resolver.map_rhs_to_lhs True >>> cube1.data.sum() 124652160.0 >>> zeros.shape (240, 37, 49) >>> zeros.sum() 0.0 >>> result = resolver.cube(zeros, in_place=True) >>> result is cube1 True >>> cube1.data.sum() 0.0
- lhs_cube_category_local#
Categorised dim, aux and scalar coordinate items local to the
lhs
Cube
only.
- lhs_cube_resolved#
The transposed/reshaped (if required)
lhs
Cube
, which can be broadcast with therhs
Cube
.
- map_rhs_to_lhs#
Map common metadata from the
rhs
Cube
to thelhs
Cube
iflhs-rank
>=rhs-rank
, otherwise map common metadata from thelhs
Cube
to therhs
Cube
.
- property mapped#
Whether all
src
dimensions have been mapped.Boolean state representing whether all
src
Cube
dimensions have been associated with relevanttgt
Cube
dimensions.Note
Resolve
will determine whether thelhs
Cube
operand is mapped to therhs
Cube
operand, or vice versa. In general, the lower rank operand (src
) is mapped to the higher rank operand (tgt
). Therefore, thesrc
Cube
may be either thelhs
or therhs
Cube
operand, given the direction of the mapping. Seemap_rhs_to_lhs
.If no
Cube
operands have been provided, thenmapped
isNone
.For example:
>>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'A1B' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'E1' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> Resolve().mapped is None True >>> resolver = Resolve(cube1, cube2) >>> resolver.mapped True >>> resolver.map_rhs_to_lhs True >>> resolver = Resolve(cube2, cube1) >>> resolver.mapped True >>> resolver.map_rhs_to_lhs False
- mapping#
Mapping of the dimensions between common metadata for the
Cube
operands, where the direction of the mapping is governed bymap_rhs_to_lhs
.
- prepared_category#
Cache containing a list of dim, aux and scalar coordinates prepared and ready for creating and attaching to the resultant resolved
Cube
.
- prepared_factories#
Cache containing a list of aux factories prepared and ready for creating and attaching to the resultant resolved
Cube
.
- rhs_cube_category_local#
Categorised dim, aux and scalar coordinate items local to the
rhs
Cube
only.
- rhs_cube_resolved#
The transposed/reshaped (if required)
rhs
Cube
, which can be broadcast with thelhs
Cube
.
- property shape#
Proposed shape of the final resolved cube.
Proposed shape of the final resolved cube given the
lhs
Cube
operand and therhs
Cube
operand.If no
Cube
operands have been provided, thenshape
isNone
.For example:
>>> print(cube1) air_temperature / (K) (time: 240; latitude: 37; longitude: 49) Dimension coordinates: time x - - latitude - x - longitude - - x Auxiliary coordinates: forecast_period x - - Scalar coordinates: forecast_reference_time 1859-09-01 06:00:00 height 1.5 m Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'A1B' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> print(cube2) air_temperature / (K) (longitude: 49; latitude: 37) Dimension coordinates: longitude x - latitude - x Scalar coordinates: forecast_period 10794 hours forecast_reference_time 1859-09-01 06:00:00 height 1.5 m time 1860-06-01 00:00:00, bound=(1859-12-01 00:00:00, 1860-12-01 00:00:00) Cell methods: 0 time: mean (interval: 6 hour) Attributes: Conventions 'CF-1.5' Model scenario 'E1' STASH m01s03i236 source 'Data from Met Office Unified Model 6.05' >>> Resolve().shape is None True >>> Resolve(cube1, cube2).shape (240, 37, 49) >>> Resolve(cube2, cube1).shape (240, 37, 49)