improver.utilities.cube_metadata module

Module containing utilities for modifying cube metadata.

improver.utilities.cube_metadata.add_coord(cube, coord_name, changes, warnings_on=False)[source]

Add coord to the cube.

Parameters:
  • cube (iris.cube.Cube) – Cube containing combined data.
  • coord_name (string) – Name of the coordinate being added.
  • changes (dict) – Details on coordinate to be added to the cube.
Keyword Arguments:
 

warnings_on (bool) – If True output warnings for mismatching metadata.
Returns:

Cube with added coordinate.
Return type:

result (iris.cube.Cube)
Raises:
  • ValueError – Trying to add new coord but no points defined.
  • ValueError – Can not add a coordinate of length > 1
  • UserWarning – adding new coordinate.
improver.utilities.cube_metadata.add_history_attribute(cube, value, append=False)[source]

Add a history attribute to a cube. This uses the current datetime to generate the timestamp for the history attribute. The new history attribute will overwrite any existing history attribute unless the “append” option is set to True. The history attribute is of the form “Timestamp: Description”.

Parameters:
  • cube (iris.cube.Cube) – The cube to which the history attribute will be added.
  • value (str) – String defining details to be included in the history attribute.
Kwargs:
append (bool):
If True, add to the existing history rather than replacing the existing attribute. Default is False.
improver.utilities.cube_metadata.amend_metadata(cube, name=None, data_type=None, coordinates=None, attributes=None, cell_methods=None, units=None, warnings_on=False)[source]

Amend the metadata in the incoming cube. Please note that if keyword arguments to this function are supplied by unpacking a dictionary, then the keys of the dictionary need to correspond to the keyword arguments.

Parameters:

cube (iris.cube.Cube) – Input cube.
Keyword Arguments:
 
  • name (str) – New name for the diagnostic.
  • data_type (numpy.dtype) – Data type that the cube data will be converted to.
  • coordinates (dict or None) – Revised coordinates for incoming cube.
  • attributes (dict or None) – Revised attributes for incoming cube.
  • cell_methods (dict or None) – Cell methods for modification within the incoming cube.
  • units (str, cf_units.Unit or None) – Units for use in converting the units of the input cube.
  • warnings_on (bool) – If True output warnings for mismatching metadata.
Returns:

Cube with corrected metadata.
Return type:

result (iris.cube.Cube)

Example inputs:

coordinates: The name of the coordinate is required, in addition
    to details regarding the coordinate required by the coordinate.
    The type of the coordinate is specified using a "metatype" key.
    Available keys are:
        * metatype: Type of coordinate e.g. DimCoord or AuxCoord.
        * points: Point values for coordinate.
        * bounds: Bounds associated with each coordinate point.
        * units: Units of coordinate
    For example:
    "threshold": {
        "metatype": "DimCoord",
        "points": [1.0],
        "bounds": [[0.1, 1.0]],
        "units": "mm hr-1"
    }

attributes: Attributes are specified using the name of the attribute
    to be modified as the key. For all keys, apart from "history",
    the value of the items in the dictionary can either be the value
    that will be added e.g. "source": "Met Office Radarnet" will add
    a "source" attribute with the value of "Met Office Radarnet", or
    "source": "delete" will delete the source attribute.
    For non-history attributes, the available options are e.g.:
        * "source": "Met Office Radarnet"
        * "source": "delete"
    For example:
    {
        "experiment_number": "delete",
        "field_code": "delete",
        "source": "Met Office Radarnet",
    }
    As the history attribute requires a timestamp to be created that
    represents now, this needs to be automatically created at runtime.
    If a history attribute is added, a name is also added.
    For the history attribute, the available options are e.g.
        * "history": ["add", "Nowcast"]
        * "history": "delete"

cell_methods: Cell methods are specified using a all arguments taken
    by iris.coords.CellMethod. Additionally, an action key is required
    to specify whether the specified cell method will be added or
    deleted.
    For example:
        {
            "action": "delete",
            "method": "point",
            "coords": "time"
        }
improver.utilities.cube_metadata.delete_attributes(cube, patterns)[source]

Delete attributes that are complete or partial matches to elements in the list patterns.

Parameters:
  • cube (iris.cube.Cube) – The cube from which attributes are to be deleted.
  • patterns (list or tuple) – A list of strings that match or partially match the keys of attributes to be deleted from the cube.
improver.utilities.cube_metadata.in_vicinity_name_format(cube_name)[source]

Generate the correct name format for an ‘in_vicinity’ probability cube, taking into account the _’above/below_threshold’ suffix required by convention.

Parameters:cube_name (str) – The ‘in_vicinity’ probability cube name to be formatted.
Returns:Correctly formatted name following the accepted convention e.g. ‘probability_of_X_in_vicinity_above_threshold’.
Return type:new_cube_name (str)
Raises:ValueError – If the input cube name already contains ‘in_vicinity’.
improver.utilities.cube_metadata.resolve_metadata_diff(cube1, cube2, warnings_on=False)[source]

Resolve any differences in metadata between cubes.

Parameters:
  • cube1 (iris.cube.Cube) – Cube containing data to be combined.
  • cube2 (iris.cube.Cube) – Cube containing data to be combined.
Keyword Arguments:
 

warnings_on (bool) – If True output warnings for mismatching metadata.
Returns:

tuple containing
result1 (iris.cube.Cube):

Cube with corrected Metadata.

result2 (iris.cube.Cube):

Cube with corrected Metadata.
Return type:

(tuple)
improver.utilities.cube_metadata.update_attribute(cube, attribute_name, changes, warnings_on=False)[source]

Update the attribute in the cube.

Parameters:
  • cube (iris.cube.Cube) – Cube containing combined data.
  • attribute_name (string) – Name of the attribute being updated.
  • changes (object) – attribute value or If changes = ‘delete’ the coordinate is deleted.
Keyword Arguments:
 

warnings_on (bool) – If True output warnings for mismatching metadata.
Returns:

Cube with updated coordinate.
Return type:

result (iris.cube.Cube)
Raises:
improver.utilities.cube_metadata.update_cell_methods(cube, cell_method_definition)[source]

Update cell methods. An “action” keyword is expected within the cell method definition to specify whether the cell method is to be added or deleted.

The cube will be modified in-place.

Parameters:
  • cube (iris.cube.Cube) – Cube containing cell methods that will be updated.
  • cell_method_definition (dict) – A dictionary which must contain an “action” keyword with a value of either “add” or “delete”, which determines whether to add or delete the cell method. The rest of the keys are passed to the iris.coords.CellMethod function. Of these keys, “method”, is compulsory, and “comments”, “coords” and “invevals” are optional. If any addtional keys are provided in the dictionary they are ignored.
Raises:
  • ValueError – If no action is specified for the cell method, then raise an error.
  • ValueError – If no method is specified for the cell method, then raise an error.
improver.utilities.cube_metadata.update_coord(cube, coord_name, changes, warnings_on=False)[source]

Amend the metadata in the combined cube.

Parameters:
  • cube (iris.cube.Cube) – Cube containing combined data.
  • coord_name (string) – Name of the coordinate being updated.
  • changes (string or dict) – Details on coordinate to be updated. If changes = ‘delete’ the coordinate is deleted.
Keyword Arguments:
 

warnings_on (bool) – If True output warnings for mismatching metadata.
Returns:

Cube with updated coordinate.
Return type:

result (iris.cube.Cube)
Raises:
  • ValueError – Can only remove a coordinate of length 1
  • ValueError – Mismatch in points in existing coord and updated metadata.
  • ValueError – Mismatch in bounds in existing coord and updated metadata.
  • ValueError – The shape of the bounds array should be points.shape + (n_bounds,)
  • UserWarning – Deleted coordinate.
  • UserWarning – Updated coordinate
improver.utilities.cube_metadata.update_stage_v110_metadata(cube)[source]

Translates meta-data relating to the grid_id attribute from StaGE version 1.1.0 to later StaGE versions. Cubes that have no “grid_id” attribute are not recognised as v1.1.0 and are ignored.

Parameters:cube (iris.cube.Cube) – Cube to modify meta-data in (modified in place)
Returns:True if meta-data have been changed by this function.
Return type:boolean (bool)