---
author: "Eroteida Sánchez-García"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::knitr}
  %\VignetteIndexEntry{Achiving BestNAOWeighting in CSTools}
  %\usepackage[utf8]{inputenc}
---

Achiving BestNAOWeighting in CSTools
-----------------------------------------

**reference**: Sánchez-García, E., Voces-Aboy, J., Navascués, N., & Rodríguez-Camino, E. (2019). Regionally improved seasonal forecast of precipitation through Best estimation of winter NAO, Adv. Sci. Res., 16, 165174, <https://doi.org/10.5194/asr-16-165-2019>


## Before start

System requeriment: CDO

In our R session, we will need to:

- define the working directory: `setwd("/home/...../AEMET_CSTOOLS")`
- install and load R packages

```{r message=FALSE}
library(multiApply)
library(verification)
library(s2dverification)
```

Data files used in the following code will be in `./data_CST` directory.


## Workflow of develop-BestNAOWeighting branch in CSTools

Loading functions: 

```{r}
source("../R/CST_PDFIndexHind.R")
source("../R/CST_PDFIndexFcst.R")
source("../R/CST_PDFBest.R")
source("../R/CST_WeightIndex.R")
source("../R/CST_EMBestIndexWeighting.R")
source("../R/CST_ProbBestIndexWeighting.R")
source("../R/zzz.R")
```

It is necessary to have calculated previosly the NAO index for models to combine
(for instance, a dynamical model as first guess combined with an empirical 
model) in order to achieve the Best NAO estimation.

The first step is to load from a RData file the list lNAOs_CST with the NAO 
index as CST object for period December,January and February, obtained 
previously for the models to combine:



```{r message=FALSE}
fileNAOs_CST <- ("../data/lNAOs_CST.RData")
load(fileNAOs_CST)
```


Improving the two seasonal forecats systems (modelsECMWF-S5 as M1 and S-ClimWaRe
as M2) NAO index DPFs estimate for the hindcast and forecast period, and ,then, 
we combine them to obtain the Best NAO PDF estimate by runnning:

```{r message=FALSE}
# Improving the ECMWF-S5 (M1) NAO index DPFs estimate for the hindcast and 
# forecast period using the named 'LMEV' methodology or scheme
pdf_hind_m1_CST <- CST_PDFIndexHind(lNAOs_CST$index_hind1, 
                                    lNAOs_CST$index_obs, 
                                    type_exp = 'ens',
                                    method = 'LMEV', 
                                    na.rm = FALSE)
str(pdf_hind_m1_CST)
dim(pdf_hind_m1_CST$data)

pdf_fcst_m1_CST <- CST_PDFIndexFcst(lNAOs_CST$index_hind1, 
                                    lNAOs_CST$index_obs,
                                    lNAOs_CST$index_fcst1,
                                    type_exp = 'ens',
                                    method = 'LMEV', 
                                    na.rm = FALSE)
str(pdf_fcst_m1_CST)
dim(pdf_fcst_m1_CST$data)

# Improving the S-ClimWaRe (M2) NAO index DPFs estimate for the hindcast and 
# forecast period using the named 'ME' methodology or scheme
pdf_hind_m2_CST <- CST_PDFIndexHind(lNAOs_CST$index_hind2, 
                                    lNAOs_CST$index_obs,
                                    type_exp = 'sta',
                                    method = 'ME', 
                                    na.rm = FALSE)
str(pdf_hind_m2_CST)
dim(pdf_hind_m2_CST$data)

pdf_fcst_m2_CST <- CST_PDFIndexFcst(lNAOs_CST$index_hind2, 
                                    lNAOs_CST$index_obs,
                                    lNAOs_CST$index_fcst2,
                                    type_exp = 'sta',
                                    method = 'ME', 
                                    na.rm = FALSE)
str(pdf_fcst_m2_CST)
dim(pdf_fcst_m2_CST$data)

# Best NAO pdf estimate for hindcast period
pdf_aux <- array(NA, dim = c(dim(pdf_hind_m1_CST$data)['time'], 
                             dataset = 2, member = 1, 
                             statistic = 4, season = 1))
pdf_aux[,1,,,] <- pdf_hind_m1_CST$data
pdf_aux[,2,,,] <- pdf_hind_m2_CST$data
pdf_exp <- list(data = pdf_aux, Datasets = c("ECMWF-S5","SCLIMWARE"), 
                season = c('DJF'), 
                Dates = list(start = pdf_hind_m2_CST$Dates$start))
class(pdf_exp) <- 's2dv_cube'
pdf_hind_best_CST <- CST_PDFBest(pdf_exp, bc_dataset1 = TRUE, bc_dataset2 = FALSE)

# Best NAO pdf estimate for forecast period
pdf_aux <- array(NA, dim = c(time = 1, dataset = 2, member = 1, 
                                  statistic = 4, season = 1))
pdf_aux[,1,,,] <- pdf_fcst_m1_CST$data
pdf_aux[,2,,,] <- pdf_fcst_m2_CST$data
pdf_exp <- list(data = pdf_aux, Datasets = c("ECMWF-S5","SCLIMWARE"), 
                 season = c('DJF'), Dates = list(start = pdf_fcst_m2_CST$Dates$start))
class(pdf_exp) <- 's2dv_cube'
pdf_fcst_best_CST <- CST_PDFBest(pdf_exp, bc_dataset1 = TRUE, bc_dataset2 = FALSE)

```


The content of the list `pdf_hind_best_CST` can be reviewed visualizing the structure:
```{r}
str(pdf_hind_best_CST)
```


Now, we can obtain an array with weights for each ensemble's member based on this Best NAO pdf estimate running the following code:

```{r message=FALSE}
# For the hindcast period
# Computing the weights for ECMWF-S5 members using the Best NAO estimate
weigths_index_CST <- CST_WeightIndex(lNAOs_CST$index_hind1, pdf_hind_best_CST)
```


The content of the weight's array can be reviewed visualizing the structure:

```{r}
dim(weigths_index_CST$data)
str(weigths_index_CST)

```


Now, we need to load the total precipitation from November to March for hindcast 
period over Iberian Peninsula. Then, we compute terciles and the probability 
that the variable data will be in the lower (or upper) tercile based on the best 
NAO pdf estimate running the code:

```{r message=FALSE}
# Loading the precipitation data for November to March from ECMWS-S5 
# in a CSTools object
filePR_CST <- ("../data/pr_hindcast_ecmf-s5_CST.RData")
load(filePR_CST)

# Computing terciles and probabilities after weighting the ensemble members 
weights_index_exp <- weigths_index_CST
em_var_exp <- CST_EMBestIndexWeighting(var_exp, weights_index_exp)
prob_var_exp <- CST_ProbBestIndexWeighting(var_exp, weights_index_exp)

```


If we want to compare with the raw output model:

```{r message=FALSE}
# Computing terciles and probabilities with CST_function
weights_index_exp_raw <- weights_index_exp
weights_index_exp_raw$data <- rep(1/25, 20 * 25)
dim(weights_index_exp_raw$data) <- dim(weights_index_exp$data)

em_var_exp_raw <- CST_EMBestIndexWeighting(var_exp, weights_index_exp_raw)
prob_var_exp_raw <- CST_ProbBestIndexWeighting(var_exp, weights_index_exp_raw)

```


## Plotting probability maps:

A map  with the probability that the total precipitation from November 2012 to
March 2013, for example, will be in the lower tercile based on the best NAO pdf
estimate is obtained running the code:

```{r message=FALSE}
coordVAR <- list(lonmin = -10, lonmax = 5, latmin = 35, latmax = 45)
lonPlot <- seq(coordVAR$lonmin,coordVAR$lonmax,0.50)
latPlot <- seq(coordVAR$latmax,coordVAR$latmin,-0.50)
probData_CST <- prob_var_exp$data[which(var_exp$Dates$start == 2012),1,1,1,,]
brks <- c(0,0.35,0.4,0.5,0.6,0.7,1)
cols <- c("#FFFFFF","#FFEE99","#FFDD00","#CC8800","#993300","#3B1400")
names(brks) <- c("0%","35%","40%","50%","60%","70%","100%")
ofile <- "./Figures/probLower_weight_CST.png"
PlotEquiMap(t(probData_CST[order(latPlot),]), lon = lonPlot, lat = latPlot[length(latPlot):1], filled.continents = FALSE, 
            fileout =ofile, brks=brks, cols = cols, 
            toptitle = paste0("Probability (pcp NDJFM 2012/13) < lower tercile) based on the best NAO pdf estimate"), 
            title_scale= 0.5, intxlon=2.0, intylat=2.0, labW=TRUE)


```

![](./Figures/probLower_weight_CST.png){width=70%}

In a similar way we can plot the map with the probability that the total precipitation from November 2012 to
March 2013, for example, will be in the lower tercile from ECMWF Seasonal Forecast System 5 (raw) to compare results running the code:

```{r message=FALSE}
probDataRaw_CST <- prob_var_exp_raw$data[which(var_exp$Dates$start == 2012),1,1,1,,]
brks <- c(0,0.35,0.4,0.5,0.6,0.7,1)
cols <- c("#FFFFFF","#FFEE99","#FFDD00","#CC8800","#993300","#3B1400")
names(brks) <- c("0%","35%","40%","50%","60%","70%","100%")
ofile <- "./Figures/probLower_raw_CST.png"
PlotEquiMap(t(probDataRaw_CST[order(latPlot),]), lon = lonPlot, lat = latPlot[length(latPlot):1], filled.continents = FALSE, 
            fileout =ofile, brks=brks, cols = cols, 
            toptitle = paste0("Probability (pcp NDJFM 2012/13) < lower tercile) based on ECMWF-S5 (raw)"), 
            title_scale= 0.5, intxlon=2.0, intylat=2.0, labW=TRUE)


```

![](./Figures/probLower_raw_CST.png){width=70%}
