improver.utilities.temporal module

Provide support utilities for making temporal calculations.

class improver.utilities.temporal.TemporalInterpolation(interval_in_minutes=None, times=None)[source]

Bases: object

Interpolate data to intermediate times between the validity times of two cubes. This can be used to fill in missing data (e.g. for radar fields) or to ensure data is available at the required intervals when model data is not available at these times.

__init__(interval_in_minutes=None, times=None)[source]

Initialise class.

Keyword Arguments:
 
  • interval_in_minutes (int) –

    Specifies the interval in minutes at which to interpolate between the two input cubes. A number of minutes which does not divide up the interval equally will raise an exception:

    e.g. cube_t0 valid at 03Z, cube_t1 valid at 06Z,
interval_in_minutes = 60 --> interpolate to 04Z and 05Z.
  • times (list or tuple of datetime.datetime objects) – A list of datetime objects specifying the times to which to interpolate.
construct_time_list(initial_time, final_time)[source]

A function to construct a list of datetime objects formatted appropriately for use by iris’ interpolation method.

Parameters:
  • initial_time (datetime.datetime) – The start of the period over which a time list is to be constructed.
  • final_time (datetime.datetime) – The end of the period over which a time list is to be constructed.
Returns:

A list containing a tuple that specifies the coordinate and a list of points along that coordinate to which to interpolate, as required by the iris interpolation method:

e.g. [(‘time’, [<datetime object 0>,

<datetime object 1>])]
Return type:

list
Raises:
  • ValueError – If list of times provided falls outside the range specified by the initial and final times.
  • ValueError – If the interval_in_minutes does not divide the time range up equally.
process(cube_t0, cube_t1)[source]

Interpolate data to intermediate times between validity times of cube_t0 and cube_t1.

Parameters:
  • cube_t0 (iris.cube.Cube) – A diagnostic cube valid at the beginning of the period within which interpolation is to be permitted.
  • cube_t1 (iris.cube.Cube) – A diagnostic cube valid at the end of the period within which interpolation is to be permitted.
Returns:

A list of cubes interpolated to the desired times.
Return type:

interpolated_cubes (iris.cube.CubeList)
Raises:
  • TypeError – If cube_t0 and cube_t1 are not of type iris.cube.Cube.
  • CoordinateNotFoundError – The input cubes contain no time coordinate.
  • ValueError – Cubes contain multiple validity times.
  • ValueError – The input cubes are ordered such that the initial time cube has a later validity time than the final cube.
improver.utilities.temporal.cycletime_to_datetime(cycletime, cycletime_format='%Y%m%dT%H%MZ')[source]

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

Args:
cycletime (string):
A cycletime that can be converted into a datetime using the cycletime_format supplied.
Keyword Args:
cycletime_format (string):
String containg the appropriate directives to indicate how the output datetime should display.
Returns:A correctly formatted datetime object.
Return type:datetime
improver.utilities.temporal.cycletime_to_number(cycletime, cycletime_format='%Y%m%dT%H%MZ', time_unit='hours since 1970-01-01 00:00:00', calendar='gregorian')[source]

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.
Keyword Arguments:
 
  • 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.
Returns:

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

float
improver.utilities.temporal.datetime_constraint(time_in, time_max=None)[source]

Constructs an iris equivalence constraint from a python datetime object.

Parameters:
  • time_in (datetime.datetime object) – The time to be used to build an iris constraint.
  • time_max (datetime.datetime object) – Optional max time, which if provided leads to a range constraint being returned up to < time_max.
Returns:

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

time_extract (iris.Constraint)
improver.utilities.temporal.datetime_to_iris_time(dt_in, time_units='hours')[source]

Convert python datetime.datetime into hours, minutes or seconds since 1970-01-01 00Z.

Parameters:
  • dt_in (datetime.datetime object) – Time to be converted.
  • time_units (str) – Name of time unit. Currently only “hours”, “minutes” or “seconds” are supported. Alternatively, an origin time can be supported, for example “seconds since 1970-01-01 00:00:00”, however, “since 1970-01-01 00:00:00” will be ignored.
Returns:

Time since epoch in the units defined by the time_units with default floating point precision.
Return type:

result (float)
improver.utilities.temporal.extract_cube_at_time(cubes, time, time_extract)[source]

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

Parameters:
  • cubes (iris.cube.CubeList) – CubeList of a given diagnostic over several times.
  • time (datetime.datetime object) – Time at which forecast data is needed.
  • time_extract (iris.Constraint) – Iris constraint for the desired time.
Returns:

Cube of data at the desired time.
Return type:

cube (iris.cube.Cube)
Raises:

ValueError if the desired time is not available within the cubelist.
improver.utilities.temporal.extract_nearest_time_point(cube, dt, time_name='time', allowed_dt_difference=None)[source]

Find the nearest time point to the time point provided.

Parameters:
  • cube (iris.cube.Cube) – Cube or CubeList that will be extracted from using the supplied time_point
  • dt (datetime.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 (float or None) – Defines 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.
Returns:

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

cube (iris.cube.Cube)
Raises:

ValueError – The requested datetime is not available within the allowed difference.
improver.utilities.temporal.find_latest_cycletime(cubelist)[source]

Find the latest cycletime from the cubes in a cubelist and convert it into a datetime object.

Parameters:cubelist (iris.cube.CubeList) – A list of cubes each containing single time step from different forecast cycles.
Returns:A datetime object corresponding to the latest forecast reference time in the input cubelist.
Return type:cycletime (datetime object)
improver.utilities.temporal.forecast_period_coord(cube, force_lead_time_calculation=False, result_units='seconds')[source]

Return or calculate the lead time coordinate (forecast_period) within a cube, either by reading the forecast_period coordinate, or by calculating the difference between the time (points and bounds) and the forecast_reference_time. The units of the forecast_period, time and forecast_reference_time coordinates are converted, if required. The final coordinate will have units of seconds.

Parameters:

cube (Iris.cube.Cube) – Cube from which the lead times will be determined.
Keyword Arguments:
 
  • force_lead_time_calculation (bool) – Force the lead time to be calculated from the forecast_reference_time and the time coordinate, even if the forecast_period coordinate exists. Default is False.
  • result_units (str or cf_units.Unit) – Desired units for the resulting forecast period coordinate.
Returns:

Describing the points and their units for ‘forecast_period’. A DimCoord is returned if the forecast_period coord is already present in the cube as a DimCoord and this coord does not need changing, otherwise it will be an AuxCoord. Units are result_units.
Return type:

coord (iris.coords.AuxCoord or DimCoord)
improver.utilities.temporal.get_forecast_times(forecast_length, forecast_date=None, forecast_time=None)[source]

Generate a list of python datetime objects specifying the desired forecast times. This list will be created from input specifications if provided. Otherwise defaults are to start today at the most recent 6-hourly interval (00, 06, 12, 18) and to run out to T+144 hours.

Parameters:
  • forecast_length (int) – An integer giving the desired length of the forecast output in hours (e.g. 48 for a two day forecast period).
  • forecast_date (string (YYYYMMDD)) – A string of format YYYYMMDD defining the start date for which forecasts are required. If unset it defaults to today in UTC.
  • forecast_time (int) – An integer giving the hour on the forecast_date at which to start the forecast output; 24hr clock such that 17 = 17Z for example. If unset it defaults to the latest 6 hour cycle as a start time.
Returns:

A list of python datetime.datetime objects that represent the times at which diagnostic data should be extracted.
Return type:

forecast_times (list of datetime.datetime objects)
Raises:

ValueError – raised if the input date is not in the expected format.
improver.utilities.temporal.iris_time_to_datetime(time_coord)[source]

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

Parameters:time_coord (iris.coord.Coord) – Iris time coordinate element(s).
Returns:
list of datetime.datetime objects
The time element(s) recast as a python datetime object.
improver.utilities.temporal.set_utc_offset(longitudes)[source]

Simplistic timezone setting for unset sites that uses 15 degree bins centred on 0 degrees longitude. Used for on the fly site generation when no more rigorous source of timeszone information is provided.

Parameters:longitudes (List) – List of longitudes.
Returns:List of utc_offsets calculated using longitude.
Return type:utc_offsets (List)
improver.utilities.temporal.unify_forecast_reference_time(cubes, cycletime)[source]

Function to unify the forecast_reference_time across the input cubes provided. The cycletime specified is used as the forecast_reference_time. This function is intended for use in grid blending, where the models being blended may not have been run at the same cycle time, but should be given the same forecast period weightings.

Parameters:
  • cubes (iris.cube.CubeList or iris.cube.Cube) – Cubes that will have their forecast_reference_time unified. If a single cube is provided the forecast_reference_time will be updated. Any bounds on the forecast_reference_time coord will be discarded.
  • cycletime (datetime.datetime) – Datetime for the cycletime that will be used to replace the forecast_reference_time on the individual cubes.
Returns:

Cubes that have had their forecast_reference_time unified.
Return type:

result_cubes (iris.cube.CubeList)
Raises:

ValueError – if forecast_reference_time is a dimension coordinate