iris.io.loading#

Loading mechanism and functions.

iris.io.loading.LOAD_POLICY = LoadPolicy(support_multiple_references=False, merge_concat_sequence='m', repeat_until_unchanged=False)#

Object containing file loading options.

class iris.io.loading.LoadPolicy(options=None, **kwargs)[source]#

Bases: _local

A container for loading strategy options.

Controls merge/concatenate usage, and the handling of cases where multiple reference fields merge to define an additional dimension (e.g. a time-varying orography).

Options can be set directly, or via set(), or changed for the scope of a code block with context().

Notes

The individual configurable options are :

  • support_multiple_references = True / False

    When enabled, the presence of multiple aux-factory reference cubes, which merge to define a extra dimension, will add that dimension to the loaded cubes. This is essential for correct support of time-dependent hybrid coordinates (i.e. aux factories) when loading from fields-based data (e.g. PP or GRIB). For example (notably) time-dependent orography in UM data on hybrid-heights.

    In addition, when such multiple references are detected, an extra concatenate step is added to the ‘merge_concat_sequence’ (see below), if none is already configured there.

  • merge_concat_sequence = “m” / “c” / “cm” / “mc”

    Specifies whether to merge, or concatenate, or both in either order. This is the combine_cubes() operation to loaded data.

  • repeat_until_unchanged = True / False

    When enabled, the configured “combine” operation will be repeated until the result is stable (no more cubes are combined).

Several common sets of options are provided in SETTINGS :

  • "legacy"

    Produces results identical to Iris versions < 3.11, i.e. before the varying hybrid references were supported.

  • "default"

    As “legacy” except that support_multiple_references=True. This differs from “legacy” only when multiple mergeable reference fields are encountered, in which case incoming cubes are extended into the extra dimension, and a concatenate step is added.

  • "recommended"

    Enables multiple reference handling, and applies a merge step followed by a concatenate step.

  • "comprehensive"

    Like “recommended”, but will also repeat the merge+concatenate steps until no further change is produced.

    Note

    The ‘comprehensive’ policy makes a maximum effort to reduce the number of cubes to a minimum. However, it still cannot combine cubes with a mixture of matching dimension and scalar coordinates. This may be supported at some later date, but for now is not possible without specific user actions.

Note

See also : Controlling Merge and Concatenate.

Examples

>>> LOAD_POLICY.set("legacy")
>>> print(LOAD_POLICY)
LoadPolicy(support_multiple_references=False, merge_concat_sequence='m', repeat_until_unchanged=False)
>>> LOAD_POLICY.support_multiple_references = True
>>> print(LOAD_POLICY)
LoadPolicy(support_multiple_references=True, merge_concat_sequence='m', repeat_until_unchanged=False)
>>> LOAD_POLICY.set(merge_concat_sequence="cm")
>>> print(LOAD_POLICY)
LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)
>>> with LOAD_POLICY.context("comprehensive"):
...    print(LOAD_POLICY)
LoadPolicy(support_multiple_references=True, merge_concat_sequence='mc', repeat_until_unchanged=True)
>>> print(LOAD_POLICY)
LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)

Create loading strategy control object.

Parameters:

options (str | dict | None)

OPTION_KEYS = ('support_multiple_references', 'merge_concat_sequence', 'repeat_until_unchanged')#
SETTINGS = {'comprehensive': {'merge_concat_sequence': 'mc', 'repeat_until_unchanged': True, 'support_multiple_references': True}, 'default': {'merge_concat_sequence': 'm', 'repeat_until_unchanged': False, 'support_multiple_references': True}, 'legacy': {'merge_concat_sequence': 'm', 'repeat_until_unchanged': False, 'support_multiple_references': False}, 'recommended': {'merge_concat_sequence': 'mc', 'repeat_until_unchanged': False, 'support_multiple_references': True}}#
context(settings=None, **kwargs)[source]#

Return a context manager applying given options.

Parameters:

  • settings (str or dict) – Options dictionary or name, as for set().

  • kwargs (dict) – Option values, as for set().

Examples

>>> path = sample_data_path("time_varying_hybrid_height", "*.pp")
>>> with LOAD_POLICY.context("legacy"):
...     cubes = iris.load(path)
>>> print(cubes)
0: surface_altitude / (m)              (time: 15; latitude: 144; longitude: 192)
1: x_wind / (m s-1)                    (time: 2; model_level_number: 5; latitude: 144; longitude: 192)
2: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
3: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)

>>> with LOAD_POLICY.context("recommended"):
...     cube = iris.load_cube(path, "x_wind")
>>> cube
<iris 'Cube' of x_wind / (m s-1) (model_level_number: 5; time: 15; latitude: 144; longitude: 192)>
set(options=None, **kwargs)[source]#

Set new options.

Parameters:

  • options (*) – A dictionary of options values, or the name of one of the SETTINGS standard option sets, e.g. “legacy” or “comprehensive”.

  • kwargs (*) – Individual option settings, from OPTION_KEYS.

Note

Keyword arguments are applied after the ‘options’ arg, and so will take precedence.

settings()[source]#

Return an options dict containing the current settings.

iris.io.loading.combine_cubes(cubes, options=None, merge_require_unique=False, **kwargs)[source]#

Combine cubes as for load, according to “loading policy” options.

Applies merge()/concatenate() steps to the given cubes, as determined by the ‘settings’.

Parameters:

  • cubes (list of Cube) – A list of cubes to combine.

  • options (dict or str) – Settings, as described for iris.LOAD_POLICY.set(). Defaults to current iris.LOAD_POLICY.settings().

  • merge_require_unique (bool) – Value for the ‘unique’ keyword in any merge operations.

  • kwargs (dict) – Individual settings, as described for iris.LOAD_POLICY.set().

Returns:

  • list of Cube

  • .. Note:: – The support_multiple_references keyword/property has no effect on the combine_cubes() operation : it only takes effect during a load operation.

iris.io.loading.load(uris, constraints=None, callback=None)[source]#

Load any number of Cubes for each constraint.

For a full description of the arguments, please see the module documentation for iris.

Parameters:

  • uris (str or pathlib.PurePath) – One or more filenames/URIs, as a string or pathlib.PurePath. If supplying a URL, only OPeNDAP Data Sources are supported.

  • constraints (optional) – One or more constraints.

  • callback (optional) – A modifier/filter function.

Returns:

An iris.cube.CubeList. Note that there is no inherent order to this iris.cube.CubeList and it should be treated as if it were random.

Return type:

iris.cube.CubeList

iris.io.loading.load_cube(uris, constraint=None, callback=None)[source]#

Load a single cube.

For a full description of the arguments, please see the module documentation for iris.

Parameters:

  • uris – One or more filenames/URIs, as a string or pathlib.PurePath. If supplying a URL, only OPeNDAP Data Sources are supported.

  • constraints (optional) – A constraint.

  • callback (optional) – A modifier/filter function.

Return type:

iris.cube.Cube

iris.io.loading.load_cubes(uris, constraints=None, callback=None)[source]#

Load exactly one Cube for each constraint.

For a full description of the arguments, please see the module documentation for iris.

Parameters:

  • uris – One or more filenames/URIs, as a string or pathlib.PurePath. If supplying a URL, only OPeNDAP Data Sources are supported.

  • constraints (optional) – One or more constraints.

  • callback (optional) – A modifier/filter function.

Returns:

An iris.cube.CubeList. Note that there is no inherent order to this iris.cube.CubeList and it should be treated as if it were random.

Return type:

iris.cube.CubeList

iris.io.loading.load_raw(uris, constraints=None, callback=None)[source]#

Load non-merged cubes.

This function is provided for those occasions where the automatic combination of cubes into higher-dimensional cubes is undesirable. However, it is intended as a tool of last resort! If you experience a problem with the automatic combination process then please raise an issue with the Iris developers.

For a full description of the arguments, please see the module documentation for iris.

Parameters:

  • uris – One or more filenames/URIs, as a string or pathlib.PurePath. If supplying a URL, only OPeNDAP Data Sources are supported.

  • constraints (optional) – One or more constraints.

  • callback (optional) – A modifier/filter function.

Return type:

iris.cube.CubeList