Euro-Atlantic teleconnections
=============================

s2dverification contains a function, "EuroAtlantic_TC" to compute Euro-Atlantic teleconnection indexes with the Varimax rotation. To this end, the following steps are required:

### 1- Install and load s2dverification package (the version including the teleconnection function) inside an R session with commands:

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

You can also read the s2dverification guide available [*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 `EuroAtlantic_TC()` 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. 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.

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

`EuroAtlantic_TC()` returns a list with 4 variables: the rotated EOFs (`telec$REOFs`) and PCs (`telec$RPCs`), 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: `getCorPatterns()` and `getRegPatterns()`. The first one plot 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
getCorPatterns(ano = anom, lat = data$lat, lon = data$lon, PCs = telec$RPCs[,1:4], show = TRUE)
getRegPatterns(anom, lat, lon, test$RPCs[,1:4], nrow=4, ncol=1, show = TRUE)

```
The number of teleconnection indexes to plot is set by the argument `PCs`, which in this case takes as input the first four rotated PCs. Option `show` can be set to FALSE if you only want to store the values to plot and visualize them later.



<img src="observed_regimes.png" />
