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-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:
        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 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]

Resolve the cube operands.

Resolve the provided lhs Cube operand and rhs Cube operand to determine the metadata that is common between them, and the auto-transposed, broadcast shape of the resultant Cube.

This includes the identification of common CubeMetadata, DimCoord, AuxCoord, and AuxCoordFactory metadata.

Note

Resolving common AncillaryVariable and CellMeasure metadata is not supported at this time. (Issue #3839)

Note

A Resolve instance is callable, allowing two new lhs and rhs 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:

lhs (Cube, optional) – The left-hand-side Cube operand.
rhs (Cube, optional) – The right-hand-side Cube operand.

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 and rhs 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.

Parameters:

lhs (Cube) – The left-hand-side Cube operand.
rhs (Cube) – The right-hand-side Cube operand.

category_common#: Categorised dim, aux and scalar coordinate items common to both the lhs Cube and the rhs Cube.

cube(data, in_place=False)[source]#

Create the resultant resolved cube.

Create the resultant Cube from the resolved lhs and rhs Cube operands, using the provided data.

Parameters:

data – The data payload for the resultant Cube, which must match the expected resolved shape.
in_place (bool, default=False) – If True, the data is inserted into the tgt Cube. The existing metadata of the tgt Cube is replaced with the resolved metadata from the lhs and rhs Cube operands. Otherwise, a new Cube instance is returned. Default is False.

Return type:

Cube

Notes

Note

Resolve will determine whether the lhs Cube operand is mapped to the rhs Cube operand, or vice versa. In general, the lower rank operand (src) is mapped to the higher rank operand (tgt). Therefore, the src Cube may be either the lhs or the rhs Cube operand, given the direction of the mapping. See map_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., the tgt Cube must match the expected resolved shape.

Examples

>>> resolver = Resolve(cube1, cube2)
>>> resolver.map_rhs_to_lhs
True
>>> cube1.data.sum()
np.float32(1.2465214e+08)
>>> zeros.shape
(240, 37, 49)
>>> zeros.sum()
np.float32(0.0)
>>> result = resolver.cube(zeros, in_place=True)
>>> result is cube1
True
>>> cube1.data.sum()
np.float32(0.0)

lhs_cube#: The lhs operand to be resolved into the resultant Cube.

lhs_cube_aux_coverage#: Analysis of aux and scalar coordinates spanning the lhs Cube.

lhs_cube_category#: Categorised dim, aux and scalar coordinate items for lhs Cube.

lhs_cube_category_local#: Categorised dim, aux and scalar coordinate items local to the lhs Cube only.

lhs_cube_dim_coverage#: Analysis of dim coordinates spanning the lhs Cube.

lhs_cube_resolved#: The transposed/reshaped (if required) lhs Cube, which can be broadcast with the rhs Cube.

map_rhs_to_lhs#: Map common metadata from the rhs Cube to the lhs Cube if lhs-rank >= rhs-rank, otherwise map common metadata from the lhs Cube to the rhs Cube.

property mapped#

Whether all src dimensions have been mapped.

Boolean state representing whether all src Cube dimensions have been associated with relevant tgt Cube dimensions.

Note

Resolve will determine whether the lhs Cube operand is mapped to the rhs Cube operand, or vice versa. In general, the lower rank operand (src) is mapped to the higher rank operand (tgt). Therefore, the src Cube may be either the lhs or the rhs Cube operand, given the direction of the mapping. See map_rhs_to_lhs.

If no Cube operands have been provided, then mapped is None.

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 by map_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#: The rhs operand to be resolved into the resultant Cube.

rhs_cube_aux_coverage#: Analysis of aux and scalar coordinates spanning the rhs Cube.

rhs_cube_category#: Categorised dim, aux and scalar coordinate items for rhs Cube.

rhs_cube_category_local#: Categorised dim, aux and scalar coordinate items local to the rhs Cube only.

rhs_cube_dim_coverage#: Analysis of dim coordinates spanning the rhs Cube.

rhs_cube_resolved#: The transposed/reshaped (if required) rhs Cube, which can be broadcast with the lhs Cube.

property shape#

Proposed shape of the final resolved cube.

Proposed shape of the final resolved cube given the lhs Cube operand and the rhs Cube operand.

If no Cube operands have been provided, then shape is None.

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)