\name{PlotTimeSeries}
\alias{PlotTimeSeries}
\title{
Plots time series
}
\description{
Function for plotting time series, taking arrays or common data model (CDM) objects as input. Allows the user to group the data along any of the available dimensions. Calculates and plots the multi-member mean, shades between the minimum and maximum values for each start date and lead time, and plots curves of the invidividual members. The user can also plot confidence intervals and error bars.
}
\usage{
PlotClim(var, curves_along = NULL, points = FALSE, colour_along = NULL, style_along = NULL,
         mean_along = NULL, minmax_along = mean_along, shape_along = NULL, group_along = NULL, 
         interact_along = c(1,2,3), intercept = 0, interval_along = NULL, error_bar_along = NULL,  
         interval_type = 'errorbar', lower = 1, test = 2, upper = 3, x_axis_dim = NULL, 
         first_date = NULL, sdates = NULL, period = NULL, sdate_period = NULL, title = NULL, 
         xtitle = NULL, ytitle = NULL, ref_dimnames = .GetDimNames(), file_name = NULL, 
         file_path = NULL, file_width = NA, file_height = NA, file_size_units = 'in', add = FALSE)
}
\arguments{
  \item{var}{
A CDM dataset or array of model or observational data. The data is assumed to be in the format:\cr
c(dataset, member, sdate, ftime)
}
  \item{curves_along}{
The dimension along which the curves will be drawn, with the start date dimension (sdate) being used as the default.}
  \item{points}{
Whether or not points are to be plotted. By default points are plotted along the same dimension as the curves, unless shape_along is specified.
  }
  \item{colour_along = NULL}{
The dimension along which to colour the curves. The default is along the sdate dimension.
  }
  \item{style_along}{
The dimension along which to style the lines.
  }
  \item{mean_along}{
The dimension along which to plot the mean along. By default the means of all members are plotted for each start date and leadtime..
  }
  \item{minmax_along}{
The dimension along which to plot the minimum and maximum. By default the min/max of all members are plotted for each start date and leadtime.
  }
  \item{shape_along}{
The dimension along which to use different shapes for the points. 
  }
  \item{group_along}{
I cant remember what this one was for.
  }
   \item{interact_along}{
A vector of the dimensions along which the curves should be grouped.
  }
  \item{intercept}{
The intercept for the horizontal line. 
  }
  \item{interval_along}{
The dimension along which to plot the confidence interval.
  }
  \item{interval_type}{
The type of interval to be plotted.
  }
  \item{lower}{
The element of the interval_along dimension containing the lower confidence bound.
  }
  \item{test}{
The element of the interval_along dimension containing the test statistic.
  }
  \item{upper}{
The element of the interval_along dimension containing the upper confidence bound.
  }
  \item{x_axis_dim}{
The dimension specifying the x-axis. By default the function searches the CDM object for the start dates.
  }
  \item{first_date}{
The earliest start date in the data.
  }
  \item{sdates}{
A vector of start dates.
  }
  \item{period}{
The temporal range of the data.
  }
  \item{sdate_period}{
The temporal range of the start dates.
  }
  \item{title}{
The title of the plot.
  }  
  \item{xtitle}{
The x-axis label.
  }
  \item{ytitle}{
The y-axis label.
  }
}
\examples{
# Loading example data
library(s2dverification)
data_path <- system.file('sample_data', package = 's2dverification')
expA <- list(name = 'experiment', path = file.path(data_path, 
             'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly',
             '$VAR_NAME$_$START_DATE$.nc'))
obsX <- list(name = 'observation', path = file.path(data_path,
             '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$',
             '$VAR_NAME$_$YEAR$$MONTH$.nc'))

# Now we are ready to use Load().
startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
sampleData <- Load('tos', list(expA), list(obsX), startDates,
                   output = 'areave', latmin = 27, latmax = 48, 
                   lonmin = -12, lonmax = 40)

# Doing example calculations
clim <- Clim(sampleData$mod, sampleData$obs)
ano_exp <- Ano(sampleData$mod, clim$clim_exp)
ano_exp <- Smoothing(ano_exp)
ano_obs <- Ano(sampleData$obs, clim$clim_obs)
ano_obs <- Smoothing(ano_obs)

# Transforming to 'hypothetical' common data structure
ano_exp <- list(Data = ano_exp,
                Variable = sampleData$Variable,
                Datasets = sampleData$Datasets$exp,
                Dates = sampleData$Dates)
class(ano_exp) <- 'multiCDM'
ano_obs <- list(Data = ano_obs,
                Variable = sampleData$Variable,
                Datasets = sampleData$Datasets$obs,
                Dates = sampleData$Dates)
class(ano_obs) <- 'multiCDM'

PlotTimeSeries(ano_exp)
PlotTimeSeries(ano_exp) + PlotTimeSeries(ano_obs, add = T)
}
\author{
History:\cr
1.0  -  2016-10  (N. Manubens, \email{nicolau.manubens at bsc.es})  -  Original code\cr
1.0  -  2016-10  (A. Hunter, \email{alasdair.hunter at bsc.es})  -  Original code\cr
1.0  -  2016-10  (J. Giner, \email{julia.giner at bsc.es})  -  Original code
}
\keyword{datagen}
