\name{ACC}
\alias{ACC}
\title{
  Computes Anomaly Correlation Coefficient (Spatial Correlation)
}
\description{
  Matrix var_exp & var_obs should have dimensions (nexp/nobs, nsdates, 
  nltimes, nlat, nlon) or (nexp/nobs, nsdates, nmember, nltimes, nlat, nlon)
  ACC computes the Anomaly Correlation Coefficient for the ensemble mean of
  each jexp in 1:nexp and each jobs in 1:nobs which gives nexp x nobs ACC 
  for each startdate and each leadtime.
  A domain can be selected by providing the list of longitudes/latitudes
  (lon/lat) of the grid together with the corner of the domain:
  lonlatbox = c(lonmin, lonmax, latmin, latmax)
}
\usage{
ACC(var_exp, var_obs, lon = NULL, lat = NULL,
                lonlatbox = NULL, conf = TRUE, conftype = "parametric",
                nrmemb=100, nrspa=0, nrdate=0,
                blocspa=1, blocdate=1) 
}
\arguments{
  \item{var_exp}{
    Matrix of experimental data with dimensions: 
      c(nexp, nsdates, nltimes, nlat, nlon)
  }
  \item{var_obs}{Matrix of observational data, same dimensions as var_exp except 
    along the first dimension and the second if it corresponds to
    the members dimension.
  }
  \item{lon}{
    Array of longitudes of the var_exp/var_obs grids, optional.
  }
  \item{lat}{
    Array of latitudes of the var_exp/var_obs grids, optional.
  }
  \item{lonlatbox}{
    Domain to select : c(lonmin, lonmax, latmin, latmax), optional.
  }
  \item{conf}{
    TRUE/FALSE 
    confidence intervals or significance level provided or not.
  }
  \item{conftype}{
    "parametric" provides a confidence interval for the ACC computed 
    by a Fisher transformation and a significance level 
    for the ACC from a one-sided student-T distribution
    "bootstrap" provides a confidence interval for the ACC and MACC
     computed from bootstrapping . 
     To guarantee the statistical robustness of the result,
     make sure that your experiments/oservations/startdates/
     leadtimes always have the same number of members.
     (even if it is one, see nrmemb for more detail).
     The total number of drawing is nrmemb*(nrspa + 1) for ACC
     and nrmemb*(nrspa + 1)*(nrdate +1) for MACC.
   }
   \item{nrmemb}{
     Number of drawing with replacement over the members (default: 100).
     If there is only one member in both observation and model, set to
     one.
   }
   \item{nrspa}{
     Number of drawing with replacement over the spatial dimensions.
     The re-sampling is done by blocs of size of blocspa
     (see blocpa for more details). If nrspa = 0 (Default)
     no spatial bootstraping is performed.
   }
   \item{nrdate}{
     Number of drawing with replacement over the stardates dimensions. 
     The re-sampling is done by blocs of size of blocdate
     (see blodate for more details). If nrdate = 0 (Default)
     no temporal bootstraping is performed.
     (only available if nrspa>0)
   }
   \item{blocspa}{
     Size of the square bloc for the spatial re-sampling (Default: 1)
   }
   \item{blocdate}{
     Size of the bloc for the temporal re-sampling (Default: 1)
   }
 }
\value{
  \item{ACC}{
    If conf set as TRUE, Matrix with dimensions :
    c(nexp, nobs, nsdates, nleadtimes, 4).
    The fifth dimension of length 4 corresponds to the lower limit of
    the 95\% confidence interval, the computed ACC, the upper limit of 
    the 95\% confidence interval and the 95\% significance level given by 
    a one-sided T-test (only for the parametric option).
    If the confidence interval is estimated with the bootstrap option,
    The size of the distribution used to calculate it will be:
    nrmemb*(nrspa + 1). If the bootstrap option is set no significance
    level is given.
  }
  \item{MACC}{
    Mean Anomaly Correlation Coefficient 
    if conf equal TRUE:
    Matrix with c(nexp, nobs, nleadtimes, 3) dimensions.
    The fourth dimension of length 3 corresponds to the lower limit
    of the 95\% confidence interval, the computed MACC and the upper 
    limit of the 95\% confidence interval
    If the confidence interval is estimated with the bootstrap option,
    The size of the distribution used to calculate it will be:
    nrmemb*(nrspa + 1)*(nrspa + 1)*(nrdate +1)
    if conf equal FALSE:
    Matrix with c(nexp, nobs, nleadtimes) dimensions.
  }
  \item{ACCdiff}{
    Difference of anomaly Correlation Coefficient
  if conf equal TRUE and conftype="bootstrap":
    The difference between the first experience of the var_exp
    matrix and all other experiment is computed.
    The results have the dimensions:
    Matrix with c(nexp-1, nobs, nsdates, nleadtimes, 3) dimensions.
    The fourth dimension of length 3 corresponds to the lower limit
    of the 95\% confidence interval of the difference,
    the difference and the upper 
    limit of the 95\% confidence interval of the difference.
    If the confidence interval is estimated with the bootstrap option,
    The size of the distribution used to calculate it will be:
    nrmemb*(nrspa + 1)
  }
   \item{MACCdiff}{Difference of mean anomaly Correlation Coefficient
  if conf equal TRUE and conftype="bootstrap":
     The difference between the first experience of the var_exp
    matrix and all other experiment is computed.
    The results have the dimensions:
    Matrix with c(nexp-1, nobs, nleadtimes, 3) dimensions.
    The fourth dimension of length 3 corresponds to the lower limit
    of the 95\% confidence interval of the difference,
    the difference and the upper 
    limit of the 95\% confidence interval of the difference.
    If the confidence interval is estimated with the bootstrap option,
    The size of the distribution used to calculate it will be:
    nrmemb*(nrspa + 1)*(nrdate +1)
  } 
}
\examples{
  startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
  sampleData <- Load('tos', c('i00k'), c('ERSST'), startDates, nleadtime = 124, 
                     leadtimemin = 1, leadtimemax = 4, output = 'lonlat', 
                     latmin = 30, latmax = 45, lonmin = 0, lonmax = 40)
  sampleData$mod <- Season(sampleData$mod, 4, 11, 12, 2)
  sampleData$obs <- Season(sampleData$obs, 4, 11, 12, 2)
  clim <- Clim(sampleData$mod, sampleData$obs)
  ano_exp <- Ano(sampleData$mod, clim$clim_exp)
  ano_obs <- Ano(sampleData$obs, clim$clim_obs)
  acc <- ACC(Mean1Dim(sampleData$mod, 2), 
             Mean1Dim(sampleData$obs, 2),
             conftype = "parametric")
  PlotACC(acc$ACC, startDates )
}
\author{
  History:
  0.1  -  2013-08  (V. Guemas, \email{virginie.guemas@ic3.cat})  -  Original code
  1.0  -  2013-09  (N. Manubens, \email{nicolau.manubens@ic3.cat})  - Formatting to CRAN
  1.1  -  2013-09  (C. Prodhomme, \email{chloe.prodhomme@ic3.cat})  - optimization
  
  1.2  -  2014-08  (V. Guemas, \email{virginie.guemas@ic3.cat}) - Bug-fixes : handling of
                                NA & selection of domain + Simplification of code
  1.3.0  -  2014-08  (V. Guemas, \email{virginie.guemas@ic3.cat}) - Boostrapping over members
  1.3.1  -  2014-09  (C. Prodhomme, chloe.prodhomme@ic3.cat) - Add
  comments and minor style changes
  1.3.1  -  2014-09  (C. Prodhomme, chloe.prodhomme@ic3.cat) - Add
                                spatial and temporal bootstrapping options
}
}\keyword{datagen}
