iris.common.resolve
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.
In this module:
At present, Resolve
is used by Iris solely
during cube maths to combine a left-hand Cube
operand and a right-hand Cube
operand into a resultant
Cube
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 two Cube
operands together into a single resultant
Cube
. This is highlighted through the following use case
patterns.
Firstly, creating a resolver
instance with specific Cube
operands, and then supplying data
with suitable dimensionality and shape to
create the resultant resolved Cube
, 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:
mean time (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:
mean time (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:
mean time (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 different Cube
operands and different data
,
e.g.,
>>> resolver = Resolve()
>>> result1 = resolver(cube1, cube2).cube(data1)
>>> result2 = resolver(cube3, cube4).cube(data2)
Lastly, creating a resolver
instance with specific Cube
operands, and then supply different data
multiple times, e.g.,
>>> payload = (data1, data2, data3)
>>> resolver = Resolve(cube1, cube2)
>>> results = [resolver.cube(data) for data in payload]
- class iris.common.resolve.Resolve(lhs=None, rhs=None)[source]
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.For example:
>>> 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 TrueKwargs:
- __call__(lhs, rhs)[source]
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.Args:
- cube(data, in_place=False)[source]
Create the resultant
Cube
from the resolvedlhs
andrhs
Cube
operands, using the provideddata
.Args:
Kwargs:
- Returns
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
.For example:
>>> 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
- category_common
Categorised dim, aux and scalar coordinate items common to both the
lhs
Cube
and therhs
Cube
.
- 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
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: mean time (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: mean time (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 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: mean time (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: mean time (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)