\name{AnimVsLTime}
\alias{AnimVsLTime}
\title{Animate Forecast/Observed Values or Scores 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, the correlation or the RMSSS, between 
  modelled and observed data along the forecast time (lead-time) for all 
  input experiments and input observational datasets.
}
\usage{
  AnimVsLTime(var, lon, lat, toptitle = c("", "", "", "", "", "", "", "", "", 
  "", ""), sizetit = 1, units = "", monini = 1, freq = 12, msk95lev = FALSE, 
  brks = NULL, cols = NULL, filled.continents = FALSE, lonmin = 0, lonmax = 360, 
  latmin = -90, latmax = 90, intlon = 20, intlat = 30, drawleg = TRUE, 
  subsampleg = 1, colNA='white', equi = TRUE, fileout = c("output1_animvsltime.gif", 
  "output2_animvsltime.gif", "output3_animvsltime.gif"))
}
\arguments{
  \item{var}{
    Matrix of dimensions (nltime, nlat, nlon)
                      or (nexp/nmod, nltime, nlat, nlon)
                      or (nexp/nmod, 3/4, nltime, nlat, nlon)
                      or (nexp/nmod, nobs, 3/4, nltime, nlat, nlon)
  }
  \item{lat}{
    Vector containing latitudes (degrees)
  }
  \item{lon}{
    Vector containing longtitudes (degrees)
  }
  \item{toptitle}{
    c('','', \dots) array of main title for each animation, optional.
    If RMS, RMSSS, correlations: first exp with successive obs, then second exp 
    with successive obs, etc ...
  }
  \item{sizetit}{
    Multiplicative factor to increase title size, optional
  }
  \item{units}{
    Units, optional
  }
  \item{monini}{
    Starting month between 1 and 12. Default = 1
  }
  \item{freq}{
    1 = yearly, 12 = monthly, 4 = seasonal ...
  }
  \item{msk95lev}{
    TRUE/FALSE grid points with dots if 95\% significance level reached. 
    Default = FALSE
  }
  \item{brks}{
    Limits of colour levels, optional. For example:
    seq(min(var), max(var), (max(var) - min(var)) / 10)
  }
  \item{cols}{
    Vector of colours of length(brks) - 1, optional.
  }
  \item{filled.continents}{
    Continents filled in grey (TRUE) or represented by a black line (FALSE).
    Default = TRUE.
    Filling unavailable if crossing Greenwich and equi = TRUE.
    Filling unavailable if square = FALSE and equi = TRUE.
  }
  \item{lonmin}{
    Westward limit of the domain to plot (> 0 or < 0).
    Default : 0 degrees
  }
  \item{lonmax}{
    Eastward limit of the domain to plot (> 0 or < 0).
    lonmax > lonmin. Default : 360 degrees
  }
  \item{latmin}{
    Southward limit of the domain to plot. Default : -90 degrees
  }
  \item{latmax}{
    Northward limit of the domain to plot. Default : 90 degrees
  }
  \item{intlat}{
    Interval between latitude ticks on y-axis for equi = TRUE 
    or between latitude circles for equi = FALSE. Default = 30 degrees.
  }
  \item{intlon}{
    Interval between longitude ticks on x-axis. Default = 20 degrees.
  }
  \item{drawleg}{
    Draw a colorbar. Can be FALSE only if square = FALSE or equi = FALSE.
    Default = TRUE
  }
  \item{subsampleg}{
    Supsampling factor of the interval between ticks on colorbar.
    Default = 1 = every colour level.
  }
  \item{colNA}{
    Color used to represent NA. Default = 'white'
  }
  \item{equi}{
    TRUE/FALSE == cylindrical equidistant/stereographic projection. 
    Default: TRUE
  }
  \item{fileout}{
    c('', '', \dots) array of output file name for each animation. 
    If RMS, RMSSS, correlations : first exp with successive obs, then second exp 
    with successive obs, etc ...
  }
}
\details{
  Examples of input:
  ------------------

  1- Outputs from clim (exp, obs, memb = FALSE):
           (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 = TRUE)
                    & mean1dim(var, posdim = 3, narm = TRUE)
  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.
}
\examples{
  startDates <- c('19851101','19901101', '19951101', '20001101','20051101')
  sampleData <- Load('tos', c('i00k'), c('ERSST'), startDates, nleadtime = 124,
                     leadtimemin = 1, leadtimemax = 60, output = 'lonlat',
                     latmin = 30, latmax = 45, lonmin = 0, lonmax = 40)
  clim <- Clim(sampleData$mod, sampleData$obs, memb = FALSE)
  AnimVsLTime(clim$clim_exp, sampleData$lon, sampleData$lat,
    toptitle = "climatology CMIP5 decadal prediction", sizetit = 1, 
    units = "degree", brks = seq(270, 300, 3), monini = 11, freq = 12, 
    msk95lev = FALSE, filled.continents = TRUE, intlon = 10, intlat = 10,
    fileout = 'clim_IC3_CMIP5_dec.gif')

  ano_exp <- Ano(sampleData$mod, clim$clim_exp)
  ano_obs <- Ano(sampleData$obs, clim$clim_obs)
  leadtimes_dimension <- 4
  initial_month <- 11
  mean_start_month <- 1
  mean_stop_month <- 12
  season_means_mod <- Season(ano_exp, leadtimes_dimension, initial_month,
                             mean_start_month, mean_stop_month)
  season_means_obs <- Season(ano_obs, leadtimes_dimension, initial_month,
                             mean_start_month, mean_stop_month)
  AnimVsLTime(Mean1Dim(season_means_mod, 2)[1,1,,,], sampleData$lon,
    sampleData$lat, toptitle = "Annual anomalies 1985 CMIP5 IC3 prediction",
    sizetit = 1, units = "degree", monini = 1, freq = 1, msk95lev = FALSE,
    brks = seq(-0.5, 0.5, 0.1), intlon = 10, intlat = 10,
    filled.continents = TRUE, fileout = 'annual_means_IC3_CMIP5_dec.gif')

  dim_to_mean <- 2  # Mean along members
  rms <- RMS(Mean1Dim(season_means_mod, dim_to_mean),
             Mean1Dim(season_means_obs, dim_to_mean))
  AnimVsLTime(rms, sampleData$lon, sampleData$lat, toptitle =
    "RMSE CMIP5 IC3 decadal prediction", sizetit = 1, units = "degree",
    monini = 1, freq = 1, msk95lev = FALSE, brks = seq(0, 0.8, 0.08),
    intlon = 10, intlat = 10, filled.continents = TRUE,
    fileout = 'rmse_IC3_CMIP5_dec.gif')
}
\author{
  History:
  1.0  -  2012-04  (V. Guemas, \email{virginie.guemas at bsc.es})  -  Original code
  1.1  -  2014-04  (N. Manubens, \email{nicolau.manubens at bsc.es}) - Formatting to CRAN
  1.2  -  2015-05  (V. Guemas, \email{virginie.guemas at bsc.es})  - Use of PlotEquiMap and PlotStereoMap
}
\keyword{dynamic}
