iris.loading#

Iris file loading support.

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

A control object containing the current file loading strategy options.

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

Bases: CombineOptions

A control object for Iris loading options.

Incorporates all the settings of a CombineOptions, and adds the support_multiple_references control.

IN addition to controlling “combine” operation during loading, this also controls the detection and handling of cases where a hybrid coordinate uses multiple reference fields during loading : for example, a UM file which contains a series of fields describing a time-varying orography.

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

Note

The default behaviour will “fix” loading for cases like the time-varying orography case described above. However, this is not strictly backwards-compatible. If this causes problems, you can force identical loading behaviour to earlier Iris versions with LOAD_POLICY.set("legacy") or equivalent.

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': True}, 'recommended': {'merge_concat_sequence': 'mc', 'repeat_until_unchanged': False, 'support_multiple_references': True}}#
SETTING_NAMES = ('legacy', 'default', 'recommended', 'comprehensive')#
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

>>> # Show how a CombineOptions acts in the context of a load operation
>>> path = sample_data_path("time_varying_hybrid_height", "*.pp")
>>> # "legacy" load behaviour allows merge but not concatenate
>>> with LOAD_POLICY.context("legacy"):
...     cubes = iris.load(path, "x_wind")
>>> print(cubes)
0: x_wind / (m s-1)                    (time: 2; model_level_number: 5; latitude: 144; longitude: 192)
1: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
2: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)
>>>
>>> # "recommended" behaviour enables concatenation also
>>> with LOAD_POLICY.context("recommended"):
...     cubes = iris.load(path, "x_wind")
>>> print(cubes)
0: x_wind / (m s-1)                    (model_level_number: 5; time: 15; latitude: 144; longitude: 192)
set(options=None, **kwargs)#

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()#

Return an options dict containing the current settings.

iris.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.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.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.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