---
author: "Nuria Perez"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::knitr}
  %\VignetteIndexEntry{Multi-model Skill Assessment}
  %\usepackage[utf8]{inputenc}
---

Multi-model Skill Assessment
-----------------------------------------

**reference**: Mishra, N., Prodhomme, C., & Guemas, V. (2018). Multi-Model Skill Assessment of Seasonal Temperature and Precipitation Forecasts over Europe, 29–31. <https://link.springer.com/article/10.1007%2Fs00382-018-4404-z>


A version of s2dverification under development should be loaded by running:


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


Library *CSTools*, should be installed from CRAN and loaded:


```r
install.packages("CSTools")
library(CSTools)
```


### 1.- Load data

In this case, the seasonal temperature forecasted, initialized in November, will be used to assess the EUROSIP multi-model seasonal forecasting system consists of a number of independent coupled seasonal forecasting systems integrated into a common framework. From September 2012, the systems include those from ECMWF, the Met Office, Météo-France and NCEP.

The parameters defined are the initializating month and the variable:


```{r cars}
mth = '11'
clim_var = 'tas'
```


The simulations available for these models are covering the period 1992-2012. So, the starting and ending dates can be defined by running the following lines:


```r
ini <- 1992
fin <- 2012
start <- as.Date(paste(ini, mth, "01", sep = ""), "%Y%m%d")
end <- as.Date(paste(fin, mth, "01", sep = ""), "%Y%m%d")
dateseq <- format(seq(start, end, by = "year"), "%Y%m%d")
``` 


The grid in which all data will be interpolated should be also specified. The observational dataset used in this example is the EraInterim. 


```r
grid <- "256x128"
obs <- "erainterim"
```

Using the `CST_Load` function, the data available in our data store can be loaded. The following lines, shows how this function can be used. However, the data is loaded from a previous saved `.RData` file:
Ask nuria.perez at bsc.es to achieve the data to run the recipe.

```r
require(zeallot)

glosea5 <- '/esnas/exp/glosea5/specs-seasonal_i1p1/$STORE_FREQ$_mean/$VAR_NAME$-allmemb/$VAR_NAME$_$START_DATE$.nc'

c(exp, obs) %<-% 
   CST_Load(var = clim_var, exp = list(list(name = 'glosea5', path = glosea5), 
                                  list(name = 'ecmwf/system4_m1'),
                                  list(name = 'meteofrance/system5_m1')),
                  obs = obs, sdates = dateseq, leadtimemin = 2, leadtimemax = 4,
                  lonmin = -20, lonmax = 70, latmin = 25, latmax = 75, 
                  storefreq = "monthly", sampleperiod = 1,  nmember = 9, 
                  output = "lonlat", method = "bilinear", 
                  grid = paste("r", grid, sep = ""))
#save(exp, obs, file = "../tas_toydata.RData")   

# Or use the following line to load the file provided in .RData format:
load(file = "./tas_toydata.RData")
```

There should be two new elements loaded in the R working environment: `exp` and `obs`, containing the experimental and the observed data for temperature. It's possible to check that they are of class `sd2v_cube` by running:


```
class(exp)
class(obs)
```

The corresponding data is saved in the element `data` of each object, while other relevant information is saved in different elements, such as `lat` and `lon`:

```r
> dim(exp$data)
dataset  member   sdate   ftime     lat     lon 
      3       9      21       3      35      64 
> dim(obs$data)
dataset  member   sdate   ftime     lat     lon 
      1       1      21       3      35      64 
Lat <- exp$lat
Lon <- exp$lon
```


### 2.- Computing and plotting Anomaly Correlation Coefficient

The Anomaly Correlation Coefficient (ACC) is the most widely used skill metric for Seasonal Climate Forecast quality (Mishra et al., 2018). 


First step is to compute the anomalies over the loaded data applying cross validation technique on individual members by running:

```
c(ano_exp, ano_obs) %<-% CST_Anomaly(exp = exp, obs = obs, cross = TRUE, memb = TRUE)
```

The dimensions are preserved:

```
> str(ano_exp$data)
 num [1:3, 1:9, 1:21, 1:3, 1:35, 1:64] -1.647 -0.478 -0.096 1.575 1.086 ...
 - attr(*, "dimensions")= chr [1:6] "dataset" "member" "sdate" "ftime" ...
> str(ano_obs$data)
 num [1, 1, 1:21, 1:3, 1:35, 1:64] 0.0235 1.546 1.3885 -0.344 -5.972 ...
 - attr(*, "dimensions")= chr [1:6] "dataset" "member" "sdate" "ftime" ...
```

The ACC is obtained by running the `CST_MultiMetric` function defining the parameter 'metric' as correlation. The function also includes the option of computing the Multi-Model Mean ensemble (MMM).


```r
AnomDJF <- CST_MultiMetric(exp = ano_exp, obs = ano_obs, metric = 'correlation', 
                          multimodel = TRUE)
```


The output of the function `CST_MultiMetric` is a object of class `s2dv_cube`, it contains the result of the metric, in this case correlation, in the `data` element (including the correlation for the MMM in the latest position).
While other relevant data is being stored in the corresponding element of the object:


```r
> dim(AnomDJF$data)
   dataset    dataset statistics        lat        lon 
         4          1          4         35         43 
> names(AnomDJF)
[1] "data"            "lon"             "lat"             "Variable"        "Datasets"        "Dates"          
[7] "when"            "source_files"    "load_parameters"
> names(AnomDJF$Datasets)
[1] "glosea5"                "ecmwf/system4_m1"       "meteofrance/system5_m1" "erainterim"    
```
 
In the second element of the list `AnomDJF`, `metric`, the third dimension contains the lower limit of the 95% confidence interval, the correlation, the upper limit of the 95% confidence interval and the 95% significance level given by a one-sided T-test. 


```r
corre <- AnomDJF$data[ , , 2, , ]
names(dim(corre)) <- c("maps", "lat", "lon")
```


To obtain a spatial plot with a scale from -1 to 1 value of correlation for the model with the highest correlation for each grid point, the following lines should be run:

```r
PlotCombinedMap(corre, lon = Lon, lat = Lat, map_select_fun = max,
                display_range = c(0, 1), map_dim = 'maps',
                legend_scale = 0.5, brks = 11,
                cols = list(c('white', 'darkblue'),
                            c('white', 'darkred'),
                            c('white', 'darkorange'),
                            c('white', 'black')),
                bar_titles = c(names(AnomDJF$Datasets)[-4], "MMM"),
                fileout = "./vignettes/Figures/MultiModelSkill_cor_tas_1992-2012.png",
                width = 14, height = 8)                
```

The next figure is the map of the maximum positive Anomaly Correlation Coefficient (ACC) among the three individual models from EUROSIP and the multimodel ensemble. ACC for each model is calculated between their respective predicted ensemble mean anomalies and the anomalies of the observed temperature obtained from ERAINT for winter (DJF) seasons over the period 1992-2012. Blue, red, yellow and black colors indicate that the maximum correlation is obtained for GloSea5, ECMWF, MF and the Multi-Model Mean respectively (similar to figure 3 in Mishra et al., 2018).


![Max Skills Correlation](../vignettes/Figures/MultiModelSkill_cor_tas_1992-2012.png)



### 3.- Computing and plotting Root Mean Square error (RMS)

The same function can be used to compute the RMS error by defining the parameter `metric` as 'rms'.

```r
AnomDJF <- CST_MultiMetric(exp = ano_exp, obs = ano_obs, metric = 'rms', 
                          multimodel = TRUE)
RMS <- AnomDJF$data[ , , 2, , ]
```

The following lines are necessary to obtain the plot which visualizes the best model given this metric for each grid point. 

```r
names(dim(RMS)) <- c("maps", "lat", "lon")
PlotCombinedMap(RMS, lon = Lon, lat = Lat, map_select_fun = min,
                display_range = c(0, ceiling(max(abs(RMS)))), map_dim = 'maps',
                legend_scale = 0.5, brks = 11,
                cols = list(c('darkblue', 'white'),
                            c('darkred', 'white'),
                            c('darkorange', 'white'),
                            c('black', 'white')),
                bar_titles = c(names(AnomDJF$Datasets)[-4], "MMM"), 
                fileout = "./vignettes/Figures/MultiModelSkill_rms_tas_1992-2012.png",
                width = 14, height = 8)              
```

![Max Skills RMS](../vignettes/Figures/MultiModelSkill_rms_tas_1992-2012.png)


### 4.- Computing and plotting Root Mean Square error Skill Scores (RMSSS)


By running the following lines a plot for the best model given the RMSSS is obtained. 
When parameter `metric` is defined as `rmsss`, the RMSSS are stored in the first position on the third dimension of the `metric` component in the AnoMultiMetric output. 
Notice that the perfect RMSSS is 1 and the parameter  `map_select_fun` from `PlotCombinedMap` function (see *s2dverification R package*) has been defined in order to select the best model.


```r
AnomDJF <- CST_MultiMetric(exp = ano_exp, obs = ano_obs, metric = 'rmsss', 
                          multimodel = TRUE)
RMSSS <- AnomDJF$data[ , , 1, , ]
names(dim(RMSSS)) <- c("maps", "lat", "lon")

PlotCombinedMap(RMSSS, lon = Lon, lat = Lat, 
                map_select_fun = function(x) {x[which.min(abs(x - 1))]},
                display_range = c(0, 
                                  ceiling(max(abs(RMSSS)))), map_dim = 'maps',
                legend_scale = 0.5, brks = 11,
                cols = list(c('white', 'darkblue'),
                            c('white', 'darkred'),
                            c('white', 'darkorange'),
                            c('white', 'black')),
                bar_titles = c(names(AnomDJF$Datasets)[-4], "MMM"), 
                fileout = "./vignettes/Figures/MultiModelSkill_rmsss_tas_1992-2012.png",
                width = 14, height = 8)                
```

![Max Skills RMSSS](../vignettes/Figures/MultiModelSkill_rmsss_tas_1992-2012.png)
