# RegionalSPEI

The goal of RegionalSPEI is to calculate
the standardised precipitation evapotranspiration index
using the additional regional frequency analysis as described in
Martins et al. (2022) <doi:10.1590/1678-4499.20220061>.
The set of functions also calculate the discordance, heterogeneity and, 
goodness of fit measures. They also calculate the parameters of 
the regional distribution and the cumulative probabilities.

## Installation

You can install the development version of RegionalSPEI from [GitHub](https://github.com/gabrielblain/RegionalSPEI) with:

``` r
# install.packages("devtools")
devtools::install_github("gabrielblain/RegionalSPEI")
```

# Basic Instructions

## Function Add_Discord()
Calculates the Hosking and Wallis' discordance measure under the additional approach.

## Usage
```r
Add_Discord(dataset)
```
## Arguments
* dataset: A csv file with data from each sites. The first column is the Years. The second column is the Months (from 1 to 12). The third column is the data coming from
each site. See ’dataset.csv’ as example.

## Value

Hosking and Wallis’ discordancy measure calculated using the additive approach as proposed in ’LOPES MARTINS et al. (2022)’ https://doi.org/10.1590/1678-4499.20220061

## Examples
data(dataset)
Add_Discord(dataset)

## Function Add_Heterogenety()
Calculates the Hosking and Wallis' Heterogenety measure under the additional approach.

## Usage
```r
Add_Heterogenety(dataset, rho = 0, Ns = 100)
```
## Arguments
* dataset: A csv file with data from each sites. The first column is the Years. The second column is the Months (from 1 to 12). The third column is the data coming     from each site. See ’dataset.csv’ as example.
* rho Average spatial correlation (between 0 and 1). defauld is 0.
* Ns Number of simulated groups of series. Default is 100, but at least 500 is recommended.

## Value
’Hosking’ and ’Wallis” heterogeneity measure calculated using the additive approach proposed in ’LOPES MARTINS et al. (2022)’ https://doi.org/10.1590/1678-4499.20220061

## Examples
data(dataset)
Add_Heterogenety(dataset,rho = 0.5,Ns = 100)

## Function Add_GoodnessFit()
Calculates the Hosking and Wallis' Goodness of fit measure and its bivariate extension as proposed by Kjeldsen and Prosdocimi (2015) 

## Usage
```r
Add_GoodnessFit(dataset, rho = 0, Ns = 100)
```
## Arguments
* dataset: A csv file with data from each sites. The first column is the Years. The second column is the Months (from 1 to 12). The third column is the data coming     from each site. See ’dataset.csv’ as example.
* rho Average spatial correlation (between 0 and 1). defauld is 0.
* Ns Number of simulated groups of series. Default is 100, but at least 500 is recommended.

## Value
Hosking and Wallis (1991) Goodness of fit measure and its bivatriate extension proposed in Kjeldsen and Prosdocimi (2015)

## Examples
data(dataset)
Add_GoodnessFit(dataset,rho=0.5,Ns=100)

## Function Add_RegPar()
Calculates Regional parameter for several distributions.

## Usage
```r
Add_RegPar(dataset)
```
## Arguments
* dataset: A csv file with data from each sites. The first column is the Years. The second column is the Months (from 1 to 12). The third column is the data coming     from each site. See ’dataset.csv’ as example.

## Value
Regional parameter for several distributions within a homogeneous region or group.
GEV: Generalized extreme value distribution.
GLO: Generalized logistic distribution. 
PE3: Pearson type III distribution. 
GNO: Generalized normal distribution. GPA: Generalized pareto distribution.

## Examples
data(dataset)
Add_RegPar(dataset)

## Function Add_RegProb()
Calculates cumulative probabilities.

## Usage
```r
Add_RegPar(dataset)
```
## Arguments
* dataset: A csv file with data from each sites. The first column is the Years. The second column is the Months (from 1 to 12). The third column is the data coming     from each site. See ’dataset.csv’ as example.
* distr A string indicating the regional distribution “GEV” “GLO” “PE3” “GNO” “GPA”.
* Parameters of the regional distribution (selected by ’Add_Goodness’). Obtained
from ’Add_RegPar’. See example.

## Value
Cumulative probabilities for the sites forming the homogeneous region or group.

## Examples
data(dataset)
data(parGEV)
Add_RegProb(dataset,distr="GEV",bestPar=parGEV)

## Function Add_RegSPEI()
Calculates the regional SPEI.

## Usage
```r
Add_RegSPEI(dataset)
```
## Arguments
* RegProb The cumulative probabilities for the sites forming the homogeneous region or group. Calculated using the ’Add_RegProb’ function. See example.

## Value
The regional standardised precipitation evapotranspiration index
using the additional regional frequency analysis as described in
Martins et al. (2022) <doi:10.1590/1678-4499.20220061>.

## Examples
data(RegProb)
RegSPEI=Add_RegSPEI(RegProb)

## dataset: Difference between precipitation and ’evapotranspiration’.

Contains monthly values for the difference between precipitation and ’evapotranspiration’ (1993 to
2021).

## Usage

```r
dataset
```

## Format
* A data.frame with 15 variables and 344 rows.
* Year Year
* Month Month
* site1 precipitation minus ’evapotranspiration’ at site 1
* site2 precipitation minus ’evapotranspiration’ at site 2
* site3 precipitation minus ’evapotranspiration’ at site 3
* site4 precipitation minus ’evapotranspiration’ at site 4
* site5 precipitation minus ’evapotranspiration’ at site 5
* site6 precipitation minus ’evapotranspiration’ at site 6
* site7 precipitation minus ’evapotranspiration’ at site 7
* site8 precipitation minus ’evapotranspiration’ at site 8
* site9 precipitation minus ’evapotranspiration’ at site 9
* site10 precipitation minus ’evapotranspiration’ at site 10
* site11 precipitation minus ’evapotranspiration’ at site 11
* site12 precipitation minus ’evapotranspiration’ at site 12
* site13 precipitation minus ’evapotranspiration’ at site 13

## Source

Generated by the statistical simulation using the generalized extreme value distribution.

## Examples

```r
data(dataset)
```

## parGEV: Regional parameters of the generalized extreme value distribution.

Contains parameters of the generalized extreme value distribution fitted through the additive regional
frequency analysis.

## Usage

```r
parGEV
```

## Format
* A data.frame with 4 variables and 12 rows.
* Month Month
* loc location parameter
* scl scale parameter
* shp shape parameter

## Source

Generated by the statistical simulation using the generalized extreme value distribution.

## Examples

```r
data(parGEV)
```

## RegProb: Cumulative probabilities of the precipitation minus ’evapotranspiration’.

Contains monthly values for the cumulative probabilities of precipitation minus ’evapotranspiration’
totals (1993 to 2021).

## Usage

```r
RegProb
```

## Format
* A data.frame with 15 variables and 344 rows.
* Year Year
* Month Month
* site1 probabilities of precipitation minus ’evapotranspiration’ at site 1
* site2 probabilities of precipitation minus ’evapotranspiration’ at site 2
* site3 probabilities of precipitation minus ’evapotranspiration’ at site 3
* site4 probabilities of precipitation minus ’evapotranspiration’ at site 4
* site5 probabilities of precipitation minus ’evapotranspiration’ at site 5
* site6 probabilities of precipitation minus ’evapotranspiration’ at site 6
* site7 probabilities of precipitation minus ’evapotranspiration’ at site 7
* site8 probabilities of precipitation minus ’evapotranspiration’ at site 8
* site9 probabilities of precipitation minus ’evapotranspiration’ at site 9
* site10 probabilities of precipitation minus ’evapotranspiration’ at site 10
* site11 probabilities of precipitation minus ’evapotranspiration’ at site 11
* site12 probabilities of precipitation minus ’evapotranspiration’ at site 12
* site13 probabilities of precipitation minus ’evapotranspiration’ at site 13

## Source

Generated by the statistical simulation using the generalized extreme value distribution 
with regional parameters.

## Examples

```r
data(RegProb)
```

## BugReports: 
<https://github.com/gabrielblain/RegionalSPEI/issues>

## License:

MIT

## Authors: 
Gabriel Constantino Blain, Graciela da Rocha Sobierajski, and Leticia Lopes Martins. 
Maintainer: Gabriel Constantino Blain, <gabriel.blain@sp.gov.br>

## Acknowledgments:
To CNPq for Fellowship for the first author (Process 307616/2019-3).
To Coordenação de Aperfeiçoamento de Pessoal de Nível Superior for Fellowship for the third author (Grant No. 33081018001P4 – Agricultura tropical e subtropical)

## References
Beguería S., Vicente-Serrano S. M., Reig F., Latorre B. (2014). Standardized
precipitation evapotranspiration index (SPEI) revisited: parameter fitting,
evapotranspiration models, tools, datasets and drought monitoring.
International Journal of Climatology, 34, 3001–3023. https://doi.org/10.1002/joc3887

Hosking, J. R. M. and Wallis, J. R. (1993). Some statistic useful in regional frequency analysis. 
Water Resources Research, 29, 271-281. https://doi.org/10.1029/92WR01980

Hosking, J. R. M. and Wallis, J. R., 1997. Regional frequency analysis: an approach based on L-moments. 
Cambridge: Cambridge University Press.

Kjeldsen, T. R. and Prosdocimi, I.  (2015). A bivariate extension of the Hosking and Wallis 
goodness‐of‐fit measure for regional distributions. 
Water Resources Research, 51, 896-907. https://doi.org/10.1002/2014WR015912

Martins, L. L., Souza, J. C., Sobierajski, G. R., Blain, G. C. (2022). Is it possible to apply 
the regional frequency analysis to daily extreme air temperature data? 
Bragantia, 81,1-22. https://doi.org/10.1590/1678-4499.20220061

Package ‘lmom', Version 2.9, Author J. R. M. Hosking. https://CRAN.R-project.org/package=lmom

Package ‘lmomRFA', Version 3.6, Author J. R. M. Hosking. https://CRAN.R-project.org/package=lmomRFA

Package ‘MASS', Venables WN, Ripley BD (2002). Modern Applied Statistics with S, 
Fourth edition. Springer, New York. ISBN 0-387-95457-0, https://www.stats.ox.ac.uk/pub/MASS4/.

Package ‘rrcov', Version 1.7-4, Author Valentin Todorov.  https://CRAN.R-project.org/package=rrcov

Package ‘stats', Version: 4.4.0, Author R Core Team and contributors worldwide 
https://stat.ethz.ch/R-manual/R-devel/library/stats/html/00Index.html