% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DiffCorr.R
\name{DiffCorr}
\alias{DiffCorr}
\title{Compute the correlation difference and its significance}
\usage{
DiffCorr(
  exp,
  obs,
  ref,
  N.eff = NA,
  time_dim = "sdate",
  memb_dim = NULL,
  method = "pearson",
  alpha = 0.05,
  handle.na = "return.na",
  test.type = "two-sided",
  pval = TRUE,
  sign = FALSE,
  ncores = NULL
)
}
\arguments{
\item{exp}{A named numerical array of the forecast data with at least time 
dimension.}

\item{obs}{A named numerical array with the observations with at least time
dimension. The dimensions must be the same as "exp" except 'memb_dim'.}

\item{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'.}

\item{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.}

\item{time_dim}{A character string indicating the name of the time dimension.
The default value is 'sdate'.}

\item{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 (default), the ensemble mean should be provided
directly to the function.}

\item{method}{A character string indicating the correlation coefficient to be
computed ("pearson" or "spearman"). The default value is "pearson".}

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

\item{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".}

\item{test.type}{A character string indicating the type of significance test. 
It can be "two-sided" (to assess whether the skill of "exp" and "ref" are 
significantly different) or "one-sided" (to assess whether the skill of  
"exp" is significantly higher than that of "ref") following Steiger (1980).
The default value is "two-sided".}

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

\item{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.}

\item{ncores}{An integer indicating the number of cores to use for parallel 
computation. The default value is NULL.}
}
\value{
A list with:
\item{$diff.corr}{
 A numerical array of the correlation differences with the same dimensions as
 the input arrays except "time_dim" (and "memb_dim" if provided).
}
\item{$sign}{
 A logical array of the statistical significance of the correlation 
 differences with the same dimensions as the input arrays except "time_dim"
 (and "memb_dim" if provided). Returned only if "sign" is TRUE.
}
\item{$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.
}
}
\description{
Compute the correlation difference between two deterministic forecasts. 
Positive values of the correlation difference indicate that the forecast is 
more skillful than the reference forecast, while negative values mean that 
the reference forecast is more skillful. The statistical significance of the 
correlation differences is computed with a one-sided or two-sided test for 
equality of dependent correlation coefficients (Steiger, 1980; Siegert et al.,
2017) using effective degrees of freedom to account for the autocorrelation of
the time series (Zwiers and von Storch, 1995).
}
\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 = 10, sdate = 50))
res_two.sided_sign <- DiffCorr(exp, obs, ref, memb_dim = 'member', 
                               test.type = 'two-sided', alpha = 0.05)
res_one.sided_pval <- DiffCorr(exp, obs, ref, memb_dim = 'member', 
                               test.type = 'one-sided', alpha = NULL)

}
\references{
Steiger, 1980; https://content.apa.org/doi/10.1037/0033-2909.87.2.245
Siegert et al., 2017; https://doi.org/10.1175/MWR-D-16-0037.1
Zwiers and von Storch, 1995; https://doi.org/10.1175/1520-0442(1995)008<0336:TSCIAI>2.0.CO;2
}
