Diurnal Temperature Variation (DTR) Indicator
=============================================

The diurnal temperature variation indicator is a proxy for energy demand. The diurnal temperature indicator is the number of days in a season where the daily temperature variation (tasmax - tasmin) exceeds the vulnerability threshold. Here, the vulnerability threshold is based on the mean daily temperature variation for a reference period plus 5 degrees. This definition was proposed in a study conducted for the DALKIA energy company. 

*Note: This vignette has been written to process and plot the output of an ESMValTool namelist configured with a specific set of parameters. If you wish to run and plot the outputs for another set of parameters, you need to re-run the corresponding namelist with the desired parameters, interpolate the output NetCDF files to a common grid, and modify the vignette code accordingly.*

The following example will compute the diurnal temperature variation indicator in the North Atlantic - European Sector [20ºW-50ºE; 30ºN-80ºN] using the CMIP5 projection for the 8.5 scenario.

### 1- Load dependencies
This example requires the following system libraries:


- libssl-dev
- libnecdf-dev
- cdo


You will need to install specific versions of certain R packages as follows:

```r
library(devtools)
install_git('https://earth.bsc.es/gitlab/es/startR', branch = 'develop-hotfixes-0.0.2')
```

One functions should be loaded by running the following lines in R, until integrated into the new magic.bsc package.

```r
source('https://earth.bsc.es/gitlab/nperez/magic.bsc/raw/master/R/DTR_Indicator.R')
source('https://earth.bsc.es/gitlab/nperez/magic.bsc/raw/master/R/DTR_Ref.R')
```


All the other R packages involved can be installed directly from CRAN and loaded as follows:
```r
library(s2dverification)
library(startR)
library(multiApply)
library(ggplot2)
library(climdex.pcic)
library(parallel)
```

### 2- Loading reference data

The vulnerability threshold, based on the mean daily temperature variation, is computed for the reference period 1961-1990.


The historical simulations for the CMIP5 model should be loaded by the function `Start` from `s2dverification` package.

```r
start_climatology <- '1961-01-01'
end_climatology <- '1990-12-31'
lat.min <- 30;  lat.max <- 80
lon.min <- -20; lon.max <- 50
climatology_filenames_tasmax <- paste0("/esarchive/scratch/pbretonn/cmip5-cp4cds/historical/day/tasmax/",
                                "tasmax_day_IPSL-CM5A-LR_historical_r1i1p1_19500101-20051231.nc")
climatology_filenames_tasmin <- paste0("/esarchive/scratch/pbretonn/cmip5-cp4cds/historical/day/tasmin/",
                                "tasmin_day_IPSL-CM5A-LR_historical_r1i1p1_19500101-20051231.nc")                                
historical_tasmax <- Start(model = climatology_filenames_tasmax, var = 'tasmax', var_var = 'var_names', 
                        time = values(list(as.POSIXct(start_climatology), as.POSIXct(end_climatology))),
                        time_tolerance = as.difftime(0, units = 'days'), 
                        lat = values(list(lat.min, lat.max)), lon = values(list(lon.min, lon.max)), 
                        lon_var = 'lon', lon_reorder = CircularSort(0, 360), return_vars = list(time = 'model', 
                        lon = 'model', lat = 'model'), retrieve = TRUE)
historical_tasmin <- Start(model = climatology_filenames_tasmin, var = 'tasmin', var_var = 'var_names',
                        time = values(list(as.POSIXct(start_climatology), as.POSIXct(end_climatology))),
                        time_tolerance = as.difftime(0, units = 'days'), 
                        lat = values(list(lat.min, lat.max)), lon = values(list(lon.min, lon.max)),
                        lon_var = 'lon', lon_reorder = CircularSort(0, 360),
                        return_vars = list(time = 'model', lon = 'model', lat = 'model'),
                        retrieve = TRUE)                        
```
The function `DTR_ref` computes the mean between maximum and minimum temperature for each season during the selected reference period:

```r
dtr_base <- DTR_Ref(tmax = historical_tasmax, tmin = historical_tasmin, by.seasons = TRUE, ncores = NULL)
```

The label `dtr_ref` contains the output for each season and gridpoint:

```r
> str(dtr_base)
List of 2
 $ dtr_ref: num [1:4, 1, 1, 1:26, 1:21] 15.3 17.2 16.2 13.7 12.7 ...
 $ season : chr [1:4] "DJF" "MAM" "JJA" "SON"
 ```
 
 
### 3- Loading projection data

Minimum and maximum temperature of the 8.5 scenario is loaded for the period 2020-2040:

```r
start_projection <- '2020-01-01'
end_projection <- '2040-01-01'
projection_filenames_tasmax <- paste0("/esarchive/scratch/pbretonn/cmip5-cp4cds/rcp85/day/tasmax/",
                                      "tasmax_day_IPSL-CM5A-LR_rcp85_r1i1p1_20060101-22051231.nc")
projection_filenames_tasmin <- paste0("/esarchive/scratch/pbretonn/cmip5-cp4cds/rcp85/day/tasmin/",
                                      "tasmin_day_IPSL-CM5A-LR_rcp85_r1i1p1_20060101-22051231.nc")    
rcp_tasmax <- Start(model = projection_filenames_tasmax, var = 'tasmax', var_var = 'var_names',
                      time = values(list(as.POSIXct(start_projection), as.POSIXct(end_projection))),
                      time_tolerance = as.difftime(0, units = 'days'), 
                      lat = values(list(lat.min, lat.max)), lon = values(list(lon.min, lon.max)),
                      lon_var = 'lon', lon_reorder = CircularSort(0, 360),
                      return_vars = list(time = 'model', lon = 'model', lat = 'model'),
                      retrieve = TRUE)
rcp_tasmin <- Start(model = projection_filenames_tasmin, var = 'tasmin', var_var = 'var_names',
                      time = values(list(as.POSIXct(start_projection),as.POSIXct(end_projection))),
                      time_tolerance = as.difftime(0, units = 'days'), 
                      lat = values(list(lat.min, lat.max)), lon = values(list(lon.min, lon.max)),
                      lon_var = 'lon', lon_reorder = CircularSort(0, 360),
                      return_vars = list(time = 'model', lon = 'model', lat = 'model'),
                      retrieve = TRUE)
```


### 4- Computing the diurnal temperature variation indicator

The diurnal temperature variation indicator is computed with the function `DTR_indicator` indicating the maximum and minimum temperature for the future projectionn and the mean daily temperature variation:

```r
dtr_indicator <- DTR_Indicator(rcp_tasmax, rcp_tasmin, ref = dtr_base, by.seasons = TRUE, ncores = NULL)
```

The function returns a list of three elements, being the label `indicator` the desired output:

```r
> str(dtr_indicator)
List of 3
 $ indicator: int [1:21, 1:4, 1, 1, 1:26, 1:21] 2 1 1 0 2 3 0 6 0 2 ...
 $ year     : chr [1:21] "2020" "2021" "2022" "2023" ...
 $ season   : chr [1:4] "DJF" "JJA" "MAM" "SON"
```


### 5- Visualizing the diurnal temperature variation indicator

A four panel plot can be generated to visualize the seasonal indicator running the following lines:


```r
lat <- attr(rcp_tasmax, "Variables")$dat1$lat
lon <- attr(rcp_tasmax, "Variables")$dat1$lon
  
season <-   as.factor(dtr_indicator$season)
year <- dtr_indicator$year
  
breaks <- seq(0, max(apply(data, c(2, 5, 6), mean)), 5)

dtr_rcp <- array(dim = c(length(lat), length(lon), 4))             
for (j in 1:4){
              dtr_rcp[,,j] <- Mean1Dim(dtr_indicator$indicator[,j,,,,], 1)
}            
         

PlotLayout(PlotEquiMap, c(1, 2), lon = lon, lat = lat, var = dtr_rcp, titles = c('DJF', 'MAM', 'JJA', 'SON'), 
           toptitle = paste0("Number of days in exceeding the reference mean diurnal temperature range by 5 degrees ", 
           " ", substr(start_projection, 1, 4), "-", substr(end_projection, 1, 4)), filled.continents = FALSE, 
           units = "Days", title_scale = 0.5, axelab = FALSE, draw_separators = TRUE, subsampleg = 1, 
           brks = breaks, color_fun = clim.palette("yellowred"), bar_extra_labels = c(2, 0, 0, 0), 
           fileout = "dtr_indicator_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.png")
```

<img src = "dtr_indicator_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.png" />


In order to compare with the reference period, the diurnal temperature variation indicator will be computed for the reference period:

```r
dtr_indicator_reference <- DTR_indicator(historical_tasmax, historical_tasmin, ref = dtr_base, by.seasons = TRUE, ncores = NULL)
```

The function `PlotLayout` will allow to produce a four panel plot:

```r
dtr_diff <- array(dim=c(length(lat), length(lon), 4))
for (i in 1:4){
                dtr_diff[,,i] <- Mean1Dim(dtr_indicator$indicator[,i,1,1,,], 1) - 
                                 Mean1Dim(dtr_indicator_reference$indicator[,i,1,1,,], 1)
}
PlotLayout(PlotEquiMap, c(1, 2), lon = lon, lat = lat, var = dtr_diff,
           titles = c('DJF', 'MAM', 'JJA', 'SON'), toptitle = "Change in DTR indicator (2020-2040) - (1961-1990)",
           filled.continents = FALSE, units = "Days",
           axelab = FALSE, draw_separators = TRUE, subsampleg = 1, brks = seq(-16, 16, by=2),
           bar_extra_labels = c(2, 0, 0, 0), fileout = "Comparison_DTR_2020-2040_vs_1961-1990_rcp85.png")
```
<img src = "Comparison_DTR_2020-2040_vs_1961-1990_rcp85.png" />



### 6 - Saving the diurnal temperature indicator

The following lines will generate ncdf file for each season for the future projection diurnal temperature indicator:

```r
attributes(lon) <- NULL
attributes(lat) <- NULL
dim(lon) <-  c(lon = length(lon))
dim(lat) <- c(lat = length(lat))
data <- dtr_indicator$indicator
for (j in 1 : 4) {
                  data_subset <- data[,j,,,,]
                  data_subset <- aperm(data_subset, c(3, 2, 1))
                  names(dim(data_subset)) <- c("lon", "lat", "time")
                  metadata <- list(index = list(dim = list(list(name = 'time', unlim = FALSE, prec='double'))))
                  attr(data_subset, 'variables') <- metadata
                  day <- "01"
                  if (levels(season)[j] == "DJF") {
                                                   month <- "-01-"
                  } else if (levels(season)[j] == "MAM") {
                                                   month <- "-03-"
                  } else if (levels(season)[j] == "JJA") {
                                                   month <- "-06-"
                  } else {
                                                   month <- "-09-"
                  }
                  time <- as.POSIXct(paste0(year, month, day))
                  time <- julian(time, origin = as.POSIXct("1970-01-01"))
                  
                  attributes(time) <- NULL
                  dim(time) <- c(time = length(time))
                  metadata <- list(time = list(standard_name = 'time', long_name = 'time', 
                                   units = 'days since 1970-01-01 00:00:00', prec = 'double', 
                                   dim = list(list(name = 'time', unlim = FALSE))))
                  attr(time, "variables") <- metadata
                  ArrayToNetCDF(list(metric= data_subset, lat = lat, lon = lon, time = time), 
                                paste0("dtr_indicator", "_", levels(season)[j] , "_IPSL-CM5A-LR_rcp85_", 
                                start_projection, "_", end_projection, ".nc"))
}
```

The files will be saved in the working directory with the names:

- dtr_indicator_DJF_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.nc
- dtr_indicator_MAM_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.nc
- dtr_indicator_JJA_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.nc
- dtr_indicator_SON_IPSL-CM5A-LR_rcp85_2020-01-01_2040-01-01.nc