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: 

-  First, it call function EOF() of package s2dverification, a function developed for extracting the principal components without rotating them. 
- Cluster partitions are obtained from an iterative process (default `iter.max=100`) in which the centroid coordinates are those that produces the maximum variance ratio. In this example the 30 initial random centroid coordinates have been used (default, `nstart = 30` ).
- To reduce the dimensionality of the problem EOF can be used, however in this example we have not computed EOFs just to take into account the extreme values (`EOFS=FALSE`). 
- Anomalies introduced in the k-means function should be latitude weighted (`lat_weights=TRUE`), therefore latitude values are introduced as input (`lat` input).

```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" />
