EuroAtlantic teleconnections
=============================

Four teleconnections that impact the EuroAtlantic climate have been described in the literature: North Atlantic Oscillation (NAO), East Atlantic (EA), East Atlantic/Western Russia (EA/WR) and Scandinavian pattern (SCAN).
Indices for those teleconnections are regularly published by CPC, but the methodology is not straightforward for using it with seasonal and subseasonal predictions. 
There are many ways to compute similar indices. 
s2dverification contains a function, "EuroAtlanticTC", that computes the EuroAtlantic teleconnection indices using a rotated EOF with a Varimax rotation over the EuroAtlantic region. 
This vignette details the steps to follow for using the function:

### 1- Install and load s2dverification package 

The branch that includes the teleconnection functions can be installed and loaded with commands:

```r
 devtools::install_git('https://earth.bsc.es/gitlab/es/s2dverification',
                       branch = 'develop-teleconnections')
                     
 library(s2dverification)
```

- The documentation of the package can be found here:

https://cran.r-project.org/web/packages/s2dverification/s2dverification.pdf

### 2- Load reanalysis data with the `Load()` function included in the package. 

The data employed in this example is described below. For a full description of `Load()` you can click [*here*] (https://earth.bsc.es/gitlab/es/s2dverification/blob/develop-vignettes/vignettes/data_retrieval.md).

- Variable: mean monthly geopotential at 500 hPa (g500): this has been selected as the circulation variable for measuring teleconnections; however, other variables such as sea level pressure can be also used.
- Datasets: NCEP reanalysis ([**Kalnay et al. 1996**](https://rda.ucar.edu/datasets/ds090.0/docs/bams/bams1996mar/bamspapr-bm.pdf)) as a reference dataset.
- Spatial Domain: traditional Euro-Atlantic domain [90ºW-60ºE; 20-80ºN]]
- Period: 1981-2015
- Season: DJF


```r
data <- Load('g500', exp = NULL,
             obs = 'ncep-reanalysis',
             sdates = paste0(1981:2015, '1201'),
             storefreq = 'monthly',
             leadtimemin = 1, leadtimemax = 3,
             latmin = 20, latmax = 80,
             lonmin = 270, lonmax = 60, output = 'lonlat')
```

Arguments `leadtimemin` and `leadtimemax` respectively set the min and max number of consecutive months to load, starting from the month specified in the `sdates` argument (December in this case).
The object returned by `Load()` contains the requested DJF g500 data, stored in an array (`data$obs`). The first DJF period loaded is 1981-1982 and the last is 2015-2016, so also data from 2016 is loaded even if the last year set is 2015.

Notice that in this step it is not strictly necessary to load only the EuroAtlantic domain (by setting arguments `latmin`, `latmax`, `lonmin` and `lonmax`), since the function measuring teleconnections will already subset the region internally. However, loading data only for the Euro-Atlantic domain takes much less computational time than loading it for the whole globe.

### 3- Compute DJF anomalies
DJF anomalies can be obtained by following these steps: 

- Average monthly g500 data over DJF with the `Mean1Dim()` function:

```r
data.DJF <- Mean1Dim(data$obs, 4)
```

- DJF climatology is computed averaging object `data.DJF` over all years:

```r
clim <- Mean1Dim(data.DJF, 3)
```

- Obtain DJF anomalies with the `Ano()` function as the difference between average DJF g500 and its monthly climatology:

```r
anom <- Ano(data.DJF, clim)
```

- Remove the first two unused dimensions (experiment number and members) in the `anom` array with the `drop()` function:

```r
anom <- drop(anom)
```

At the end of the preformatting, you should have a 3D array of mean DJF g500 anomalies with dimensions [year, lat, lon].

### 4- Get the teleconnection patterns and indices

Function `EuroAtlanticTC()` performs a principal component analysis for the EuroAtlantic region, truncates the EOFs to a number specified by the user in option `ntrunc` and rotates the EOFs using Varimax. The first four rotated EOFs are returned. A detailed explanation of this function is provided below.

- First, it selects only the g500 data inside spatial domain [90ºW-60ºE; 20-80ºN], if it was not selected previously in the loading step.
- Then, it calls function `REOF()` of s2dverification, which consists in two parts: the extraction of the principal components and their rotation.
- The first part of `REOF()` is a call to function `EOF()` of s2dverification. It was developed for extracting the principal components (PCs) without rotating them. `EOF()` also weights the anomalies by the square root of the cosine of the latitude, to give to each point equal weight, and returns the first `ntrunc` PCs and EOFs, discarding the others.
- In the second part of `REOF()`, it rotates the first `ntrunc` EOFs (loadings) provided by `EOF()` with the `varimax()` function. 
- Finally, EuroAtlanticTC() selects only the first four rotated EOFs, representing the main Euro-Atlantic teleconnections.

```r
telec <- EuroAtlanticTC(ano = anom, lon = data$lon, lat = data$lat, ntrunc = 30)
```

`EuroAtlanticTC()` returns a list with 4 variables: the rotated EOFs (`telec$patterns`) and PCs (`telec$indices`), the latitude weigths (`telec$wgth`) and the variance explained by each rotated PC (`telec$var`)

### 5- Visualisation of the teleconnection patterns

To plot the four main EuroAtlantic teleconnection patterns, two functions are provided: `CorrPatterns()` and `RegPatterns()`. The first one plots the patterns generated by projecting the teleconnection indexes on the g500 anomalies with the correlation method, and the second one with the regression method.


```r
CorrPatterns(ano = anom, lon = data$lon, lat = data$lat, PCs = telec$indices, nPCs = 4, show = TRUE, var = telec$var)
RegPatterns(ano = anom, lon = data$lon, lat = data$lat, PCs = telec$indices, nPCs = 4, show = TRUE, var= telec$var)

```
The number of teleconnection indexes to plot is specified by the argument `nPCs`. In this case, `nPCs` is set to 4, so it takes as input the first four rotated PCs passed in the `PCs` argument. Option `show` can be set to FALSE if you only want to compute the values to plot and visualize them later. You can also show the % of explained variance of each PC by passing it in the `var` argument.

Figure below shows the patterns of the four main EuroAtlantic teleconnections, projected with the correlation methods.








<img src="figure.png" />
