ResidualCorr {s2dv}

Compute the residual correlation and its significance

Description

The residual correlation assesses whether a forecast captures any of the observed variability that is not already captured by a reference forecast (Smith et al., 2019; https://doi.org/10.1038/s41612-019-0071-y.). The procedure is as follows: the residuals of the forecasts and observations are computed by linearly regressing out the reference forecast's ensemble mean from the forecasts' ensemble mean and observations, respectively. Then, the residual correlation is computed as the correlation between both residuals. Positive values of the residual correlation indicate that the forecast capture more observed variability than the reference forecast, while negative values mean that the reference forecast capture more. The significance of the residual correlation is computed with a two-sided t-test (Wilks, 2011; https://doi.org/10.1016/B978-0-12-385022-5.00008-7) using an effective degrees of freedom to account for the time series' autocorrelation (von Storch and Zwiers, 1999; https://doi.org/10.1017/CBO9780511612336).

Usage

ResidualCorr(
  exp,
  obs,
  ref,
  N.eff = NA,
  time_dim = "sdate",
  memb_dim = NULL,
  method = "pearson",
  alpha = 0.05,
  handle.na = "return.na",
  pval = TRUE,
  sign = FALSE,
  ncores = NULL
)

Arguments

exp

A named numerical array of the forecast with at least time dimension.

obs

A named numerical array of the observations with at least time dimension. The dimensions must be the same as "exp" except 'memb_dim'.

ref

A named numerical array of the reference forecast data with at least time dimension. The dimensions must be the same as "exp" except 'memb_dim'.

N.eff

Effective sample size to be used in the statistical significance test. It can be NA (and it will be computed with the s2dv:::.Eno), a numeric (which is used for all cases), or an array with the same dimensions as "obs" except "time_dim" (for a particular N.eff to be used for each case) . The default value is NA.

time_dim

A character string indicating the name of the time dimension. The default value is 'year'.

memb_dim

A character string indicating the name of the member dimension to compute the ensemble mean of the forecast and reference forecast. If it is NULL, the ensemble mean should be provided directly to the function. The default value is NULL.

method

A character string indicating the correlation coefficient to be computed ("pearson", "kendall", or "spearman"). The default value is "pearson".

alpha

A numeric of the significance level to be used in the statistical significance test (output "sign"). The default value is 0.05.

handle.na

A charcater string indicating how to handle missing values. If "return.na", NAs will be returned for the cases that contain at least one NA in "exp", "ref", or "obs". If "only.complete.triplets", only the time steps with no missing values in all "exp", "ref", and "obs" will be used. If "na.fail", an error will arise if any of "exp", "ref", or "obs" contains any NA. The default value is "return.na".

pval

A logical value indicating whether to return the p-value of the significance test Ho: DiffCorr = 0. The default value is TRUE.

sign

A logical value indicating whether to return the statistical significance of the test Ho: DiffCorr = 0 based on 'alpha'. The default value is FALSE.

ncores

An integer indicating the number of cores to use for parallel computation. The default value is NULL.

Value

A list with:

$res.corr

A numerical array of the residual correlation with the same dimensions as the input arrays except "time_dim" (and "memb_dim" if provided).

$sign

A logical array indicating whether the residual correlation is statistically significant or not with the same dimensions as the input arrays except "time_dim" (and "memb_dim" if provided). Returned only if "sign" is TRUE.

$p.val

A numeric array of the p-values with the same dimensions as the input arrays except "time_dim" (and "memb_dim" if provided). Returned only if "pval" is TRUE.

Examples

exp <- array(rnorm(1000), dim = c(lat = 3, lon = 2, member = 10, sdate = 50))
obs <- array(rnorm(1000), dim = c(lat = 3, lon = 2, sdate = 50))
ref <- array(rnorm(1000), dim = c(lat = 3, lon = 2, member = 5, sdate = 50))
res <- ResidualCorr(exp = exp, obs = obs, ref = ref, memb_dim = 'member')