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

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

### 1- Load s2dverification (the version including the teleconnection function) with command:

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

- Check the documentation which is available here:

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

### 2- Load data with the `Load ()` function included in the package. For a full description of `Load()` you can click [*here*] (https://earth.bsc.es/gitlab/es/s2dverification/blob/develop-vignettes/vignettes/data_retrieval.md).

The data employed in this example is described below.  
- 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
sdates <- paste0(1981:2015, '1201')
data <- Load('psl', exp = NULL,
             obs = 'NCEP',
             sdates = sdates,
             storefreq = 'monthly',
             leadtimemin = 1, leadtimemax = 3,
             latmin = 20, latmax = 80,
             lonmin = 270, lonmax = 60, output = 'lonlat')
```

Arguments `leadtimemin` and `leadtimemax` set the 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 falls between 1981-1982 and the last one between 2015-2016, so also data from 2016 is loaded.
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 reccommended to load data only 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(pslFull$obs, 4)
```

- DJF climatology is computed averaging '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 the climatology:

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

### 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 finally 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) with the `varim()` function.

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

`REOF()` returns a list with 4 variables: the rotated EOFs (`REOFs`) and PCs (`RPCs`), the latitude weigths (`wgth`) and the variance explained by each PC (`var`)

### 5- Visualisation of the teleconnection patterns

To plot the pattern of each of the four Euro-Atlantic teleconnections, we have employed the `PlotLayout()` and `PlotEquiMap()` functions available in s2dverifcation. The object `WR_obs$composite` is divided by 100, just to reperesent the anomalies in hPa. 

 ```r
titles<-paste0('freq = ',round(WR_obs$frequency,1),'%')
PlotLayout(PlotEquiMap,c(1,2),lon=data$lon,lat=data$lat,var=WR_obs$composite/100,
           titles=paste0(paste0('Cluster ',1:4),' (',paste0('freq = ',round(WR_obs$frequency,1),'%'),' )'),filled.continents=F,
           axelab=F,draw_separators = T,subsampleg = 1,brks=seq(-16,16,by=2),
           bar_extra_labels = c(2,0,0,0),fileout='observed_regimes.png')
```

<img src="observed_regimes.png" />
