sup3r.bias.bias_transforms.local_qdm_bc

Contents

sup3r.bias.bias_transforms.local_qdm_bc#

local_qdm_bc(data: DataArray, lat_lon: ndarray, base_dset: str, feature_name: str, bias_fp: str, date_range_kwargs: dict, lr_padded_slice=None, threshold=0.1, relative=True, no_trend=False, delta_denom_min=None, delta_denom_zero=None, delta_range=None, out_range=None, max_workers=1)[source]#

Bias correction using QDM

Apply QDM to correct bias on the given data. It assumes that the required statistical distributions were previously estimated and saved in bias_fp.

Assume CDF for the nearest day of year (doy) is representative.

Parameters:

  • data (xr.DataArray) – Sup3r input data to be bias corrected, assumed to be 3D with shape (spatial, spatial, temporal) for a single feature.

  • lat_lon (np.ndarray) – Array of latitudes and longitudes for the domain to bias correct (n_lats, n_lons, 2)

  • base_dset – Name of feature that is used as (historical) reference. Dataset with names “base_{base_dset}_params” will be retrieved.

  • feature_name (str) – Name of feature that is being corrected. Datasets with names “bias_{feature_name}_params” and “bias_fut_{feature_name}_params” will be retrieved.

  • date_range_kwargs (dict) – Keyword args for pd.date_range to produce a DatetimeIndex object associated with the input data temporal axis (assumed 3rd axis e.g. axis=2). Note that if this method is called as part of a sup3r resolution forward pass, the date_range_kwargs will be included automatically for the current chunk.

  • bias_fp (str) – Filepath to statistical distributions file from the bias calc module. Must have datasets “bias_{feature_name}_params”, “bias_fut_{feature_name}_params”, and “base_{base_dset}_params” that are the parameters to define the statistical distributions to be used to correct the given data.

  • lr_padded_slice (tuple | None) – Tuple of length four that slices (spatial_1, spatial_2, temporal, features) where each tuple entry is a slice object for that axes. Note that if this method is called as part of a sup3r forward pass, the lr_padded_slice will be included automatically in the kwargs for the active chunk. If this is None, no slicing will be done and the full bias correction source shape will be used.

  • no_trend (bool, default=False) – An option to ignore the trend component of the correction, thus resulting in an ordinary Quantile Mapping, i.e. corrects the bias by comparing the distributions of the biased dataset with a reference datasets. See params_mf of rex.utilities.bc_utils.QuantileDeltaMapping. Note that this assumes that params_mh is the data distribution representative for the target data.

  • delta_denom_min (float | None) – Option to specify a minimum value for the denominator term in the calculation of a relative delta value. This prevents division by a very small number making delta blow up and resulting in very large output bias corrected values. See equation 4 of Cannon et al., 2015 for the delta term.

  • delta_denom_zero (float | None) – Option to specify a value to replace zeros in the denominator term in the calculation of a relative delta value. This prevents division by a very small number making delta blow up and resulting in very large output bias corrected values. See equation 4 of Cannon et al., 2015 for the delta term.

  • delta_range (tuple | None) – Option to set a (min, max) on the delta term in QDM. This can help prevent QDM from making non-realistic increases/decreases in otherwise physical values. See equation 4 of Cannon et al., 2015 for the delta term.

  • out_range (None | tuple) – Option to set floor/ceiling values on the output data.

  • max_workers (int | None) – Max number of workers to use for QDM process pool

Returns:

out (np.ndarray) – The input data corrected by QDM. Its shape is the same of the input (spatial, spatial, time_window, temporal). The dimension time_window aligns with the number of time windows defined in a year, while temporal aligns with the time of the data.

See also

sup3r.bias.qdm.QuantileDeltaMappingCorrection

Estimate probability distributions required by QDM method

Notes

Be careful selecting bias_fp. Usually, the input data used here would be related to the dataset used to estimate “bias_fut_{feature_name}_params”.

Keeping arguments as consistent as possible with local_linear_bc(), thus a 4D data (spatial, spatial, time_window, temporal), and lat_lon (n_lats, n_lons, [lat, lon]). But QuantileDeltaMapping(), from rex library, expects an array, (time, space), thus we need to re-organize our input to match that, and in the end bring it back to (spatial, spatial, time_window, temporal). This is still better than maintaining the same functionality consistent in two libraries.

Also, rex.utilities.bc_utils.QuantileDeltaMapping expects params to be 2D (space, N-params).

See also

rex.utilities.bc_utils.QuantileDeltaMapping

Core QDM transformation.

Examples

>>> unbiased = local_qdm_bc(biased_array, lat_lon_array, "ghi", "rsds",
...                         "./dist_params.hdf")
Contents