Euro-Atlantic 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 Euro-Atlantic 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 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 sea level pressure (psl): this has been selected as the circulation variable for measuring teleconnections; however, other variables such as geopotential at 500 hPa 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('psl', 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 psl data (in Pa), stored in an array (`data$obs`). The first DJF period loaded is between 1981-1982 and the last one between 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 Euro-Atlantic domain (by setting arguments `latmin`, `latmax`, `lonmin` and `lonmax`), since the function measuring teleconnections will already select it internally. However, it is recommended to load data only for the Euro-Atlantic domain, because it takes much less computational time than loading it for the whole world.

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

- Average monthly psl 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)
```

- Measure DJF anomalies with the `Ano()` function as the difference between average DJF psl 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 psl anomalies with format [year, lat, lon], which will be used as input array for the EOF analysis.

### 4- Rotated teleconnections

Function `EuroAtlanticTC()` performs the principal component analysis for the Euro-Atlantic region, truncates the EOFs to a number specified by the user in option `ntrunc` and rotates the EOFs, selecting only the first four EOFs. A detailed explanation of this function is provided below.

- First, it selects only the psl 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 `varim()` 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 Euro-Atlantic teleconnection patterns, two functions are provided: `CorrPatterns()` and `RegPatterns()`. The first one plots the patterns generated by projecting the teleconnection indexes on the psl 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 Euro-Atlantic teleconnections, projected with the correlation methods.








<img src="figure.png" />
