improver.utilities.temporal_interpolation module
Class for Temporal Interpolation calculations.
- class TemporalInterpolation(interval_in_minutes=None, times=None, interpolation_method='linear', accumulation=False, max=False, min=False)[source]
Bases:
BasePluginInterpolate 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.
The plugin will return the interpolated times and the later of the two input times. This allows us to modify the input diagnostics if they represent accumulations.
The IMPROVER convention is that period diagnostics have their time coordinate point at the end of the period. The later of the two inputs therefore covers the period that has been broken down into shorter periods by the interpolation and, if working with accumulations, must itself be modified. The result of this approach is that in a long run of lead-times, e.g. T+0 to T+120 all the lead-times will be available except T+0.
If working with period maximums and minimums we cannot return values in the new periods that do not adhere to the inputs. For example, we might have a 3-hour maximum of 5 ms-1 between 03-06Z. The period before it might have a maximum of 11 ms-1. Upon splitting the 3-hour period into 1-hour periods the gradient might give us the following results:
Inputs: 00-03Z: 11 ms-1, 03-06Z: 5 ms-1 Outputs: 03-04Z: 9 ms-1, 04-05Z: 7 ms-1, 05-06Z: 5ms-1
However these outputs are not in agreement with the original 3-hour period maximum of 5 ms-1 over the period 03-06Z. We enforce the maximum from the original period which results in:
Inputs: 00-03Z: 10 ms-1, 03-06Z: 5 ms-1 Outputs: 03-04Z: 5 ms-1, 04-05Z: 5 ms-1, 05-06Z: 5ms-1
If instead the preceding period maximum was 2 ms-1 we would use the trend to produce lower maximums in the interpolated 1-hour periods, becoming:
Inputs: 00-03Z: 2 ms-1, 03-06Z: 5 ms-1 Outputs: 03-04Z: 3 ms-1, 04-05Z: 4 ms-1, 05-06Z: 5ms-1
This interpretation of the gradient information is retained in the output as it is consistent with the original period maximum of 5 ms-1 between 03-06Z. As such we can impart increasing trends into maximums over periods but not decreasing trends. The counter argument can be made when interpolating minimums in periods, allowing us only to introduce decreasing trends for these.
We could use the cell methods to determine whether we are working with accumulations, maximums, or minimums. This should be denoted as a cell method associated with the time coordinate, e.g. for an accumulation it would be time: sum, whilst a maximum would have time: max. However we cannot guarantee these cell methods are present. As such the interpolation of periods here relies on the user supplying a suitable keyword argument that denotes the type of period being processed.
- __init__(interval_in_minutes=None, times=None, interpolation_method='linear', accumulation=False, max=False, min=False)[source]
Initialise class.
- Parameters:
interval_in_minutes (
Optional[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 (
Optional[List[datetime]]) – A list of datetime objects specifying the times to which to interpolate.interpolation_method (
str) – Method of interpolation to use. Default is linear. Only methods in known_interpolation_methods can be used.accumulation (
bool) – Set True if the diagnostic being temporally interpolated is a period accumulation. The output will be renormalised to ensure that the total across the period constructed from the shorter intervals matches the total across the period from the coarser intervals.max (
bool) – Set True if the diagnostic being temporally interpolated is a period maximum. Trends between adjacent input periods will be used to provide variation across the interpolated periods where these are consistent with the inputs.min (
bool) – Set True if the diagnostic being temporally interpolated is a period minimum. Trends between adjacent input periods will be used to provide variation across the interpolated periods where these are consistent with the inputs.
- Raises:
ValueError – If neither interval_in_minutes nor times are set.
ValueError – If both interval_in_minutes and times are both set.
ValueError – If interpolation method not in known list.
ValueError – If multiple period diagnostic kwargs are set True.
ValueError – A period diagnostic is being interpolated with a method not found in the period_interpolation_methods list.
- _abc_impl = <_abc_data object>
- static _calculate_accumulation(cube_t0, period_reference, interpolated_cube)[source]
If the input is an accumulation we use the trapezium rule to calculate a new accumulation for each output period from the rates we converted the accumulations to prior to interpolating. We then renormalise to ensure the total accumulation across the period is unchanged by expressing it as a series of shorter periods.
The interpolated cube is modified in place.
- Parameters:
cube_t0 (
Cube) – The input cube corresponding to the earlier time.period_reference (
Cube) – The input cube corresponding to the later time, with the values prior to conversion to rates.interpolated_cube (
Cube) – The cube containing the interpolated times, which includes the data corresponding to the time of the later of the two input cubes.
- static add_bounds(cube_t0, interpolated_cube)[source]
Calcualte bounds using the interpolated times and the time taken from cube_t0. This function is used rather than iris’s guess bounds method as we want to use the earlier time cube to inform the lowest bound. The interpolated_cube crd is modified in place.
- Parameters:
- Raises:
CoordinateNotFoundError – if time or forecast_period coordinates are not present on the input cubes.
- static calc_lats_lons(cube)[source]
Calculate the lats and lons of each point from a non-latlon cube, or output a 2d array of lats and lons, if the input cube has latitude and longitude coordinates.
- 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:
- Return type:
- 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>])]
- 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.
- static daynight_interpolate(interpolated_cube)[source]
Set linearly interpolated data to zero for parameters (e.g. solar radiation parameters) which are zero if the sun is below the horizon.
- static enforce_time_coords_dtype(cube)[source]
Enforce the data type of the time, forecast_reference_time and forecast_period within the cube, so that time coordinates do not become mis-represented. The units of the time and forecast_reference_time are enforced to be “seconds since 1970-01-01 00:00:00” with a datatype of int64. The units of forecast_period are enforced to be seconds with a datatype of int32. This functions modifies the cube in-place.
- Parameters:
cube (
Cube) – The cube that will have the datatype and units for the time, forecast_reference_time and forecast_period coordinates enforced.- Return type:
- Returns:
Cube where the datatype and units for the time, forecast_reference_time and forecast_period coordinates have been enforced.
- process(cube_t0, cube_t1)[source]
Interpolate data to intermediate times between validity times of cube_t0 and cube_t1.
- Parameters:
- Return type:
- Returns:
A list of cubes interpolated to the desired times.
- Raises:
TypeError – If cube_t0 and cube_t1 are not of type iris.cube.Cube.
ValueError – A mix of instantaneous and period diagnostics have been used as inputs.
ValueError – A period type has been declared but inputs are not period diagnostics.
ValueError – Period diagnostics with overlapping periods.
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.
- solar_interpolate(diag_cube, interpolated_cube)[source]
Temporal Interpolation code using solar elevation for parameters (e.g. solar radiation parameters like Downward Shortwave (SW) radiation or UV index) which are zero if the sun is below the horizon and scaled by the sine of the solar elevation angle if the sun is above the horizon.
- Parameters:
- Return type:
- Returns:
A list of cubes interpolated to the desired times.