CST_Calibration.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/CST_Calibration.R
\name{CST_Calibration}
\alias{CST_Calibration}
\title{Forecast Calibration}
\usage{
CST_Calibration(
  exp,
  obs,
  exp_cor = NULL,
  cal.method = "mse_min",
  eval.method = "leave-one-out",
  multi.model = FALSE,
  na.fill = TRUE,
  na.rm = TRUE,
  apply_to = NULL,
  alpha = NULL,
  memb_dim = "member",
  sdate_dim = "sdate",
  dat_dim = NULL,
  ncores = NULL
)
}
\arguments{
\item{exp}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} 
function, containing the seasonal hindcast experiment data in the element 
named \code{$data}. The hindcast is used to calibrate the forecast in case 
the forecast is provided; if not, the same hindcast will be calibrated 
instead.}

\item{obs}{An object of class \code{s2dv_cube} as returned by \code{CST_Load} 
function, containing the observed data in the element named \code{$data}.}

\item{exp_cor}{An optional object of class \code{s2dv_cube} as returned by 
\code{CST_Load} function, containing the seasonal forecast experiment data 
in the element named \code{$data}. If the forecast is provided, it will be 
calibrated using the hindcast and observations; if not, the hindcast will 
be calibrated instead.  The dimensions must be the same as 'exp' except 
dataset dimension. If there is only one corrected dataset, it should not 
have dataset dimension. If there is a corresponding corrected dataset for 
each 'exp' forecast, the dataset dimension must have the same length as in 
'exp'. The default value is NULL.}

\item{cal.method}{A character string indicating the calibration method used, 
can be either \code{bias}, \code{evmos}, \code{mse_min}, \code{crps_min} or 
\code{rpc-based}. Default value is \code{mse_min}.}

\item{eval.method}{A character string indicating the sampling method used, it 
can be either \code{in-sample} or \code{leave-one-out}. Default value is the 
\code{leave-one-out} cross validation. In case the forecast is provided, any 
chosen eval.method is over-ruled and a third option is used.}

\item{multi.model}{A boolean that is used only for the \code{mse_min} 
method. If multi-model ensembles or ensembles of different sizes are used, 
it must be set to \code{TRUE}. By default it is \code{FALSE}. Differences 
between the two approaches are generally small but may become large when 
using small ensemble sizes. Using multi.model when the calibration method is 
\code{bias}, \code{evmos} or \code{crps_min} will not affect the result.}

\item{na.fill}{A boolean that indicates what happens in case calibration is 
not possible or will yield unreliable results. This happens when three or 
less forecasts-observation pairs are available to perform the training phase 
of the calibration. By default \code{na.fill} is set to true such that NA 
values will be returned. If \code{na.fill} is set to false, the uncorrected 
data will be returned.}

\item{na.rm}{A boolean that indicates whether to remove the NA values or not. 
The default value is \code{TRUE}. See Details section for further 
information about its use and compatibility with \code{na.fill}.}

\item{apply_to}{A character string that indicates whether to apply the 
calibration to all the forecast (\code{"all"}) or only to those where the 
correlation between the ensemble mean and the observations is statistically
significant (\code{"sign"}). Only useful if \code{cal.method == "rpc-based"}.}

\item{alpha}{A numeric value indicating the significance level for the 
correlation test. Only useful if \code{cal.method == "rpc-based" & apply_to == "sign"}.}

\item{memb_dim}{A character string indicating the name of the member dimension.
By default, it is set to 'member'.}

\item{sdate_dim}{A character string indicating the name of the start date 
dimension. By default, it is set to 'sdate'.}

\item{dat_dim}{A character string indicating the name of dataset dimension. 
The length of this dimension can be different between 'exp' and 'obs'. 
The default value is NULL.}

\item{ncores}{An integer that indicates the number of cores for parallel 
computations using multiApply function. The default value is one.}
}
\value{
An object of class \code{s2dv_cube} containing the calibrated forecasts 
 in the element \code{$data} with the same dimensions as the one in the exp 
 object.
}
\description{
Equivalent to function \code{Calibration} but for objects of 
class \code{s2dv_cube}.
}
\examples{
# Example 1:
mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7)
dim(mod1) <- c(dataset = 1, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7)
obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7)
dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7)
lon <- seq(0, 30, 5)
lat <- seq(0, 25, 5)
exp <- list(data = mod1, lat = lat, lon = lon)
obs <- list(data = obs1, lat = lat, lon = lon)
attr(exp, 'class') <- 's2dv_cube'
attr(obs, 'class') <- 's2dv_cube'
a <- CST_Calibration(exp = exp, obs = obs, cal.method = "mse_min", eval.method = "in-sample")
str(a)

# Example 2:
mod1 <- 1 : (1 * 3 * 4 * 5 * 6 * 7)
mod2 <- 1 : (1 * 3 * 1 * 5 * 6 * 7)
dim(mod1) <- c(dataset = 1, member = 3, sdate = 4, ftime = 5, lat = 6, lon = 7)
dim(mod2) <- c(dataset = 1, member = 3, sdate = 1, ftime = 5, lat = 6, lon = 7)
obs1 <- 1 : (1 * 1 * 4 * 5 * 6 * 7)
dim(obs1) <- c(dataset = 1, member = 1, sdate = 4, ftime = 5, lat = 6, lon = 7)
lon <- seq(0, 30, 5)
lat <- seq(0, 25, 5)
exp <- list(data = mod1, lat = lat, lon = lon)
obs <- list(data = obs1, lat = lat, lon = lon)
exp_cor <- list(data = mod2, lat = lat, lon = lon)
attr(exp, 'class') <- 's2dv_cube'
attr(obs, 'class') <- 's2dv_cube'
attr(exp_cor, 'class') <- 's2dv_cube'
a <- CST_Calibration(exp = exp, obs = obs, exp_cor = exp_cor, cal.method = "evmos")
str(a)
}
\seealso{
\code{\link{CST_Load}}
}
\author{
Verónica Torralba, \email{veronica.torralba@bsc.es}

Bert Van Schaeybroeck, \email{bertvs@meteo.be}
}