improver.utilities.temporal_interpolation module#
Class for Temporal Interpolation calculations.
- class DurationSubdivision(target_period, fidelity, night_mask=True, day_mask=False)[source]#
Bases:
objectSubdivide a duration diagnostic, e.g. sunshine duration, into shorter periods, optionally applying a night mask to ensure that quantities defined only in the day or night are not spread into night or day periods respectively.
This is a very simple approach. In the case of sunshine duration the duration is divided up evenly across the short periods defined by the fidelity argument. These are then optionally masked to zero for chosen periods (day or night). Values in the non-zeroed periods are then renormalised relative to the original period total, such that the total across the whole period ought to equal the original. This is not always possible as the night mask applied is simpler than e.g. the radiation scheme impact on a 3D orography. As such the renormalisation could yield durations longer than the fidelity period in each non-zeroed period as it tries to allocate e.g. 5 hours of sunlight across 4 non-zeroed hours. This is not physical, so the renormalisation is partnered with a clip that limits the duration allocated to the renormalised periods to not exceed their length. The result of this is that the original sunshine durations cannot be recovered for points that are affected. Instead the calculated night mask is limiting the accuracy to allow the subdivision to occur. This is the cost of this method.
Note that this method cannot account for any weather impacts e.g. cloud that is affecting the sunshine duration in a period. If a 6-hour period is split into three 2-hour periods the split will be even regardless of when thick cloud might occur.
- __init__(target_period, fidelity, night_mask=True, day_mask=False)[source]#
Define the length of the target periods to be constructed and the intermediate fidelity. This fidelity is the length of the shorter periods into which the data is split and from which the target periods are constructed. A shorter fidelity period allows the time dependent day or night masks to be applied more accurately.
- Parameters:
target_period (
int) – The time period described by the output cubes in seconds. The data will be reconstructed into non-overlapping periods. The target_period must be a factor of the original period.fidelity (
int) – The shortest increment in seconds into which the input periods are divided and to which the night mask is applied. The target periods are reconstructed from these shorter periods. Shorter fidelity periods better capture where the day / night discriminator falls.night_mask (
bool) – If true, points that fall at night are zeroed and duration reallocated to day time periods as much as possible.day_mask (
bool) – If true, points that fall in the day time are zeroed and duration reallocated to night time periods as much as possible.
- Raises:
ValueError – If target_period and / or fidelity are not positive integers.
ValueError – If day and night mask options are both set True.
- allocate_data(cube, period)[source]#
Allocate fractions of the original cube duration diagnostic to shorter fidelity periods with metadata that describes these shorter periods appropriately. The fidelity period cubes will be merged to form a cube with a longer time dimension. This cube will be returned and used elsewhere to construct the target period cubes.
- construct_target_periods(fidelity_period_cube)[source]#
Combine the short fidelity period cubes into cubes that describe the target period.
- Parameters:
fidelity_period_cube (
Cube) – The short fidelity period cubes from which the target periods are constructed.- Return type:
- Returns:
A cube containing the target period data with a time dimension with an entry for each target period. These periods combined span the original cube’s period.
- static cube_period(cube)[source]#
Return the time period of the cube in seconds.
- Parameters:
cube (
Cube) – The cube for which the period is to be returned.- Returns:
Period of cube time coordinate in seconds.
- Return type:
period
- process(cube)[source]#
Create target period duration diagnostics from the original duration diagnostic data.
- Parameters:
cube (
Cube) – The original duration diagnostic cube.- Return type:
- Returns:
A cube containing the target period data with a time dimension with an entry for each period. These periods combined span the original cube’s period.
- Raises:
ValueError – The target period is not a factor of the input period.
ValueError – The fidelity period is not less than or equal to the target period.
- static renormalisation_factor(cube, fidelity_period_cube)[source]#
Sum up the total of the durations distributed amongst the fidelity period cubes following the application of any masking. These are then used with the durations in the unsubdivided original data to calculate a factor to restore the correct totals; note that where clipping plays a role the original totals may not be restored.
- Parameters:
- Returns:
An array of factors that can be used to multiply up the fidelity period durations such that when the are summed up they are equal to the original durations.
- Return type:
factor
- 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._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.