improver.utilities.temporal module

General utilities for parsing and extracting cubes at times

cycletime_to_datetime(cycletime, cycletime_format='%Y%m%dT%H%MZ')

Convert a string representating the cycletime of the format YYYYMMDDTHHMMZ into a datetime object.

Parameters:

• cycletime (str) – A cycletime that can be converted into a datetime using the cycletime_format supplied.

• cycletime_format (str) – String containing the desired format for the cycletime.

Return type:

datetime

Returns:

A correctly formatted datetime object.

cycletime_to_number(cycletime, cycletime_format='%Y%m%dT%H%MZ', time_unit='hours since 1970-01-01 00:00:00', calendar='gregorian')

Convert a cycletime of the format YYYYMMDDTHHMMZ into a numeric time value.

Parameters:

• cycletime (str) – A cycletime that can be converted into a datetime using the cycletime_format supplied.

• cycletime_format (str) – String containg the appropriate directives to indicate how the output datetime should display.

• time_unit (str) – String representation of the cycletime units.

• calendar (str) – String describing the calendar used for defining the cycletime. The choice of calendar must be supported by cf_units.CALENDARS.

Return type:

float

Returns:

A numeric value to represent the datetime using assumed choices for the unit of time and the calendar.

datetime_constraint(time_in, time_max=None)

Constructs an iris equivalence constraint from a python datetime object.

Parameters:

• time_in (datetime) – The time to be used to build an iris constraint.

• time_max (Optional[datetime]) – Optional max time, which if provided leads to a range constraint being returned up to < time_max.

Return type:

Constraint

Returns:

An iris constraint to be used in extracting data at the given time from a cube.

datetime_to_cycletime(adatetime, cycletime_format='%Y%m%dT%H%MZ')

Convert a datetime object into a string representing the cycletime of the format YYYYMMDDTHHMMZ.

Parameters:

• adatetime (datetime) – A datetime that can be converted into a cycletime using the cycletime_format supplied.

• cycletime_format (str) – String containing the desired format for the cycletime.

Return type:

str

Returns:

A correctly formatted string.

datetime_to_iris_time(dt_in)

Convert python datetime.datetime or cftime.DatetimeGregorian object into seconds since 1970-01-01 00Z.

Parameters:

dt_in (Union[datetime, DatetimeGregorian]) – Time to be converted into seconds since 1970-01-01 00Z.

Return type:

int64

Returns:

Time since epoch in the seconds.

extract_cube_at_time(cubes, time, time_extract)

Extract a single cube at a given time from a cubelist.

Parameters:

• cubes (CubeList) – CubeList of a given diagnostic over several times.

• time (datetime) – Time at which forecast data is needed.

• time_extract (Constraint) – Iris constraint for the desired time.

Return type:

Cube

Returns:

Cube of data at the desired time.

Raises:

ValueError if the desired time is not available within the cubelist. –

extract_nearest_time_point(cube, dt, time_name='time', allowed_dt_difference=0)

Find the nearest time point to the time point provided.

Parameters:

• cube (Cube) – Cube or CubeList that will be extracted from using the supplied time_point

• dt (datetime) – Datetime representation of a time that will be used within the extraction from the cube supplied.

• time_name (str) – Name of the “time” coordinate that will be extracted. This must be “time” or “forecast_reference_time”.

• allowed_dt_difference (int) – An int in seconds to define a limit to the maximum difference between the datetime provided and the time points available within the cube. If this limit is exceeded, then an error is raised. This must be defined in seconds. Default is 0.

Return type:

Cube

Returns:

Cube following extraction to return the cube that is nearest to the time point supplied.

Raises:

ValueError – The requested datetime is not available within the allowed difference.

integrate_time(cube, new_name=None)

Multiply a frequency or rate cube by the time period given by the time bounds over which it is defined to return a count or accumulation. The frequency or rate must be defined with time bounds, e.g. an average frequency across the period. This function will handle a cube with a non-scalar time coordinate, multiplying each time in the coordinate by the related bounds.

The returned cube has units equivalent to the input cube multiplied by seconds.

Any time related cell methods are removed from the output cube and a new “sum” over time cell method is added.

Parameters:

• Cube – A cube of average frequency or rate within a defined period.

• new_name (str) – A new name for the resulting diagnostic.

Return type:

Cube

Returns:

The cube with the data multiplied by the period in seconds defined by the bounds on the time coordinate.

Raises:

ValueError – If the input cube time coordinate does not have time bounds.

iris_time_to_datetime(time_coord, point_or_bound='point')

Convert iris time to python datetime object. Working in UTC.

Parameters:

time_coord (Coord) – Iris time coordinate element(s).

Return type:

List[datetime]

Returns:

The time element(s) recast as a python datetime object.

relabel_to_period(cube, period=None)

Add or replace bounds for the forecast period and time coordinates on a cube.

Parameters:

• cube (Cube) – The cube for a diagnostic that will be modified to represent the required period.

• period (Optional[int]) – The period in hours.

Returns:

Cube with metadata updated to represent the specified period.