Visualisation
=============

s2dverification contains a set of functions to plot data at every stage of the 
verification process, most based directly on R graphics plotting tools.
These functions are essential to:
 - Quickly inspect the results of a newly produced experiment, i.e. to check 
the physical consistency of the results.
 - Assess the added value of a new prediction system, i.e. to compare new 
results with a reference (observation, reconstruction or other experiment).
 - Assess visually the significance of results, i.e. to display in a 
user-friendly way confidence intervals and other statistics.

The visualisation functions, most with a name following the pattern 
`Plot*()`, can be grouped as a function of the kind of plot they provide: 
 - [**Plotting time series**](#time_series): `PlotClim()`, `PlotAno()`, 
`PlotVsLtime()`, `Plot2VarsVsLTime()` and `PlotACC()`.
 - [**Plotting maps**](#maps): `PlotEquiMap()`, 
`PlotStereoMap()`, `AnimVsLTime()`, `PlotSection()`.

To master these functions it is convenient to have in mind the common array 
dimension structure used throughout in s2dverification and how it evolves as 
the data objects go through the statistics and verification stages. For that 
you can review the introduction in [**Data retrieval**](data_retrieval.md) and 
the sections [**Statistics**](statistics.md) and 
[**Verification**](verification.md).

Next an explanation of which situations they fit the best, details of the 
options they provide and short examples of usage. The data used hereunder will
be the same as in [**Data retrieval**](data_retrieval.md):
```r
library(s2dverification)
expA <- list(name = 'experimentA',
             path = file.path('/path/to/experiments/$EXP_NAME$/monthly_mean',
                              '$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc'))
expB <- list(name = 'experimentB',
             path = file.path('/path/to/experiments/$EXP_NAME$/monthly_mean',
                              '$VAR_NAME$/$VAR_NAME$_$START_DATE$.nc'))
obsX <- list(name = 'observationX',
             path = file.path('/path/to/observations/$OBS_NAME$/monthly_mean',
                              '$VAR_NAME$/$VAR_NAME$_$YEAR$$MONTH$.nc'))
sdates <- paste0(1991:2000, '1101')
data <- Load('tas', list(expA, expB), list(obsX),
             sdates = sdates,
             leadtimemin = 2, leadtimemax = 13,
             latmin = -10, latmax = 60,
             lonmin = 100, lonmax = 250,
             output = 'areave', grid = 't106grid',
             method = 'distance-weighted')
ano <- Ano_CrossValid(data$mod, data$obs, memb = FALSE)
```

Plotting time series<a name="time_series"></a>
--------------------

All the functions devoted to plotting time series have some common traits and
parameters:
 - Aimed to plot monthly, seasonal or yearly time series, adjustable via the 
parameter `freq`.
 - All of them generate plots and save them to PostScript files the path and 
file name of which you have to provide to the `fileout` parameter. Can plot in
a presentation oriented style or in a paper oriented style, adjustable with the
parameter `biglab`.
 - Can plot a legend automatically, adjustable via the parameters `leg`, 
`listexp` and `listobs`/`listvar` in `PlotVsLTime()`, `Plot2VarVsLtime()` and 
`PlotClim()` or via the parameter `legends` in `PlotAno()` and `PlotACC()`.
 - Accept any additional parameters via the parameter `...` to be sent to 
the underlying R graphics `plot()` function for a fine tuning.

### Plotting climatologies

`PlotClim()` takes as inputs an experimental and an observational array of 2 
to 3 dimensions each:
```r
  c(n. of datasets, n. of members, n. of lead-times)
```
the second one being optional. This means that the latitude and longitude 
dimensions must have been removed either because working on area-averages or
because working on a single grid point and that the starting dates dimension
must have also been removed either because willing to plot data of a single
starting date or because working on averages across starting dates, i.e. 
climatologies (see [**Statistics**](statistics.md)).

A curve is plotted for each member of each experiment or observation. The 
members of a same experiment or observation are equally coloured whereas the 
different experiments and observations are plotted with different colours.  
`PlotClim()` assumes by default that the provided climatologies start in 
January. Otherwise the initial month can be specified with the parameter 
`monini`:

```r
clim <- Clim(data$mod, data$obs)
PlotClim(clim$clim_exp, clim$clim_obs, monini = 12,
         toptitle = "Per-pair 'tas' climatologies over North Pacific region.",
         ytitle = "K",
         listexp = c('Experiment A', 'Experiment B'),
         listobs = c('Observation X'),
         fileout = "vis_clim_expA_expB_obsX.eps")
```
<img src="vis_clim_expA_expB_obsX.png" width="600" />

### Plotting multi-member raw data or anomalies

`PlotAno()` takes also two data arrays as inputs with 4 dimensions each:
```r
  c(n. of datasets, n. of members, n. of starting dates, n. of lead-times)
```
all being mandatory. It means that if willing to plot single member data or
data from a single starting date, the corresponding dimensions still have to
be present in the provided arrays; `InsertDim()` helps in that.

The data in the provided arrays can be raw data, anomalies or any other kind
of data, as long as it is arranged with the required dimensions.  
For each run of a model (i.e. for each group of members of a same starting 
date from one experiment) a thick curve with the ensemble mean is plotted 
together with a finer curve for each ensemble member, unless any of these are 
disabled with `ensmean` or `memb`, respectively. The area delimited by the 
minimum and maximum ensemble values at each forecast time is filled in with a 
different colour for each starting date, unless disabled with `fill`.  
A fine black curve is plotted with the observational data alongside each 
starting date.  
A separate new plot is created for each experimental dataset provided in the
experimental data array.

The starting dates the provided data corresponds to must be provided with the
parameter `sdates` for them to be plotted accordingly along the x axis. 

`linezero` draws a line at y = 0 to help perceiving whether the anomaly is 
positive or negative, `vlines` draws vertical lines at any specified abscissae
and `points` will draw all the curves in pointed style.

```r
sdates <- paste0(1991:2000, '1101')
selected_sdates <- gsub('1101', '1201', sdates)
PlotAno(data$mod, data$obs, selected_sdates,
        toptitle = paste0(c("Experiment A", "Experiment B"),
                          ": Raw 'tas' over North Pacific region."),
        ytitle = c("K", "K"),
        fileout = paste0("vis_raw_exp", c("A", "B"), "_obsX.eps"))
```
<img src="vis_raw_expA_obsX.png" width="600" />
<img src="vis_raw_expB_obsX.png" width="600" />

### Plotting statistics and scores

The functions `PlotVsLTime()`, `Plot2VarsVsLTime()` and `PlotACC()` serve to
plot time series of variables obtained with the 
[**Statistics**](statistics.md) or [**Verification**](verification) modules 
that yield forecast time series of indices or scores that usually come 
together with confidence intervals and significance levels.

`PlotVsLTime()` takes as main input an array of data with the following 
dimensions:
```r
  c(n. of experiments, n. of observational datasets, 3 or 4, n. of lead-times)
```
the second one being optional and the third one corresponding to the lower 
limit of a confidence interval, the measurement or index or score, the upper
limit of a confidence interval and, optionally, a significance level. This
dimension format requires that the index or score to be plotted is computed
along the actual time (starting dates) and over the average of the ensemble 
members, either at a single grid point or from an area average.

A curve is drawn for each pair of (experiment, observation) with a different 
colour and line style. The scores or indices that correspond to a same 
experiment are coloured equally but a different line style is used for each 
observation that experiment has been compared to when computing the index or 
score. The confidence intervals are plotted with a finer line of the same
colour and line style, unless disabled with `show_conf`. To plot the 
signification level instead the parameter `siglev` can be set to `TRUE`.

As in `PlotClim()`, each curve is defined along the forecast times and is
assumed to start at January. Otherwise it can be adjusted via `monini`. 
Additionally the number of ticks along the x axis can be adjusted with 
`nticks` and any number of horizontal lines can be drawn by specifying the 
target ordinates to `hlines`. 

`PlotVsLTime()` can be useful in the following situations:
 - To plot `Trend()` or `Regression()` fitted coefficients of ensemble averages 
of data at a single grid cell or averaged over a region:

```r
trend_exp <- Trend(Mean1Dim(ano$ano_exp, 2))
trend_obs <- Trend(Mean1Dim(ano$ano_obs, 2))
PlotVsLTime(trend_exp$trend,
            toptitle = "Slopes of trends of 'tas' over North Pacific region",
            ytitle = "K/year",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_trend_expA_expB.eps')
```
```r
ano_expA_Y <- Regression(Mean1Dim(plyr::take(ano$ano_exp, 1, 1), 2),
                         Mean1Dim(plyr::take(ano$ano_exp, 1, 2), 2))
PlotVsLTime(ano_expA_Y$regression,
            toptitle = "Slopes of regression of exp. A with exp. B, over North Pacific region",
            ytitle = "K/year",
            monini = 12, freq = 1, leg = FALSE,
            fileout = 'vis_regression_expA_expB.eps')
```
<img src="vis_trend_expA_expB.png" width="600" />
<img src="vis_regression_expA_expB.png" width="600" />
 - To plot the `Spread()` across ensemble members and starting dates of area 
averaged data (interquartile range, maximum minus minimum, standard deviation
or median absolute deviation):

```r
spread <- Spread(ano$ano_exp, posdim = c(2, 3))
PlotVsLTime(spread$iqr,
            toptitle = "IQR across members and starting dates over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_iqr_expA_expB.eps')
PlotVsLTime(spread$maxmin,
            toptitle = "Max. - min. across members and starting dates over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_maxmin_expA_expB.eps')
PlotVsLTime(spread$sd,
            toptitle = "S. deviation across members and starting dates over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_sd_expA_expB.eps')
PlotVsLTime(spread$iqr,
            toptitle = "MAD across members and starting dates over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_mad_expA_expB.eps')
```
<img src="vis_iqr_expA_expB.png" width="600" />
<img src="vis_maxmin_expA_expB.png" width="600" />
<img src="vis_sd_expA_expB.png" width="600" />
<img src="vis_mad_expA_expB.png" width="600" />
 - To plot the correlation (`Corr()`) and RMSE (`RMS()`) between experiments 
(averaged across ensemble members) and observations:

```r
corr <- Corr(Mean1Dim(ano$ano_exp, 2), Mean1Dim(ano$ano_obs, 2))
PlotVsLTime(corr,
            toptitle = "Time correlation with observation X, over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_corr_expA_expB_obsX.eps')
```
```r
rms <- RMS(Mean1Dim(ano$ano_exp, 2), Mean1Dim(ano$ano_obs, 2))
PlotVsLTime(rms,
            toptitle = "RMSE with observation X, over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_rms_expA_expB_obsX.eps')
```
<img src="vis_corr_expA_expB_obsX.png" width="600" />
<img src="vis_rms_expA_expB_obsX.png" width="600" />
 - To plot the ratio between the RMSE of the ensemble mean of two experiments 
with a same observation at a single grid point or area averaged:

```r
ratio_rms <- RatioRMS(Mean1Dim(ano$ano_exp[1, , , ], 1),
                      Mean1Dim(ano$ano_exp[2, , , ], 1),
                      ano$ano_obs[1, 1, , ])
ratio_rms2 <- array(dim = c(1, 4, dim(ratio_rms)[2]))
ratio_rms2[1, c(2, 4), ] <- ratio_rms
PlotVsLTime(ratio_rms2,
            toptitle = "RMSE of exp. A / RMSE of exp. B (against obs. X), over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1, siglev = TRUE, leg = FALSE,
            fileout = 'vis_ratiorms_expA_expB_obsX.eps')
```
<img src="vis_ratiorms_expA_expB_obsX.png" width="600" />
 - To plot the ratio between the ensemble spread of the experiments and their 
RMSE against the observations (`RatioSDRMS()`) at a single grid point or area
averaged:

```r
ratio_sdrms <- RatioSDRMS(ano$ano_exp, ano$ano_obs)
ratio_sdrms2 <- array(dim = c(dim(ratio_sdrms)[1:2], 4, dim(ratio_sdrms)[4]))
ratio_sdrms2[, , c(2, 4), ] <- ratio_sdrms
PlotVsLTime(ratio_sdrms2,
            toptitle = "S. dev. over members and s. dates / RMSE, over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1, siglev = TRUE,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_ratiosdrms_expA_expB_obsX.eps')
```
<img src="vis_ratiosdrms_expA_expB_obsX.png" width="600" />

In this example, the ratio SD / RMS is calculated for the experiment A only 
but against two observational datasets:

```r
ratio_sdrms <- RatioSDRMS(plyr::take(ano$ano_exp, 1, 1),
                          abind::abind(ano$ano_obs, 
                                       ano$ano_obs + rnorm(length(ano$ano_obs), 0, 0.1), 
                                       along = 1))
ratio_sdrms2 <- array(dim = c(dim(ratio_sdrms)[1:2], 4, dim(ratio_sdrms)[4]))
ratio_sdrms2[, , c(2, 4), ] <- ratio_sdrms
PlotVsLTime(ratio_sdrms2,
            toptitle = "S. dev. over members and s. dates / RMSE, over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1, siglev = TRUE,
            listexp = c('Experiment A'),
            listobs = c('Observation X', 'Observation X + rnorm(n, 0, 0.1)'),
            fileout = 'vis_ratiosdrms_expA_obsX_obsXrnorm.eps')
```
<img src="vis_ratiosdrms_expA_obsX_obsXrnorm.png" width="600" />
 - To plot `RMSSS()` of ensemble mean at a single grid point or area averaged:

```r
rmsss <- RMSSS(Mean1Dim(ano$ano_exp, 2), Mean1Dim(ano$ano_obs, 2))
rmsss2 <- array(dim = c(dim(rmsss)[1:2], 4, dim(rmsss)[4]))
rmsss2[, , c(2, 4), ] <- rmsss
PlotVsLTime(rmsss2,
            toptitle = "RMSSS with observation X, over North Pacific region",
            ytitle = "K",
            monini = 12, freq = 1, siglev = TRUE,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_rmsss_expA_expB_obsX.eps')
```
<img src="vis_rmsss_expA_expB_obsX.png" width="600" />
 - To plot effective number of independent data (`Eno()`):

```r
eno <- Eno(Mean1Dim(ano$ano_exp, 2), posdim = 2)
eno2 <- array(dim = c(dim(eno)[1], 4, dim(eno)[2]))
eno2[, 2, ] <- eno
PlotVsLTime(eno2,
            toptitle = "Eff. n. of independent data, over North Pacific region",
            monini = 12, freq = 1, siglev = FALSE, show_conf = FALSE,
            listexp = c('Experiment A', 'Experiment B'),
            fileout = 'vis_eno_expA_expB.eps')
``` 
<img src="vis_eno_expA_expB.png" width="600" />

`Plot2VarsVsLTime()` allows to plot two indices or scores at a time on the same
plot, each with its confidence intervals. It accepts as inputs arrays of only 
3 dimensions:
```r
  c(n. of experiments, 3/4, n. of lead-times)
```
i.e., it accepts only indices or scores from a set of experimental datasets 
against a single observation.
Its options are identical to the ones of `PlotVsLTime()` except that the 
parameter for specifying legends for observations (`listobs`) is replaced by a 
parameter to put a legend to distinguish the plotted variables, `listvars`.
```
Plot2VarsVsLTime(corr[, 1, 1:3, ], rms[, 1, , ],
                 toptitle = "Time corr. and RMSE with observation X, over North Pacific region",
                 ytitle = "K",
                 monini = 12, freq = 1,
                 listexp = c('Experiment A', 'Experiment B'),
                 listvars = c('Corr', 'RMSE'),
                 fileout = 'vis_corr_rms_expA_expB_obsX.eps')
```
<img src="vis_corr_rms_expA_expB_obsX.png" width="600" />

`PlotACC()`, in contrast to `PlotVsLTime()`, accepts an additional dimension
for the starting dates in the input and the dimension of the confidence 
intervals is positioned at the end in place of the latitudes and longitudes, 
as provided by `ACC()`:
```r
  c(n. of experiments, n. of observational datasets, n. of starting dates, n. of lead-times, 4)
```
The ACCs and confidence intervals of all forecast times and starting dates of 
all experiments are plotted. In contrast to `PlotAno()`, the consecutive 
starting dates are overlapped so as to make it easy to compare their behaviour
overall.

All the starting dates of an experiment are painted with the same colour. 
There are two possible styles, switchable via the parameter `points`:
 - Drawing curves along forecast times, as in `PlotVsLTime()`. In that case 
`fill` can enable filling the area limited by the confidence intervals.
 - Drawing a point for each forecast time, with vertical lines joined to the
extremes of the confidence interval, limited with notches (default).
Besides, `linezero` draws a line at ordinate 0 and `vlines` draws vertical
lines at any specified set of abscissae.

```r
map_data <- Load('tas', list(expA, expB), list(obsX),
                 sdates = sdates,
                 leadtimemin = 2, leadtimemax = 13,
                 latmin = -30, latmax = 60,
                 lonmin = -90, lonmax = 20,
                 output = 'lonlat', grid = 't106grid',
                 method = 'distance-weighted')
ano <- Ano_CrossValid(map_data$mod, map_data$obs, memb = FALSE)
acc <- ACC(ano$ano_exp, ano$ano_obs)
PlotACC(acc$ACC, selected_sdates, 
        toptitle = "Spatial anom. corr. coeff. with obs X over Atlantic region",
        ytitle = "K", freq = 1,
        legends = c('Experiment A', 'Experiment B'),
        fileout = 'vis_acc_expA_expB_obsX.eps')
```
<img src="vis_acc_expA_expB_obsX.png" width="600" />

Plotting maps<a name="maps"></a>
-------------

This group of functions allows to plot grid data (i.e. defined over latitudes 
and longitudes) on a rectangular equidistant projection or on a stereographic 
projection (as of s2dverification v2.5.0) as well as depth sections (i.e. 
defined over latitudes/longitudes and depth levels).

Regarding the functions to plot maps, by default each grid point is drawn on a 
world map with a colour as a function of the magnitude of the provided field, 
index or score at that point. While `PlotEquiMap()` and `PlotStereoMap()` plot 
data of a single forecast time, `AnimVsLTime()` creates an animation with the 
plotted maps of all lead-times obtained with one of the previous functions at 
choice.

`PlotEquiMap()` and `PlotStereoMap()` share some traits:
 - Both expect a data matrix in the parameter `var` of dimensions 
`c(n. of latitudes, n. of longitudes)`, `lat` with a vector with the latitudes 
of the centers of the grid cells and `lon`, a vector with the longitudes. 
`Load()` already provides these in the correct format, through the components 
`$lon` and `$lat`.
 - The N colours to paint the grid cells with (via `cols`) as well as the N +
1 threshold magnitudes (via `brks`) that will allow to assign each grid cell 
value one of the N colours. The colour for any missing values can be adjusted 
with `colNA`.
 - Whether to fill the map continents or only draw coast wires can be adjusted
with `filled.continents`.
 - A matrix of `dots` can be plotted over the drawn map to, e.g., highlight 
cells where a skill has been greatest or most significant.
 - A legend can be drawn (unless disabled with `drawleg`) and the amount of 
ticks on that legend can be adjusted with `subsampleg`.
 - They accept any additional parameters via the parameter `...` to be sent to
the underlying R graphics `image()` function for a fine tuning.

### PlotEquiMap()

Next some examples of maps obtained with `PlotEquiMap()`:
```r
png('vis_equimap_raw_expA.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$mod, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Exp. A: 'tas' over Atlantic; s. date: 1990-11-01, l.-time: 1 month.", 
            units = "K")
dev.off()

png('vis_equimap_raw_obsX.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$obs, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Obs. X: 'tas' over Atlantic, 1990-12-01.", 
            units = "K", filled.continents = FALSE)
dev.off()
```
<img src="vis_equimap_raw_expA.png" width="600" />
<img src="vis_equimap_raw_obsX.png" width="600" />

```r
cols <- clim.colors(50)

data_min <- min(map_data$mod, map_data$obs, na.rm = TRUE)
data_max <- max(map_data$mod, map_data$obs, na.rm = TRUE)
brks <- round(seq(data_min, data_max, length.out = length(cols) + 1), 2)

png('vis_equimap_cols_raw_expA.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$mod, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Exp. A 'tas', s. date: 1990-11-01, l.-time: 1 month.", 
            units = "K", brks = brks, cols = cols, subsampleg = 5)
dev.off()

png('vis_equimap_cols_raw_obsX.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$obs, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Obs. X 'tas', 1990-12-01.", 
            units = "K", brks = brks, cols = cols, subsampleg = 5,
            filled.continents = FALSE)
dev.off()
```
<img src="vis_equimap_cols_raw_expA.png" width="600" />
<img src="vis_equimap_cols_raw_obsX.png" width="600" />


Or, as seen in the example from [**Snippet 2**](snippets.md#snippet2):<a name="snippet2"></a>

<img src="snip2_equimap_corr_raw_expA_obsX.png" width="600" />
<img src="snip2_equimap_corr_raw_expB_obsX.png" width="600" />


`PlotEquiMap()` has some other additional features:
 - Drawing contour lines: `square` allows to smooth the borders of each 
coloured region and draws contour lines and figures. The contours can be 
adjusted by providing a matrix to `contours` with dimensions 
`c(n. of longitudes, n. of latitudes)`. The contours of the data in that 
matrix will be drawn over the map, using the thresholds provided in `brks2`.
This is useful to plot the contours of the original data without border 
smoothing, to plot only some of the default contours or to plot other contours 
defined by another field.  

```r
png('vis_equimap_contour_raw_expA.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$mod, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Exp. A 'tas', s. date: 1990-11-01, l.-time: 1 month.", 
            units = "K", brks = brks, cols = cols, subsampleg = 5, square = FALSE)
dev.off()

png('vis_equimap_contour_raw_obsX.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$obs, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Obs. X 'tas', 1990-12-01.", 
            units = "K", brks = brks, cols = cols, subsampleg = 5, square = FALSE)
dev.off()
```

<img src="vis_equimap_contour_raw_expA.png" width="600" />
<img src="vis_equimap_contour_raw_obsX.png" width="600" />

 - Drawing boxes on the map: `boxlim`, `boxcol` and `boxlwd` allow to 
specify the position of the corners, colour and thickness of a box to be drawn 
on the map. 

```r
png('vis_equimap_box_expA.png', width = 800, height = 600)
PlotEquiMap(Mean1Dim(map_data$obs, 2)[1, 1, 1, , ], map_data$lon, map_data$lat,
            toptitle = "Obs. X 'tas', 1990-12-01.", 
            units = "K", brks = brks, cols = cols, subsampleg = 5, 
            boxlim = c(-62, -22, -23, 15))
dev.off()
```

<img src="vis_equimap_box_expA.png" width="600" />

 - Ticks on the longitude/latitude axes can be adjusted with `axelab`, `labW`, 
`intylat` and `intxlon`.
 - `numbfig` allows to specify the number of figures in the final layout in 
order to adjust some spacing parameters.

### PlotStereoMap()

`PlotStereoMap()` can be called almost identically to `PlotEquiMap()`, except
that it requires the `latlims` parameter to specify which range of latitudes to
be plotted on the stereographic projection map.  
The only special parameter is the `intlat`, to set the interval in degrees 
between consecutive latitude circles on the plot.

Next a couple of examples:

```r
## Loading data over the entire globe
world_data <- Load('tas', list(expA, expB), list(obsX),
                    sdates = sdates[1],
                    leadtimemin = 2, leadtimemax = 13,
                    latmin = -90, latmax = 90,
                    lonmin = 0, lonmax = 360,
                    output = 'lonlat', grid = 't106grid',
                    method = 'distance-weighted')
png('vis_stereomap_raw_expA.png', width = 800, height = 600)
PlotStereoMap(Mean1Dim(world_data$mod, 2)[1, 1, 1, , ], 
              world_data$lon, world_data$lat, c(40, 90),
              cols = cols, brks = brks, subsampleg = 5,
              toptitle = "Exp. A 'tas', s. date: 1990-11-01, l.-time: 1 month.",
              units = "K", filled.continents = TRUE)
dev.off()

png('vis_stereomap_raw_obsX.png', width = 800, height = 600)
PlotStereoMap(Mean1Dim(world_data$obs, 2)[1, 1, 1, , ], 
              world_data$lon, world_data$lat, c(-90, -60), intlat = 10, 
              cols = cols, brks = brks, subsampleg = 5,
              toptitle = "Obs. X 'tas', 1990-12-01.",
              units = "K")
dev.off()
```

<img src="vis_stereomap_raw_expA.png" width="600" />
<img src="vis_stereomap_raw_obsX.png" width="600" />

### AnimVsLTime()

`AnimVsLTime()` generates animations of maps from `PlotEquiMap()` or 
`PlotStereoMap()` and saves them in GIF files at the paths specified in the
parameter `fileout`. It receives as main parameter, similarly as 
`PlotVsLTimes()`, an array with the dimensions:
```r
  c(n. of experiments/observations, n. of observations, 3, n. of lead-times, n. of latitudes, n. of longitudes)
```
the first 3 being optional and the 3rd dimension corresponding to the lower 
confidence interval, the actual value and the upper confidence interval. This 
means it can plot maps of a field of one or multiple experimental or 
observational datasets, averaged across ensemble members and starting dates 
(climatologies) or indices or scores computed across starting dates against 
one or more observations. The confidence intervals, if provided, are used to 
draw black dots on grid cells that reach a 95% significance level, if 
requested via `msk95lev`.

The provided data is assumed to be in a monthly frequency and to start at 
January. Otherwise it can be adjusted with `monini` and `freq`.

Whether to plot with a equidistant rectangular projection or a stereographic 
projection can be chosen with the parameter `equi`. The plot can be limited to 
a sub-region of the provided data via the parameters `lonmin`, `lonmax`, 
`latmin` and `latmax`.

`AnimVsLTime()` allows for the typical adjustments in the map plotting 
functions: specifying the palette colors and breaks (`col` and `brk`),
displaying or not a legend (`drawleg`, `subsampleg`), selecting a color for
the NA values (`colNA`) and filling or not the continents 
(`filled.continents`).

Further title and axis tick adjustments can be achieved with `toptitle`, 
`sizetit`, `units`, `intlon` and `intlat`.
brk col drawleg subsampleg colNA filled.continents

Next a few examples:

```r
map_clim <- Clim(map_data$mod, map_data$obs, memb = FALSE)
AnimVsLTime(map_clim$clim_exp, map_data$lon, map_data$lat, monini = 12, 
            toptitle = c("Exp. A climatologies.", "Exp. B climatologies"), 
            units = "K", brk = brks, col = cols, subsampleg = 5,
            fileout = c("vis_anim_clim_expA", "vis_anim_clim_expB"))
AnimVsLTime(map_clim$clim_obs, map_data$lon, map_data$lat, monini = 12, 
            toptitle = "Obs. X climatologies.", units = "K",
            brk = brks, col = cols, subsampleg = 5,
            fileout = 'vis_anim_clim_obsX')
```

<img src="vis_anim_clim_expA.gif" width="600" />
<img src="vis_anim_clim_expB.gif" width="600" />
<img src="vis_anim_clim_obsX.gif" width="600" />

```r
world_clim <- Clim(world_data$mod, world_data$obs, memb = FALSE)
AnimVsLTime(plyr::take(world_clim$clim_exp, 1, 1), world_data$lon, world_data$lat, 
            filled.continents = FALSE, monini = 12,
            toptitle = "Exp. A climatologies.", units = "K",
            brk = brks, col = cols, subsampleg = 5,
            fileout = 'vis_anim_clim_expA_world')
AnimVsLTime(world_clim$clim_obs, world_data$lon, world_data$lat, 
            equi = FALSE, monini = 12, 
            toptitle = "Obs. X climatologies.", units = "K",
            brk = brks, col = cols, subsampleg = 5,
            fileout = 'vis_anim_clim_obsX_world')
```


And, as seen in [**Snippet 2**](snippets.md#snippet2), the animations of the 
actual time correlations of Experiment A and B against Observation X over the 
Atlantic, with black dots on values that reach a 95% significance level:

<img src="snip2_anim_corr_expA_obsX.gif" width="600" />
<img src="snip2_anim_corr_expB_obsX.gif" width="600" />

### PlotSection()


