improver.blending.utilities module

Utilities to support weighted blending

_get_cycletime_point(cube, cycletime)[source]

For cycle and model blending, establish the current cycletime to set on the cube after blending.

Parameters:

  • blended_cube –

  • cycletime (str) – Current cycletime in YYYYMMDDTHHmmZ format

Return type:

int64

Returns:

Cycle time point in units matching the input cube forecast reference time coordinate

_set_blended_time_coords(blended_cube, cycletime)[source]

For cycle and model blending:

  • Add a “blend_time” coordinate equal to the current cycletime

  • Update the forecast reference time to reflect the current cycle time (behaviour is DEPRECATED)

  • If a forecast period coordinate is present this will be updated relative to the current cycle time (behaviour is DEPRECATED)

  • Remove any bounds from the forecast reference time (behaviour is DEPRECATED)

  • Mark any forecast reference time and forecast period coordinates as DEPRECATED

Modifies cube in place.

Parameters:

  • blended_cube (Cube) –

  • cycletime (Optional[str]) – Current cycletime in YYYYMMDDTHHmmZ format

Return type:

None

find_blend_dim_coord(cube, blend_coord)[source]

Find the name of the dimension coordinate across which to perform the blend, since the input “blend_coord” may be an auxiliary coordinate.

Parameters:

  • cube (Cube) – Cube to be blended

  • blend_coord (str) – Name of coordinate to blend over

Return type:

str

Returns:

Name of dimension coordinate associated with blend dimension

Raises:

ValueError – If blend coordinate is associated with more or less than one dimension

get_coords_to_remove(cube, blend_coord)[source]

Generate a list of coordinate names associated with the blend dimension. Unless these are time-related coordinates, they should be removed after blending. An empty list is returned if there are no coordinates to remove.

Parameters:

  • cube (Cube) – Cube to be blended

  • blend_coord (str) – Name of coordinate over which the blend will be performed

Return type:

List[str]

Returns:

List of names of coordinates to remove

record_run_coord_to_attr(target, source, record_run_attr, discard_weights=False)[source]

Extracts record_run entries from the RECORD_COORD auxiliary coordinate on the source cube. These are joined together and added as the record_run_attr attribute to the target cube.

Parameters:

  • target (Cube) – Cube to which the record_run_attr should be added. This is the product of blending the data in the source cube.

  • source (Union[Cube, CubeList, List[Cube]]) – The cubes merged together in preparation for blending. This cube contains the RECORD_COORD that includes the record_run entries to use in constructing the attribute.

  • record_run_attr (str) – The name of the attribute used to store model and cycle sources.

  • discard_weights (bool) – If cubes have been combined rather than blended the weights may well not provide much information, i.e. in weather symbols. They may also not be normalised and could give a total contributing weight much larger than 1. In these cases, setting discard_weights to true will produce an attribute that records only the models and cycles without the weights.

Return type:

None

store_record_run_as_coord(cubelist, record_run_attr, model_id_attr)[source]

Stores model identifiers and forecast_reference_times on the input cubes as auxiliary coordinates. These are used to construct record_run attributes that can be applied to a cube produced by merging or combining these cubes. By storing this information as a coordinate it will persist in merged cubes in which forecast_reference_times are otherwise updated. It also allows the data to be discarded when cubes for blending are filtered to remove zero-weight contributors, ensuring the resulting attribute is consistent with what has actually contributed to a blended forecast.

From the list of cubes, pre-existing record_run attributes, model IDs and forecast reference times are extracted as required. These are combined and stored as a RECORD_COORD auxiliary coordinate. The constructed attribute has the form:

model : cycle : weight

e.g.:

uk_ens : 20201105T1200Z : 1.0

If a new record is being constructed the weight is always set to 1. This will be updated using the weights applied in blending the cubes. When combining (rather than blending) cubes (e.g. weather symbols) it is expected that each input will already possess a record_run attribute that contains the real weights used.

Existing records may contain multiple of these attribute components joined with newline characters.

There are two ways this method may work:

  • All of the input cubes have an existing record_run attribute. The model_id_attr argument is not required as the existing record_run attribute is used to create the RECORD_COORD.

  • Some or none of the input cubes have an existing record_run attribute. The model_id_attr argument must be provided so that those cubes without an existing record_run attribute can be interrogated for their model identifier. This is used to create a model:cycle:weight attribute that is stored in the RECORD_COORD.

Parameters:

  • cubelist (CubeList) – Cubes from which to obtain model and cycle information, or an existing record_run attribute.

  • record_run_attr (str) – The name of the record_run attribute that may exist on the input cubes.

  • model_id_attr (Optional[str]) – The name of the model_id attribute that may exist on the input cubes.

Raises:

  • ValueError – If model_id_attr is not set and is required to construct a new record_run_attr.

  • Exception – The model_id_attr name provided is not present on one or more of the input cubes.

Return type:

None

update_blended_metadata(cube, blend_coord, coords_to_remove=None, cycletime=None, attributes_dict=None, model_id_attr=None)[source]

Update metadata as required after blending - For cycle and model blending, set a single forecast reference time and period using current cycletime - For model blending, add attribute detailing the contributing models - Remove scalar coordinates that were previously associated with the blend dimension - Update attributes as specified via process arguments - Set any missing mandatory arguments to their default values

Modifies cube in place.

Parameters:

  • cube (Cube) – Blended cube

  • blend_coord (str) – Name of coordinate over which blending has been performed

  • coords_to_remove (Optional[List[str]]) – Name of scalar coordinates to be removed from the blended cube

  • cycletime (Optional[str]) – Current cycletime in YYYYMMDDTHHmmZ format

  • model_id_attr (Optional[str]) – Name of attribute for use in model blending, to record the names of contributing models on the blended output

  • attributes_dict (Optional[Dict[str, str]]) – Optional user-defined attributes to add to the cube

Return type:

None

update_record_run_weights(cube, weights, blend_coord)[source]

Update each weight component of record_run to reflect the blending weights being applied.

When cycle blending, the weights recorded in the record_run entries will all initially be set to 1 following their creation. These are modified to reflect the weight each cycle contributes to the blend.

When model blending the record_run entries will likely be multiple, reflecting the several cycles that have already been blended. These are split up so that the weights can be modified to reflect their final contribution to the model blend.

As an example, consider 4 deterministic cycles that have been cycle blended using equal weights. Each cycle will have a weight of 0.25. These might then be model blended with another model, each contributing 0.5 of the total. Each of the 4 deterministic cycles will end up with a modified weight of 0.125 contributing to the final blend.

Parameters:

  • cube (Cube) – The cubes merged together in preparation for blending. These contain the RECORD_COORD in which the weights need to be updated.

  • weights (Cube) – The weights cube that is being applied in the blending. Note that these should be simple weights, rather than spatial weights. The attribute cannot hope to capture the spatially varying weights, so the high-level contribution is recorded ignoring local variation.

  • blend_coord (str) – The coordinate over which blending is being performed.

Return type:

Cube

Returns:

A copy of the input cube with the updated weights.