---
title: "Accumulation over a Period"
author: "Earth Sciences department, Barcelona Supercomputing Center (BSC)"
date: "16/03/2021"
output: rmarkdown::html_vignette
vignette: >
---

<!--
```{r, echo = FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
-->

## Introduction

Climate Services not only provide the forecasts of the Essential Climatic Variables, a variety of the sectoral indicators are often required for Climate Services people, including researchers, decision-makers and farmers, etc.


Two of the important indicators for the agricultural sector, especially for the grape industries, are **Spring Total Precipitation** and **Harvest Total Precipitation** that are the total precipitation from April 21th to June 21st and from August 21st to October 21st, respectively.

A function which can compute the sum/accumulation of a variable (like precipitation here) in an adjustable period will be useful. Furthermore, parellel computation is also prefered when handling such a multi-dimensional big data. 

Therefore, `CST_PeriodAccumulation` and `AccumulationPeriod` (along with many other functions for indices computation) have been created to fulfill the needs. The former (with prefix _CST_) handle `s2dv_cube` object and a multidimensional array can be processed by the latter.

When period selection is needed, the `start` and `end` have to be provided to cut out the portion in `time_dim`. Otherwise, the function will take the entire `time_dim`.

## Preliminary setup

In order to run the examples in this vignette, the *multiApply* package need to be loaded by running:

```{r}
install.packages('multiApply')
library(multiApply)
```

### Acummulation over the whole period

We use test data provided by CSTools to load a seasonal precipitation forecast:

```{r}
exp <- CSTools::lonlat_prec
```

This gives us a CSTools object `exp`, containing an element `exp$data` with dimensions:

```{r}  
dim(exp$data)
#dataset  member   sdate   ftime     lat     lon 
#      1       6       3      31       4      4 
```

In this 's2dv_cube' object, there are 6 ensemble members available in the data set, 3 starting dates and 31 forecast times, which refer to daily values in the month of March following starting dates on November 1st in the years 2010, 2011, 2012. This sample spatial domain covers a small area of Northern Italy at resolution 1 degree lon=[6,9], lat=[44,47].

To compute the total precipitation in March for each starting dates, we can run:

```{r}
TP <- CST_PeriodAccumulation(exp)
```

Without the `start` and `end` provided, the `CST_PeriodAccumulation` will use the entire `time_dim`. The result will have dimensions:

```{r}
dim(TP$data)
#dataset  member   sdate     lat     lon
#      1       6       3       4       4
```

### Computing Spring Total Precipitation (from April 21th to June 21st)

To compute SprR with the period given, we use the sample data saved here.

```{r}
load('/esarchive/scratch/cchou/MEDGOLD/grape/output/ECVs/data/temp/prlr/prlr_dv.RData')
```

This contains elements `prlr_dv$exp$data` and `prlr_dv$obs$data` with dimensions:

```{r}
dim(prlr_dv$exp$data)
dataset  member   sdate   ftime     lat     lon
      1       3       4     214       4       4
dim(prlr_dv$obs$data)
dataset  member   sdate   ftime     lat     lon
      1       1       4     214       4       4
```

There are three ensemble members in the prediction data set, 4 starting dates and the entire 7-month forecast times, which refer to daily precipitation from April to October following starting dates on April 1st in the years from 2013-2016. The spatial domain cover parts of Douro Valley of Northern Portugal at resolution 0.25 degree lon=[352.25, 353], lat=[41, 41.75].

To compute SprR for each forecast years, we can run:

```{r}
SprR <- CST_PeriodAccumulation(prlr_dv, start = list(21, 4), end = list(21, 6))
```

The `start` and `end` are the initial and final dates and the day must be given before the month as above. They will be applied along the dimension `time_dim` (it is set to 'ftime' by default).

As mentioned, these paramters are optional, the function will take the entire timeseries when the period is not specified in `start` and `end`.

The dimensions of SprR are:

```{r}
dim(SprR$data)
dataset  member   sdate     lat     lon 
      1       3       4       4       4 
```

The forecast SprR for the 1st member from 2013-2016 of the 1st grid poinnt in mm are:

```{r}
#SprR$data[1,1,,1,1] * 86400 * 1000
#[1]  93.23205 230.41904 194.01412 226.52614
```

### Computing Harvest Total Precipitation (from August 21st to October 21st)

By using the same sample data loaded above, another important indicator, Harvest Total Preciptation, can be computed by running:

```{r}
HarvestR <- CST_PeriodAccumulation(prlr_dv$exp, start = list(21, 8), end = list(21, 10))
```

The forecast HarvestR for the 1st member from 2013-2016 of the 1st grid poinnt in mm are:

```{r}
#HarvestR$data[1,1,,1,1] * 86400 * 1000
#[1]  52.30026  42.88068 156.87961  32.18579
```