improver.calibration.dz_rescaling module

Estimate and apply a rescaling of the input forecast based on the difference in altitude between the grid point and the site.

class ApplyDzRescaling(site_id_coord='wmo_id', frt_hour_leniency=1)

Bases: PostProcessingPlugin

Apply rescaling of the forecast using the difference in altitude between the grid point and the site.

__init__(site_id_coord='wmo_id', frt_hour_leniency=1)

Initialise class.

Parameters:

• site_id_coord (str) – The name of the site ID coordinate. This defaults to ‘wmo_id’.

• frt_hour_leniency – The forecast reference time hour for the forecast and the scaled_dz are expected to match. If no match is found and a leniency greater than zero is specified, the forecast reference time hour will be compared with e.g. a +/-1 hour leniency.

_abc_impl = <_abc_data object>

_check_mismatched_sites(forecast, scaled_dz)

Check that the sites match for the forecast and the scaled_dz inputs.

Parameters:

• forecast (Cube) – Forecast to be adjusted using dz rescaling.

• scaled_dz (Cube) – A scaled version of the difference in altitude between the grid point and the site.

Raises:

ValueError – Sites do not match between the forecast and the scaled dz.

Return type:

None

static _create_forecast_period_constraint(forecast, scaled_dz)

Create a forecast period constraint to identify the most appropriate forecast period from the scaled_dz to extract. The most appropriate scaled dz is selected by choosing the nearest forecast period that is greater than or equal to the forecast period of the forecast. If no forecast periods in the scaled dz cube are greater than the forecast period of the forecast, the longest available forecast period is used.

Parameters:

• forecast (Cube) – Forecast to be adjusted using dz rescaling.

• scaled_dz (Cube) – A scaled version of the difference in altitude between the grid point and the site.

Return type:

Constraint

Returns:

Forecast period constraint.

Raises:

ValueError – No scaled dz could be found for the forecast period provided.

static _create_forecast_reference_time_constraint(forecast, leniency)

Create a forecast reference time constraint based on the hour within the forecast reference time.

Parameters:

• forecast (Cube) – Forecast to be adjusted using dz rescaling.

• leniency (int) – The leniency in hours to adjust the forecast reference time hour when looking for a match.

Return type:

Constraint

Returns:

Forecast reference time hour constraint.

process(forecast, scaled_dz)

Apply rescaling of the forecast to account for differences in the altitude between the grid point and the site, as assessed using a training dataset. The most appropriate scaled dz is selected by choosing the nearest forecast period that is greater than or equal to the forecast period of the forecast.

Parameters:

• forecast (Cube) – Forecast to be adjusted using dz rescaling.

• scaled_dz (Cube) – A scaled version of the difference in altitude between the grid point and the site.

Return type:

Cube

Returns:

Altitude-corrected forecast.

Raises:

ValueError – No scaled dz could be found for the forecast period and forecast reference time hour provided.

class EstimateDzRescaling(forecast_period, dz_lower_bound=None, dz_upper_bound=None, land_constraint=False, similar_altitude=False, site_id_coord='wmo_id')

Bases: PostProcessingPlugin

Estimate a rescaling of the input forecasts based on the difference in altitude between the grid point and the site.

__init__(forecast_period, dz_lower_bound=None, dz_upper_bound=None, land_constraint=False, similar_altitude=False, site_id_coord='wmo_id')

Initialise class.

Parameters:

• forecast_period (float) – The forecast period in hours that is considered representative of the input forecasts. This is required as the input forecasts could contain multiple forecast periods.

• dz_lower_bound (Union[str, float, None]) – The lowest acceptable value for the difference in altitude between the grid point and the site. Sites with a lower (or more negative) difference in altitude will be excluded. Defaults to None.

• dz_upper_bound (Union[str, float, None]) – The highest acceptable value for the difference in altitude between the grid point and the site. Sites with a larger positive difference in altitude will be excluded. Defaults to None.

• land_constraint (bool) – If True, this will return a cube containing the nearest grid point neighbours to spot sites that are also land points. May be used with the similar_altitude option.

• similar_altitude (bool) – If True, this will return a cube containing the nearest grid point neighbour to each spot site that is found, within a given search radius, to minimise the height difference between the two. May be used with the land_constraint option.

• site_id_coord (str) – The name of the site ID coordinate. This defaults to ‘wmo_id’.

_abc_impl = <_abc_data object>

_compute_scaled_dz(scale_factor, dz)

Compute the scaled difference in altitude.

Parameters:

• scale_factor (float) – A scale factor deduced from a polynomial fit.

• dz (ndarray) – The difference in altitude between the grid point and the site.

Return type:

ndarray

Returns:

Scaled difference in altitude at each site.

_compute_scaled_dz_cube(forecast, dz, scale_factor)

Compute the scaled difference in altitude and ensure that the output cube has the correct metadata.

Parameters:

• forecast (Cube) – Forecast cube.

• dz (Cube) – The difference in altitude between the grid point and the site.

• scale_factor (float) – A scale factor deduced from a polynomial fit.

Return type:

Cube

Returns:

Scaled difference in altitude cube with appropriate metadata.

_create_hour_coord(source_cube, target_cube)

Create a coordinate exclusively containing the hour of the forecast reference time. This is required as the date of the forecast reference time is not relevant when using a training dataset with the aim that the resulting scaling factor is applicable to future forecasts with the same hour for the forecast reference time. The auxiliary coordinate will be added to the target_cube.

Parameters:

• source_cube (Cube) – Cube containing the forecast reference time from which the hour will be extracted.

• target_cube (Cube) – Cube to which an auxiliary coordinate will be added.

_fit_polynomial(forecasts, truths, dz)

Create a polynomial fit between the log of the ratio of forecasts and truths, and the difference in altitude between the grid point and the site.

Parameters:

• forecasts (Cube) – Forecast cube.

• truths (Cube) – Truth cube.

• dz (Cube) – Difference in altitude between the grid point and the site location.

Return type:

float

Returns:

A scale factor deduced from a polynomial fit. This is a single value deduced from the fit between the forecasts and the truths.

process(forecasts, truths, neighbour_cube)

Fit a polynomial using the forecasts and truths to compute a scaled version of the difference of altitude between the grid point and the site location. There is expected to be overlap between the sites provided by the forecasts, truths and neighbour_cube. The polynomial will be fitted using the forecasts and truths and the resulting scale factor will be applied to all sites within the neighbour cube. The output scaled dz will contain sites matching the neighbour cube.

A mathematical summary of the steps within this plugin are:

1. Estimate a scale factor for the relationship between the difference in altitude between the grid point and the site, and the natural log of the forecast divided by the truth, where s is the scale factor in the equations below.

\[dz = \ln(forecast / truth) \times s\]

2. Rearranging this equation gives:

\[truth = forecast / \exp(s \times dz)\]

or alternatively:

\[truth = forecast \times \exp(-s \times dz)\]

This plugin is aiming to estimate the \(\exp(-s \times dz)\) component, which can later be used for multiplying by a forecast to estimate the truth.

Parameters:

• forecasts (Cube) – Forecast cube.

• truths (Cube) – Truth cube.

• neighbour_cube (Cube) – A neighbour cube containing the difference in altitude between the grid point and the site location. Note that the output will have the same sites as found within the neighbour cube.

Return type:

Cube

Returns:

A scaled difference of altitude between the grid point and the site location.