iris.fileformats.rules

Generalised mechanisms for metadata translation and cube construction.

In this module:

iris.fileformats.rules.aux_factory(cube, aux_factory_class)

Return the class:~iris.aux_factory.AuxCoordFactory instance of the specified type from a cube.

↑ top ↑

iris.fileformats.rules.calculate_forecast_period(time, forecast_reference_time)

Return the forecast period in hours derived from time and forecast_reference_time scalar coordinates.

Deprecated since version 1.10.

↑ top ↑

iris.fileformats.rules.has_aux_factory(cube, aux_factory_class)

Try to find an class:~iris.aux_factory.AuxCoordFactory instance of the specified type on the cube.

↑ top ↑

iris.fileformats.rules.load_cubes(filenames, user_callback, loader, filter_function=None)

↑ top ↑

iris.fileformats.rules.load_pairs_from_fields(fields, converter)

Convert an iterable of fields into an iterable of Cubes using the provided convertor.

Args:

  • fields:

    An iterable of fields.

  • convertor:

    An Iris convertor function, suitable for use with the supplied fields. See the description in iris.fileformats.rules.Loader.

Returns:
An iterable of (iris.cube.Cube, field) pairs.

↑ top ↑

iris.fileformats.rules.log(*args, **kwargs)

↑ top ↑

iris.fileformats.rules.scalar_cell_method(cube, method, coord_name)

Try to find the given type of cell method over a single coord with the given name.

↑ top ↑

iris.fileformats.rules.scalar_coord(cube, coord_name)

Try to find a single-valued coord with the given name.

↑ top ↑

iris.fileformats.rules.vector_coord(cube, coord_name)

Try to find a one-dimensional, multi-valued coord with the given name.

↑ top ↑

Used by the rules for defining attributes on the Cube in a consistent manner.

Deprecated since version 1.10.

class iris.fileformats.rules.CMAttribute(name, value)

Bases: object

Used by the rules for defining attributes on the Cube in a consistent manner.

Deprecated since version 1.10.

name
value

↑ top ↑

Used by the rules for defining custom attributes on the Cube in a consistent manner.

Deprecated since version 1.10.

class iris.fileformats.rules.CMCustomAttribute(name, value)

Bases: object

Used by the rules for defining custom attributes on the Cube in a consistent manner.

Deprecated since version 1.10.

name
value

↑ top ↑

Everything you need to make a real Cube for a named reference.

class iris.fileformats.rules.ConcreteReferenceTarget(name, transform=None)

Bases: object

Everything you need to make a real Cube for a named reference.

add_cube(cube)
as_cube()

↑ top ↑

ConversionMetadata(factories, references, standard_name, long_name, units, attributes, cell_methods, dim_coords_and_dims, aux_coords_and_dims)

class iris.fileformats.rules.ConversionMetadata(_cls, factories, references, standard_name, long_name, units, attributes, cell_methods, dim_coords_and_dims, aux_coords_and_dims)

Bases: tuple

Create new instance of ConversionMetadata(factories, references, standard_name, long_name, units, attributes, cell_methods, dim_coords_and_dims, aux_coords_and_dims)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

attributes

Alias for field number 5

aux_coords_and_dims

Alias for field number 8

cell_methods

Alias for field number 6

dim_coords_and_dims

Alias for field number 7

factories

Alias for field number 0

long_name

Alias for field number 3

references

Alias for field number 1

standard_name

Alias for field number 2

units

Alias for field number 4

↑ top ↑

Used within rules to represent a mapping of coordinate to data dimensions.

Deprecated since version 1.10.

class iris.fileformats.rules.CoordAndDims(coord, dims=None)

Bases: object

Used within rules to represent a mapping of coordinate to data dimensions.

Deprecated since version 1.10.

add_coord(cube)

↑ top ↑

Used by the rules for debug purposes

Deprecated since version 1.10.

class iris.fileformats.rules.DebugString(*args, **kwargs)

Bases: str

Used by the rules for debug purposes

Deprecated since version 1.10.

capitalize() → string

Return a copy of the string S with only its first character capitalized.

center(width[, fillchar]) → string

Return S centered in a string of length width. Padding is done using the specified fill character (default is a space)

count(sub[, start[, end]]) → int

Return the number of non-overlapping occurrences of substring sub in string S[start:end]. Optional arguments start and end are interpreted as in slice notation.

decode([encoding[, errors]]) → object

Decodes S using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeDecodeError. Other possible values are ‘ignore’ and ‘replace’ as well as any other name registered with codecs.register_error that is able to handle UnicodeDecodeErrors.

encode([encoding[, errors]]) → object

Encodes S using the codec registered for encoding. encoding defaults to the default encoding. errors may be given to set a different error handling scheme. Default is ‘strict’ meaning that encoding errors raise a UnicodeEncodeError. Other possible values are ‘ignore’, ‘replace’ and ‘xmlcharrefreplace’ as well as any other name registered with codecs.register_error that is able to handle UnicodeEncodeErrors.

endswith(suffix[, start[, end]]) → bool

Return True if S ends with the specified suffix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. suffix can also be a tuple of strings to try.

expandtabs([tabsize]) → string

Return a copy of S where all tab characters are expanded using spaces. If tabsize is not given, a tab size of 8 characters is assumed.

find(sub[, start[, end]]) → int

Return the lowest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

format(*args, **kwargs) → string

Return a formatted version of S, using substitutions from args and kwargs. The substitutions are identified by braces (‘{‘ and ‘}’).

index(sub[, start[, end]]) → int

Like S.find() but raise ValueError when the substring is not found.

isalnum() → bool

Return True if all characters in S are alphanumeric and there is at least one character in S, False otherwise.

isalpha() → bool

Return True if all characters in S are alphabetic and there is at least one character in S, False otherwise.

isdigit() → bool

Return True if all characters in S are digits and there is at least one character in S, False otherwise.

islower() → bool

Return True if all cased characters in S are lowercase and there is at least one cased character in S, False otherwise.

isspace() → bool

Return True if all characters in S are whitespace and there is at least one character in S, False otherwise.

istitle() → bool

Return True if S is a titlecased string and there is at least one character in S, i.e. uppercase characters may only follow uncased characters and lowercase characters only cased ones. Return False otherwise.

isupper() → bool

Return True if all cased characters in S are uppercase and there is at least one cased character in S, False otherwise.

join(iterable) → string

Return a string which is the concatenation of the strings in the iterable. The separator between elements is S.

ljust(width[, fillchar]) → string

Return S left-justified in a string of length width. Padding is done using the specified fill character (default is a space).

lower() → string

Return a copy of the string S converted to lowercase.

lstrip([chars]) → string or unicode

Return a copy of the string S with leading whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is unicode, S will be converted to unicode before stripping

partition(sep) -> (head, sep, tail)

Search for the separator sep in S, and return the part before it, the separator itself, and the part after it. If the separator is not found, return S and two empty strings.

replace(old, new[, count]) → string

Return a copy of string S with all occurrences of substring old replaced by new. If the optional argument count is given, only the first count occurrences are replaced.

rfind(sub[, start[, end]]) → int

Return the highest index in S where substring sub is found, such that sub is contained within S[start:end]. Optional arguments start and end are interpreted as in slice notation.

Return -1 on failure.

rindex(sub[, start[, end]]) → int

Like S.rfind() but raise ValueError when the substring is not found.

rjust(width[, fillchar]) → string

Return S right-justified in a string of length width. Padding is done using the specified fill character (default is a space)

rpartition(sep) -> (head, sep, tail)

Search for the separator sep in S, starting at the end of S, and return the part before it, the separator itself, and the part after it. If the separator is not found, return two empty strings and S.

rsplit([sep[, maxsplit]]) → list of strings

Return a list of the words in the string S, using sep as the delimiter string, starting at the end of the string and working to the front. If maxsplit is given, at most maxsplit splits are done. If sep is not specified or is None, any whitespace string is a separator.

rstrip([chars]) → string or unicode

Return a copy of the string S with trailing whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is unicode, S will be converted to unicode before stripping

split([sep[, maxsplit]]) → list of strings

Return a list of the words in the string S, using sep as the delimiter string. If maxsplit is given, at most maxsplit splits are done. If sep is not specified or is None, any whitespace string is a separator and empty strings are removed from the result.

splitlines(keepends=False) → list of strings

Return a list of the lines in S, breaking at line boundaries. Line breaks are not included in the resulting list unless keepends is given and true.

startswith(prefix[, start[, end]]) → bool

Return True if S starts with the specified prefix, False otherwise. With optional start, test S beginning at that position. With optional end, stop comparing S at that position. prefix can also be a tuple of strings to try.

strip([chars]) → string or unicode

Return a copy of the string S with leading and trailing whitespace removed. If chars is given and not None, remove characters in chars instead. If chars is unicode, S will be converted to unicode before stripping

swapcase() → string

Return a copy of the string S with uppercase characters converted to lowercase and vice versa.

title() → string

Return a titlecased version of S, i.e. words start with uppercase characters, all remaining cased characters have lowercase.

translate(table[, deletechars]) → string

Return a copy of the string S, where all characters occurring in the optional argument deletechars are removed, and the remaining characters have been mapped through the given translation table, which must be a string of length 256 or None. If the table argument is None, no translation is applied and the operation simply removes the characters in deletechars.

upper() → string

Return a copy of the string S converted to uppercase.

zfill(width) → string

Pad a numeric string S with zeros on the left, to fill a field of the specified width. The string S is never truncated.

↑ top ↑

Factory(factory_class, args)

class iris.fileformats.rules.Factory(_cls, factory_class, args)

Bases: tuple

Create new instance of Factory(factory_class, args)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

args

Alias for field number 1

factory_class

Alias for field number 0

↑ top ↑

A Rule with values returned by its actions.

Deprecated since version 1.10.

class iris.fileformats.rules.FunctionRule(conditions, actions)

Bases: iris.fileformats.rules.Rule

Create instance methods from our conditions and actions.

evaluates_true(cube, field)

Returns True if and only if all the conditions evaluate to True for the given field.

run_actions(cube, field)

Adds to the given cube based on the return values of all the actions.

↑ top ↑

None

class iris.fileformats.rules.Loader(field_generator, field_generator_kwargs, converter, legacy_custom_rules=None)

Bases: iris.fileformats.rules.Loader

Create a definition of a field-based Cube loader.

Args:

  • field_generator

    A callable that accepts a filename as its first argument and returns an iterable of field objects.

  • field_generator_kwargs

    Additional arguments to be passed to the field_generator.

  • converter

    A callable that converts a field object into a Cube.

Kwargs:

  • legacy_custom_rules

    An object with a callable verify attribute with two parameters: (cube, field). Legacy method for modifying Cubes during the load process. Default is None.

    Deprecated since version 1.9.

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

converter

Alias for field number 2

field_generator

Alias for field number 0

field_generator_kwargs

Alias for field number 1

legacy_custom_rules

Alias for field number 3

↑ top ↑

A Rule with nothing returned by its actions.

Deprecated since version 1.10.

class iris.fileformats.rules.ProcedureRule(conditions, actions)

Bases: iris.fileformats.rules.Rule

Create instance methods from our conditions and actions.

conditional_warning(condition, warning)
evaluates_true(cube, field)

Returns True if and only if all the conditions evaluate to True for the given field.

run_actions(cube, field)

Adds to the given cube based on the return values of all the actions.

↑ top ↑

None

class iris.fileformats.rules.Reference(name)

Bases: iris.util._OrderedHashable

↑ top ↑

ReferenceTarget(name, transform)

class iris.fileformats.rules.ReferenceTarget(_cls, name, transform)

Bases: tuple

Create new instance of ReferenceTarget(name, transform)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

name

Alias for field number 0

transform

Alias for field number 1

↑ top ↑

A collection of condition expressions and their associated action expressions.

Example rule:

IF
    f.lbuser[6] == 2
    f.lbuser[3] == 101
THEN
    CMAttribute('standard_name', 'sea_water_potential_temperature')
    CMAttribute('units', 'Celsius')

Deprecated since version 1.10.

class iris.fileformats.rules.Rule(conditions, actions)

Bases: object

Create instance methods from our conditions and actions.

evaluates_true(cube, field)

Returns True if and only if all the conditions evaluate to True for the given field.

run_actions(cube, field)

Adds to the given cube based on the return values of all the actions.

↑ top ↑

RuleResult(cube, matching_rules, factories)

class iris.fileformats.rules.RuleResult(_cls, cube, matching_rules, factories)

Bases: tuple

Create new instance of RuleResult(cube, matching_rules, factories)

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

cube

Alias for field number 0

factories

Alias for field number 2

matching_rules

Alias for field number 1

↑ top ↑

A collection of Rule instances, with the ability to read rule definitions from files and run the rules against given fields.

Deprecated since version 1.10.

class iris.fileformats.rules.RulesContainer(filepath=None, rule_type=<class 'iris.fileformats.rules.FunctionRule'>)

Bases: object

Create a new rule set, optionally adding rules from the specified file.

The rule_type defaults to FunctionRule, e.g for CM loading actions that return objects, such as AuxCoord(...)

rule_type can also be set to ProcedureRule e.g for PP saving actions that do not return anything, such as pp.lbuser[3] = 16203

import_rules(filepath)

Extend the rule collection with the rules defined in the specified file.

verify(cube, field)

Add to the given iris.cube.Cube by running this set of rules with the given field.

Args:

  • cube:

    An instance of iris.cube.Cube.

  • field:

    A field object relevant to the rule set.

Returns: (cube, matching_rules)

  • cube - the resultant cube
  • matching_rules - a list of rules which matched