r2d2: Apply the R2D2 multivariate bias-correction method.
In thaos/R2D2: R2D2 multivariate correction bias-correction method

Description Usage Arguments Details Value Examples

View source: R/r2d2_algo.R

r2d2 applies the R2D2 algorithm to correct the dependence structure of the (previously univariately corrected) bc1d dataset.

1	r2d2(refdata, bc1d, icond = c(1), lag_search = 0, lag_keep = 0)

`refdata`	A matrix of dimension `T_ref x P` that contains the reference data, where `T_ref` is the number of time steps and `P` is the number of variables.
`bc1d`	A matrix of dimension `T x P`. It contains the results of a 1D-bias correction method applied over the T time steps to the `P` variables (separately for each variable).
`icond`	A vector of integers giving the indices of the variables in `refdata` and `bc1d` that are to be used as conditioning dimensions when searching the best analogue in `refdata` for the rank association of the conditioning dimension in `bc1d`
`lag_search`	An integer corresponding to the number of time lags to account for when searching in `refdata` the best analogue of the conditioning dimension rank association observed in `bc1d`. The default value is no lag, i.e., `lag_search`=0.
`lag_keep`	An integer corresponding to the number of time lags to keep in the correction for each best analogue of rank associations found. `lag_keep` has to be lower or equal to `lag_search`. The default value is no lag, i.e., `lag_search`=0.

This function performs the R2D2 rank resampling conditionnaly to the conditioning dimensions, to correct the dependence structure of the P variables of a dataset bc1d in terms of rank (i.e. copula). The resulting dependence structure is adjusted with respect to dependence structure of the reference dataset, refdata.

The dataset bc1d contains data whose P variables have already been corrected by a univariate (1D) bias-correction method. Note that bc1d and refdata must not have any NA values.

Ideally, the number of time steps in the bc1d dataset and in the refdata reference dataset should be equal (T = T_refdata). If this is not the case, the ranks of the largest dataset are shrinked so that both datasets have the same maximal rank.

For the full reference, see : Vrac, M. Multivariate bias adjustment of high-dimensional climate simulations: the Rank Resampling for Distributions and Dependences (R2D2) Bias Correction. Hydrol. Earth Syst. Sci., 22, 3175-3196, https://doi.org/10.5194/hess-22-3175-2018

A list with the following elements:

ranks_ref A matrix of dimension T_ref x P with the ranks of refdata
ranks_bc1d A matrix of dimension T x P with the ranks of bc1d
sorted_bc1d A matrix of dimension min(T, T_ref) x P with the sorted values of bc1d that are available for the correction. if T > T_ref the number of possible value for correction per variable is shrunk to T_ref
r2d2_bc A matrix of dimension T x P with the bc1d data corrected by the R2D2 bias-correction method
visited_time A vector of length T_ref with the number of times that the rank of a specific time step in refdata at time T_ref[i] has been resampled to create r2d2_bc.
time_bestanalogue A vector indentifying the time indices of the best rank association analogues found in refdata for each block of conditioning dimensions. The time index of the best analogue corresponds to the last time step of the rank association block.
dist_bestanalogue A vector with the euclidean distances between the rank associations in bc1d and the best analogues found in refdata for each block of conditioning dimensions.

# Reproducing the example provided in Vrac (2018)

refdata <- matrix(c(0.3, 0.5, 0.9, 0.8,
 1.1, 1.7, 1.2, 1.9,
 2.1, 1.8, 3.0, 2.7), ncol = 3, nrow = 4)

bc1d <- matrix(c(0.7, 0.5, 0.2, 0.9,
 1.3, 1.8, 1.1, 1.4,
 1.9, 2.9, 2.0, 2.6), ncol = 3, nrow = 4)

# 1 conditioning dimension, 0 lag
r2d2(refdata = refdata,
 bc1d = bc1d,
 icond = 1)

r2d2(refdata = refdata,
 bc1d = bc1d,
 icond = 2)

r2d2(refdata = refdata,
 bc1d = bc1d,
 icond = 3)

# 1 conditioning dimension, 1 lag search, 1 lag keep
r2d2(refdata = refdata,
 bc1d = bc1d,
 icond = 1,
 lag_search = 1,
 lag_keep = 1)

# 2 conditioning dimensions, 1 lag search, 1 lag keep
r2d2(refdata = refdata,
 bc1d = bc1d,
 icond = 1:2,
 lag_search = 1,
 lag_keep = 1)


# with climate data
data("r2d2_example")

# conditioning dimension: temperature in Paris
r2d2_correction <-  r2d2(
  refdata = r2d2_example$refdata,
  bc1d =  r2d2_example$bc1d,
  icond =  1,
  lag_search = 8, lag_keep = 6 )

# conditioning dimension: temperature and precipitation in Paris
r2d2_correction <-  r2d2(
  refdata = r2d2_example$refdata,
  bc1d =  r2d2_example$bc1d,
  icond =  c(1, 6),
  lag_search = 8, lag_keep = 6 )