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 NCEP data stored in an array (`data$obs`).

### 3- Daily anomalies based on a smoothed climatology
The weather regimes classification is based on daily anomalies, which have been computed by following these steps: 

- Daily climatology is computed with the `Clim()` function.

```r
clim<-Clim(var_exp = data$mod,var_obs = data$obs,memb=F)
```
- A LOESS filter has been applied to the climatology to remove the short-term variability and retain the annual cycle and to better isolate quasi stationary periods. The parameter `loess_span` should be adapted to the period used to compute the climatology (e.g. season, month, week,...).

```r
Loess<-function(clim,loess_span){
  data<-data.frame(ensmean=clim,day=1:length(clim))
  loess_filt<-loess(ensmean~day,data,span=loess_span)
  output<-predict(loess_filt)
  return(output)
}
clim_smoothed_obs<-aperm(apply(clim$clim_obs,c(1:length(dim(clim$clim_obs)))[-which(names(dim(clim$clim_obs))=='ftime')],Loess,loess_span=1),c(2,1,3,4))
clim_smoothed_exp<-aperm(apply(clim$clim_exp,c(1:length(dim(clim$clim_exp)))[-which(names(dim(clim$clim_exp))=='ftime')],Loess,loess_span=1),c(2,1,3,4))
```
- Anomalies are computed with the `Ano()` function, as the deviations of the sea level pressure from the smoothed climatologies.

```r
anom_obs<-Ano(data$obs,clim_smoothed_obs)
anom_exp<-Ano(data$mod,clim_smoothed_exp)
```

### 4- Weather regimes in observations 

`WeatherRegimes()` function is used to define the clusters corresponding to the ERA-Interim classification. There are different assumptions that should be performed to obtain the weather regimes. In this example these assumptions are: 

-  k-means algorithm has been employed to produce a partition of all states in a predefined number of clusters (`ncenters`). These partitions maximizes the ratio of variance among the clusters centroids and the intra-cluster variance. In this example we have selected four partitions, which is the standard in the literature.  
- 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
WR_obs<-WeatherRegime(data=anom_obs,EOFS=FALSE,lat_weights = TRUE,lat=data$lat,ncenters = 4)
```

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