improver.utilities.temporal module¶
General utilities for parsing and extracting cubes at times
-
improver.utilities.temporal.cycletime_to_datetime(cycletime, cycletime_format='%Y%m%dT%H%MZ')[source]¶ Convert a string representating the cycletime of the format YYYYMMDDTHHMMZ into a datetime object.
-
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.
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
-
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) – The time to be used to build an iris constraint.
time_max (datetime.datetime) – 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
-
improver.utilities.temporal.datetime_to_cycletime(adatetime, cycletime_format='%Y%m%dT%H%MZ')[source]¶ Convert a datetime object into a string representing the cycletime of the format YYYYMMDDTHHMMZ.
- Parameters
adatetime (datetime.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.
- Returns
A correctly formatted string.
- Return type
-
improver.utilities.temporal.datetime_to_iris_time(dt_in)[source]¶ Convert python datetime.datetime into seconds since 1970-01-01 00Z.
- Parameters
dt_in (datetime.datetime) – Time to be converted into seconds since 1970-01-01 00Z.
- Returns
Time since epoch in the seconds as desired dtype.
- Return type
-
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
- 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=0)[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 (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.
- Returns
Cube following extraction to return the cube that is nearest to the time point supplied.
- Return type
- Raises
ValueError – The requested datetime is not available within the allowed difference.
-
improver.utilities.temporal.iris_time_to_datetime(time_coord, point_or_bound='point')[source]¶ Convert iris time to python datetime object. Working in UTC.
- Parameters
time_coord (iris.coords.Coord) – Iris time coordinate element(s).
- Returns
The time element(s) recast as a python datetime object.
- Return type
list of datetime.datetime