% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/QUALYPSO.r
\name{QUALYPSO}
\alias{QUALYPSO}
\title{QUALYPSO}
\usage{
QUALYPSO(Y, scenAvail, X = NULL, Xfut = NULL, iFut = NULL, listOption = NULL)
}
\arguments{
\item{Y}{matrix \code{nS} x \code{nY} or array \code{nG} x \code{nS} x \code{nY} of climate projections.}

\item{scenAvail}{data.frame \code{nS} x \code{nEff} with the \code{nEff} characteristics
(e.g. type of GCM) for each of the \code{nS} scenarios. The number of characteristics
 \code{nEff} corresponds to the number of main effects that will be included in the ANOVA model.}

\item{X}{(optional) predictors corresponding to the projections, e.g. time or global temperature.
It can be a vector if the predictor is the same for all scenarios (e.g. \code{X=2001:2100}) or
a matrix of the same size as Y if these predictors are different for the scenarios. By default,
a vector \code{1:nY} is created.}

\item{Xfut}{(optional) \code{nF} values of the predictor over which the ANOVA will be applied. It must be
a vector of values within the range of values of X. By default, it corresponds to X if X is a vector,
\code{1:nY} if X is \code{NULL} or a vector of 10 values equally spaced between the minimum and
maximum values of X if X is a matrix.}

\item{iFut}{index in \code{1:nF} corresponding to a future predictor value . This index is
necessary when \code{Y} is an array \code{nG} x \code{nS} x \code{nY} available for \code{nG} grid points.
Indeed, in this case, we run QUALYPSO only for one future predictor. The first value defines the reference
period or warming level.}

\item{listOption}{(optional) list of options
\itemize{
   \item \strong{typeClimateResponse}: type of climate response fitted to the projections. Can be either
"smooth.spline" (\code{\link[stats]{smooth.spline}}) where the parameter \code{df} in (1,nY] is the 
equivalent number of degrees of freedom, "poly" (polynomial model fitted with \code{\link[stats]{lm}})
where the parameter \code{degree} is an integer indicating the degree of the polynomial (\code{\link[stats]{poly}}), 
"lowess" (\code{\link[stats]{lowess}}) where the parameter \code{f} in (0,1) is the proportion of points which influence
the smooth at each value, or "tweedie", a Generalized Linear Model with the Tweedie distribution where the parameter 
\code{var.power} is the index of power variance function (positive value). The values 0, 1, 2 and 3 correspond to the
 normal distribution, the Poisson distribution, the gamma distribution and the inverse-Gaussian distribution respectively
(\code{\link[statmod]{tweedie}}). The tweedie model is the only model that handles zeros in the climate projections.
  \item \strong{parClimateResponse}: parameter of the model applied for the extraction of the climate response (i.e. df, degree,
f, or var.power). Default values are \code{df=4}, \code{degree=1}, \code{f=0.4} or \code{var.power=1.5} for the smoothing spline, 
polynomial, lowess, or tweedie models, respectively.
  \item \strong{typeChangeVariable}: type of change variable: "abs" (absolute, value by default) or "rel" (relative).
  \item \strong{ANOVAmethod}: ANOVA method: "Bayesian" applies the method described in Evin et al. (2020),
  "lm" applies a simple linear model to estimate the main effects.
  \item \strong{nBurn}: if \code{ANOVAmethod=="Bayesian"}, number of burn-in samples (default: 1000).
  If \code{nBurn} is too small, the convergence of MCMC chains might not be obtained.
  \item \strong{nKeep}: if \code{ANOVAmethod=="Bayesian"}, number of kept samples (default: 2000).
  If \code{nKeep} is too small, MCMC samples might not represent correctly the posterior
  distributions of inferred parameters.
  \item \strong{probCI}: probability (in [0,1]) for the confidence intervals, \code{probCI = 0.9} by default.
  \item \strong{quantilePosterior}: vector of probabilities (in [0,1]) for which
  we compute the quantiles from the posterior distributions
   \code{quantilePosterior = c(0.005,0.025,0.05,0.1,0.25,0.33,0.5,0.66,0.75,0.9,0.95,0.975,0.995)} by default.
  \item \strong{climResponse}: NULL by default. If it is provided, it must correspond to the outputs
  of \code{\link{fit.climate.response}}, i.e. a list with \code{YStar} [nS x nY], \code{phiStar} [nS x nF],
  \code{etaStar} [nS x nY], \code{phi} [nS x nF] and \code{varInterVariability} [nF].
}}
}
\value{
List providing the results for each of the \code{n} values of \code{Xfut}
if \code{Y} is a matrix or for each grid point if \code{Y} is an array, with the following fields:
\itemize{
  \item \strong{CLIMATERESPONSE}: list of climate change responses and
 corresponding internal variability. Contains \code{phiStar} (climate change
 responses), \code{etaStar} (deviation from the climate change responses as
 a result of internal variability), \code{Ystar} (change variable from the
 projections),and \code{phi} (fitted climate responses).
  \item \strong{GRANDMEAN}: List of estimates for the grand mean:
  \itemize{
     \item \strong{MEAN}: vector of length \code{n} of means.
     \item \strong{SD}: vector of length \code{n} of standard dev.
     \item \strong{CI}: matrix \code{n} x 2 of credible intervals of
     probability \code{probCI} given in \code{listOption}
     \item \strong{QUANT}: matrix \code{n} x \code{nQ} of quantiles of
     probability \code{quantilePosterior} given in \code{listOption} if
     \code{ANOVAmethod=="Bayesian"}.
  }
  \item \strong{MAINEFFECT}: List of estimates for the main effects. For each
  main effect (GCM, RCM,..), each element of the list contains a list with:
  \itemize{
     \item \strong{MEAN}: matrix \code{n} x \code{nTypeEff}
     \item \strong{SD}: matrix \code{n} x \code{nTypeEff} of standard dev.
     \item \strong{CI}: array \code{n} x 2 x \code{nTypeEff} of credible
     intervals of probability \code{probCI} given in \code{listOption}
     \item \strong{QUANT}: array \code{n} x \code{nQ} x \code{nTypeEff} of
     quantiles of probability \code{quantilePosterior} given in
     \code{listOption} if \code{ANOVAmethod=="Bayesian"}.
  }
  \item \strong{CHANGEBYEFFECT}: For each main effect, list of estimates for
  the mean change by main effect, i.e. mean change by scenario. For
  each main effect (GCM, RCM,..), each element of the list contains a list with:
  \itemize{
     \item \strong{MEAN}: matrix \code{n} x \code{nTypeEff}
     \item \strong{SD}: matrix \code{n} x \code{nTypeEff} of standard dev.
     if \code{ANOVAmethod=="Bayesian"}.
     \item \strong{CI}: array \code{n} x 2 x \code{nTypeEff} of credible
     intervals of probability \code{probCI} given in \code{listOption} if
     \code{ANOVAmethod=="Bayesian"}.
     \item \strong{QUANT}: array \code{n} x \code{nQ} x \code{nTypeEff} of
     quantiles of probability \code{quantilePosterior} given in
     \code{listOption} if \code{ANOVAmethod=="Bayesian"}.
  }
  \item \strong{EFFECTVAR}: Matrix \code{n} x \code{nTypeEff} giving, for each
  time variability related to the main effects (i.e.
  variability between the different RCMs, GCMs,..).
  \item \strong{CONTRIB_EACH_EFFECT}: Contribution of each individual effect
  to its component (percentage), e.g. what is the contribution of GCM1 to the
   variability related to GCMs. For each main effect (GCM, RCM,..), each
   element of the list contains a matrix \code{n} x \code{nTypeEff}
  \item \strong{RESIDUALVAR}: List of estimates for the variance of the
  residual errors:
  \itemize{
     \item \strong{MEAN}: vector of length \code{n}.
     \item \strong{SD}: vector of length \code{n} of standard dev.
     if \code{ANOVAmethod=="Bayesian"}.
     \item \strong{CI}: matrix \code{n} x 2 of credible intervals of
     probability \code{probCI} given in \code{listOption} if
     \code{ANOVAmethod=="Bayesian"}.
     \item \strong{QUANT}: matrix \code{n} x \code{nQ} of quantiles of
     probability \code{quantilePosterior} given in \code{listOption} if
     \code{ANOVAmethod=="Bayesian"}.
  }
  \item \strong{INTERNALVAR}: Internal variability (constant over time)
  \item \strong{TOTALVAR}: total variability, i.e. the sum of internal variability,
      residual variability and variability related to the main effects
  \item \strong{DECOMPVAR}: Decomposition of the total variability for each component
  \item \strong{RESERR}: differences between the climate change responses and the additive anova formula (grand mean + main effects)
  \item \strong{Xmat}: matrix of predictors
  \item \strong{Xfut}: future predictor values
  \item \strong{namesEff}: names of the main effects
  \item \strong{Y}: matrix of available combinations given as inputs
  \item \strong{listOption}: list of options used to obtained these results
  (obtained from \code{\link{QUALYPSO.check.option}})
  \item \strong{listScenarioInput}: list of scenario characteristics
  (obtained from \code{\link{QUALYPSO.process.scenario}})
}
}
\description{
Partition uncertainty in climate responses using an ANOVA applied to climate change responses.
}
\examples{

#____________________________________________________________
# CALLING QUALYPSO
#____________________________________________________________
# call main QUALYPSO function: two arguments are mandatory:
# - Y: Climate projections for nS scenarios and nY time steps. Y is a matrix nS x nY, we
# run QUALYPSO nY times, for each time step.
# - scenAvail: matrix or data.frame of available combinations nS x nEff. The number of
# characteristics nEff corresponds to the number of main effects that will be included in the
# ANOVA model. In the following example, we have nEff=2 main effects corresponding to the GCMs
# and RCMs.

# Many options can be specified in the argument "listOption".

#____________________________________________________________
# Example 1: Synthetic scenarios
#____________________________________________________________
# create nS=3 fictive climate scenarios with 2 GCMs and 2 RCMs, for a period of nY=20 years
n=20
t=0:n/n

# GCM effects (sums to 0 for each t)
effGCM1 = t*2
effGCM2 = t*1
effGCM3 = t*-3

# RCM effects (sums to 0 for each t)
effRCM1 = t*1
effRCM2 = t*-1

# These climate scenarios are a sum of effects and a random gaussian noise
scenGCM1RCM1 = effGCM1 + effRCM1 + rnorm(n=n+1,sd=0.5)
scenGCM1RCM2 = effGCM1 + effRCM2 + rnorm(n=n+1,sd=0.5)
scenGCM2RCM1 = effGCM2 + effRCM1 + rnorm(n=n+1,sd=0.5)
scenGCM2RCM2 = effGCM2 + effRCM2 + rnorm(n=n+1,sd=0.5)
scenGCM3RCM1 = effGCM3 + effRCM1 + rnorm(n=n+1,sd=0.5)
Y.synth = rbind(scenGCM1RCM1,scenGCM1RCM2,scenGCM2RCM1,scenGCM2RCM2,scenGCM3RCM1)

# Here, scenAvail indicates that the first scenario is obtained with the combination of the
# GCM "GCM1" and RCM "RCM1", the second scenario is obtained with the combination of
# the GCM "GCM1" and RCM "RCM2" and the third scenario is obtained with the combination
# of the GCM "GCM2" and RCM "RCM1".
scenAvail.synth = data.frame(GCM=c('GCM1','GCM1','GCM2','GCM2','GCM3'),
RCM=c('RCM1','RCM2','RCM1','RCM2','RCM1'))


# run QUALYPSO
QUALYPSO.synth = QUALYPSO(Y=Y.synth, scenAvail=scenAvail.synth, X=2000:2020,
listOption = list(typeClimateResponse="poly"))

# plot main GCM effects
plotQUALYPSOeffect(QUALYPSO.synth,nameEff="GCM",xlab="Years")
lines(2000:2020, effGCM1,lty=2,lwd=2,col="black")
lines(2000:2020, effGCM2,lty=2,lwd=2,col="red")
lines(2000:2020, effGCM3,lty=2,lwd=2,col="green")

# plot main RCM effects
plotQUALYPSOeffect(QUALYPSO.synth,nameEff="RCM",xlab="Years")
lines(2000:2020, effRCM1,lty=2,lwd=2,col="black")
lines(2000:2020, effRCM2,lty=2,lwd=2,col="red")

# plot fraction of total variance for the differences sources of uncertainty
plotQUALYPSOTotalVarianceDecomposition(QUALYPSO.synth,xlab="Years")

#____________________________________________________________
# Example 2: climate projections of mean winter (DJF) temperature
# with time as the predictor
#____________________________________________________________

# list of options
listOption = list(typeChangeVariable='abs')

# call QUALYPSO
QUALYPSO.time = QUALYPSO(Y=Y,scenAvail=scenAvail,X=X_time_vec,
                         Xfut=Xfut_time,listOption=listOption)

# grand mean effect
plotQUALYPSOgrandmean(QUALYPSO.time,xlab="Years")

# main GCM effects
plotQUALYPSOeffect(QUALYPSO.time,nameEff="GCM",xlab="Years")

# main RCM effects
plotQUALYPSOeffect(QUALYPSO.time,nameEff="RCM",xlab="Years")

# variance decomposition
plotQUALYPSOTotalVarianceDecomposition(QUALYPSO.time,xlab="Years")

#____________________________________________________________
# Example 3: climate projections of mean winter (DJF) temperature
# with global temperature as the predictor
#____________________________________________________________

# list of options
listOption = list(typeChangeVariable='abs')

# call QUALYPSO
QUALYPSO.globaltas = QUALYPSO(Y=Y,scenAvail=scenAvail,X=X_globaltas,
                              Xfut=Xfut_globaltas,listOption=listOption)

# grand mean effect
plotQUALYPSOgrandmean(QUALYPSO.globaltas,xlab="Global warming (Celsius)")

# main GCM effects
plotQUALYPSOeffect(QUALYPSO.globaltas,nameEff="GCM",xlab="Global warming (Celsius)")

# main RCM effects
plotQUALYPSOeffect(QUALYPSO.globaltas,nameEff="RCM",xlab="Global warming (Celsius)")

# variance decomposition
plotQUALYPSOTotalVarianceDecomposition(QUALYPSO.globaltas,xlab="Global warming (Celsius)")

}
\references{
Evin, G., B. Hingray, J. Blanchet, N. Eckert, S. Morin, and D. Verfaillie (2020)
Partitioning Uncertainty Components of an Incomplete Ensemble of Climate Projections Using Data Augmentation.
Journal of Climate. <doi:10.1175/JCLI-D-18-0606.1>.
}
\author{
Guillaume Evin
}
