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')
```
The object returned by `Load()` contains the requested DJF data from NCEP stored in an array (`data$obs`). Notice that the first DJF period loaded falls between 1981-1982 and the last one between 2015-2016.

### 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 `REOF()` performs the principal component analysis, truncate the EOFs to a number specified by the user in option `ntrunc`, and finally rotate the EOFs. A detailed explanation of this function is provided below.

- First, it call function EOF() of package s2dverification. EOF() is a function 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.
- EOF() returns the first `ntrunc` PCs, discarding the others.
- REOF()

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

`WeatherRegime()` provides a list with 6 elements (`$composite`, `$pvalue`, `$cluster`,`$center`, `$cluster_length`, `$cluster_values`, `$persistence` and `$frequency`) which are the needed parameters for the weather regimes assessment. Further details about the output provided by the `WeatherRegime()` function can be found in the package documentation (link WeatherRegime() documentation). 

### 5- Visualisation of the observed weather regimes

To plot the composite maps of each regime and the mean frequencies of each cluster, 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" />
