\name{AnimVslTime}
\alias{AnimVslTime}
\title{Animate Variable Values Over Forecast Time}
\description{
  Create animations showing the anomalies, the climatologies, the mean 
  InterQuartile Range, Maximum-Mininum, Standard Deviation, Median Absolute 
  Deviation, the trends, the RMSE or correlation between modelled and observed 
  data along the forecast time for all input experiments & input observational 
  datasets.
}
\usage{
  AnimVslTime(var, lat, lon, toptitle = c("", "", "", "", "", "", "", "", "", 
  "", ""), units = "", monini = 1, freq = 12, msk95lev = FALSE, brk = NULL, 
  col = NULL, lonmin = 0, lonmax = 360, latmin = -90, latmax = 90, 
  center = NULL, equi = TRUE, fileout = c("output1_animvsltime", 
  "output2_animvsltime", "output3_animvsltime"))
}
\arguments{
  \item{var}{
    Matrix of dimensions (nltime, nlat, nlon)
                      or (nexp/nmod, nltime, nlat, nlon)
                      or (nexp/nmod, 3, nltime, nlat, nlon)
                      or (nexp/nmod, nobs, 3, nltime, nlat, nlon)
  }
  \item{lat}{
    Vector containing latitudes (°)
  }
  \item{lon}{
    Vector containing longtitudes (°)
  }
  \item{toptitle}{
    c('','', \dots) array of main title for each animation, optional.
    If RMS or correlations: first exp with successive obs, then second exp with 
    successive obs, etc ...
  }
  \item{units}{
    Units, optional
  }
  \item{monini}{
    Starting month between 1 and 12. Default = 1
  }
  \item{freq}{
    1 = yearly, 12 = monthly, 4 = seasonal ...
  }
  \item{msk95lev}{
    T/F grid points masked if 95% significance level not reached. 
    Default = F
  }
  \item{brk}{
    Limits of colour levels, optional. For example:
    seq(min(var), max(var), (max(var) - min(var)) / 10)
  }
  \item{col}{
    Vector of colours of length(brk) - 1, optional.
  }
  \item{lonmin}{
    Westward limit of the domain to plot (> 0 or < 0).
    Default : 0°
  }
  \item{lonmax}{
    Eastward limit of the domain to plot (> 0 or < 0).
    lonmax > lonmin. Default : 360°
  }
  \item{latmin}{
    Southward limit of the domain to plot. Default : -90°
  }
  \item{latmax}{
    Northward limit of the domain to plot. Default : 90°
  }
  \item{center}{
    (latitude, longitude, angle) for stereographic projection
  }
  \item{equi}{
    TRUE/FALSE == cylindrical equidistant/stereographic projection. 
    Default: TRUE
  }
  \item{fileout}{
    c('', '', \dots) array of output file name for each animation without extension. 
    If RMS or correlations : first exp with successive obs, then second exp 
    with successive obs, etc ...
  }
}
\details{
  Examples of input:
  ------------------

  1- Outputs from clim (exp, obs, memb=F):
           (nmod, nltime, nlat, nlon)
        or (nobs, nltime, nlat, nlon)

  2- Model output from load/ano/smoothing:
           (nmod, nmemb, sdate, nltime, nlat, nlon)
  then passed through spread(var, posdim = 2, narm = T)
                    & mean1dim(var, posdim = 3, narm = T)
  or through trend(mean1dim(var, 2), posTR = 2):
           (nmod, 3, nltime, nlat, nlon)
  animates average along start dates of IQR/MaxMin/SD/MAD across members 
  or trends of the ensemble-mean computed accross the start dates.

  3- model and observed output from load/ano/smoothing:
           (nmod, nmemb, sdate, nltime, nlat, nlon)
         & (nobs, nmemb, sdate, nltime, nlat, nlon)
  then averaged along members mean1dim(var_exp/var_obs, posdim = 2):
           (nmod, sdate, nltime, nlat, nlon)
           (nobs, sdate, nltime, nlat, nlon)
  then passed through corr(exp, obs, posloop = 1, poscor = 2)
                   or RMS(exp, obs, posloop = 1, posRMS = 2):
           (nmod, nobs, 3, nltime, nlat, nlon)
  animates correlations or RMS between each exp & each obs against leadtime.
}
\author{
  History:
  1.0  -  2012-04  (V. Guemas, \email{vguemas@ic3.cat})  -  Original code
}
\keyword{dynamic}
