iris.fileformats.pp

Provides UK Met Office Post Process (PP) format specific capabilities.

In this module:

iris.fileformats.pp.load(filename, read_data=False, little_ended=False)

Return an iterator of PPFields given a filename.

Args:

  • filename - string of the filename to load.

Kwargs:

  • read_data - boolean

    Flag whether or not the data should be read, if False an empty data manager will be provided which can subsequently load the data on demand. Default False.

  • little_ended - boolean

    If True, file contains all little-ended words (header and data).

To iterate through all of the fields in a pp file:

for field in iris.fileformats.pp.load(filename):
    print(field)

↑ top ↑

iris.fileformats.pp.save(cube, target, append=False, field_coords=None)

Use the PP saving rules (and any user rules) to save a cube to a PP file.

Args:

Kwargs:

  • append - Whether to start a new file afresh or add the cube(s)

    to the end of the file. Only applicable when target is a filename, not a file handle. Default is False.

  • field_coords - list of 2 coords or coord names which are to be used

    for reducing the given cube into 2d slices, which will ultimately determine the x and y coordinates of the resulting fields. If None, the final two dimensions are chosen for slicing.

See also iris.io.save().

↑ top ↑

iris.fileformats.pp.load_cubes(filenames, callback=None, constraints=None)

Loads cubes from a list of pp filenames.

Args:

  • filenames - list of pp filenames to load

Kwargs:

  • constraints - a list of Iris constraints

  • callback - a function which can be passed on to

    iris.io.run_callback()

Note

The resultant cubes may not be in the order that they are in the file (order is not preserved when there is a field with orography references)

↑ top ↑

A generic class for PP fields - not specific to a particular header release number.

A PPField instance can easily access the PP header “words” as attributes with some added useful capabilities:

for field in iris.fileformats.pp.load(filename):
    print(field.lbyr)
    print(field.lbuser)
    print(field.lbuser[0])
    print(field.lbtim)
    print(field.lbtim.ia)
    print(field.t1)
class iris.fileformats.pp.PPField(header=None)

Bases: object

A generic class for PP fields - not specific to a particular header release number.

A PPField instance can easily access the PP header “words” as attributes with some added useful capabilities:

for field in iris.fileformats.pp.load(filename):
    print(field.lbyr)
    print(field.lbuser)
    print(field.lbuser[0])
    print(field.lbtim)
    print(field.lbtim.ia)
    print(field.t1)
coord_system()

Return a CoordSystem for this PPField.

Returns:
Currently, a GeogCS or RotatedGeogCS.
copy()

Returns a deep copy of this PPField.

Returns:
A copy instance of the PPField.
save(file_handle)

Save the PPField to the given file object (typically created with open()).

# to append the field to a file
with open(filename, 'ab') as fh:
    a_pp_field.save(fh)

# to overwrite/create a file
with open(filename, 'wb') as fh:
    a_pp_field.save(fh)

Note

The fields which are automatically calculated are: ‘lbext’, ‘lblrec’ and ‘lbuser[0]’. Some fields are not currently populated, these are: ‘lbegin’, ‘lbnrec’, ‘lbuser[1]’.

time_unit(time_unit, epoch='epoch')
calendar

Return the calendar of the field.

data

The numpy.ndarray representing the multidimensional data of the pp file

lbcode
lbpack
lbproc
lbtim
stash

A stash property giving access to the associated STASH object, now supporting __eq__

t1
t2
x_bounds
y_bounds

↑ top ↑

iris.fileformats.pp.reset_load_rules()

Resets the PP load process to use only the standard conversion rules.

Deprecated since version 1.7.

↑ top ↑

iris.fileformats.pp.add_save_rules(filename)

Registers a rules file for use during the PP save process.

Registered files are processed after the standard conversion rules, and in the order they were registered.

Deprecated since version 1.10: If you need to customise pp field saving, please refer to the functions as_fields(), save_pairs_from_cube() and save_fields() for an alternative solution.

↑ top ↑

iris.fileformats.pp.as_fields(cube, field_coords=None, target=None)

Use the PP saving rules (and any user rules) to convert a cube to an iterable of PP fields.

Args:

Kwargs:

  • field_coords:

    List of 2 coords or coord names which are to be used for reducing the given cube into 2d slices, which will ultimately determine the x and y coordinates of the resulting fields. If None, the final two dimensions are chosen for slicing.

  • target:

    A filename or open file handle.

↑ top ↑

iris.fileformats.pp.load_pairs_from_fields(pp_fields)

Convert an iterable of PP fields into an iterable of tuples of (Cubes, PPField).

Args:

Returns:
An iterable of :class:`iris.cube.Cube`s.

This capability can be used to filter out fields before they are passed to the load pipeline, and amend the cubes once they are created, using PP metadata conditions. Where this filtering removes a significant number of fields, the speed up to load can be significant:

>>> import iris
>>> from iris.fileformats.pp import load_pairs_from_fields
>>> filename = iris.sample_data_path('E1.2098.pp')
>>> filtered_fields = []
>>> for field in iris.fileformats.pp.load(filename):
...     if field.lbproc == 128:
...         filtered_fields.append(field)
>>> cube_field_pairs = load_pairs_from_fields(filtered_fields)
>>> for cube, field in cube_field_pairs:
...     cube.attributes['lbproc'] = field.lbproc
...     print(cube.attributes['lbproc'])
128

This capability can also be used to alter fields before they are passed to the load pipeline. Fields with out of specification header elements can be cleaned up this way and cubes created:

>>> filename = iris.sample_data_path('E1.2098.pp')
>>> cleaned_fields = list(iris.fileformats.pp.load(filename))
>>> for field in cleaned_fields:
...     if field.lbrel == 0:
...         field.lbrel = 3
>>> cubes_field_pairs = list(load_pairs_from_fields(cleaned_fields))

↑ top ↑

iris.fileformats.pp.as_pairs(cube, field_coords=None, target=None)

Deprecated since version 1.10.

Please use iris.fileformats.pp.save_pairs_from_cube() for the same functionality.

↑ top ↑

iris.fileformats.pp.save_pairs_from_cube(cube, field_coords=None, target=None)

Use the PP saving rules (and any user rules) to convert a cube or iterable of cubes to an iterable of (2D cube, PP field) pairs.

Args:

Kwargs:

  • field_coords:

    List of 2 coords or coord names which are to be used for reducing the given cube into 2d slices, which will ultimately determine the x and y coordinates of the resulting fields. If None, the final two dimensions are chosen for slicing.

  • target:

    A filename or open file handle.

↑ top ↑

iris.fileformats.pp.reset_save_rules()

Resets the PP save process to use only the standard conversion rules.

Deprecated since version 1.10: If you need to customise pp field saving, please refer to the functions as_fields(), save_pairs_from_cube() and save_fields() for an alternative solution.

↑ top ↑

iris.fileformats.pp.save_fields(fields, target, append=False)

Save an iterable of PP fields to a PP file.

Args:

  • fields:

    An iterable of PP fields.

  • target:

    A filename or open file handle.

Kwargs:

  • append:

    Whether to start a new file afresh or add the cube(s) to the end of the file. Only applicable when target is a filename, not a file handle. Default is False.

  • callback:

    A modifier/filter function.

See also iris.io.save().

↑ top ↑

A class to hold a single STASH code.

Create instances using:
>>> model = 1
>>> section = 2
>>> item = 3
>>> my_stash = iris.fileformats.pp.STASH(model, section, item)
Access the sub-components via:
>>> my_stash.model
1
>>> my_stash.section
2
>>> my_stash.item
3
String conversion results in the MSI format:
>>> print(iris.fileformats.pp.STASH(1, 16, 203))
m01s16i203
class iris.fileformats.pp.STASH(model, section, item)

Bases: iris.fileformats.pp.STASH

Args:

  • model

    A positive integer less than 100, or None.

  • section

    A non-negative integer less than 100, or None.

  • item

    A positive integer less than 1000, or None.

count(value) → integer -- return number of occurrences of value
static from_msi(msi)

Convert a STASH code MSI string to a STASH instance.

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

Raises ValueError if the value is not present.

lbuser3()

Return the lbuser[3] value that this stash represents.

lbuser6()

Return the lbuser[6] value that this stash represents.

is_valid
item

Alias for field number 2

model

Alias for field number 0

section

Alias for field number 1

↑ top ↑

iris.fileformats.pp.EARTH_RADIUS

float(x) -> floating point number

Convert a string or number to a floating point number, if possible.