README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# SPEIChanges

<!-- badges: start -->
<!-- badges: end -->

A package designed to improve the interpretation of the Standardized
Precipitation-Evapotranspiration index (SPEI) under changing climate conditions.

## Authors

**Gabriel Constantino Blain**  
Maintainer and main author  
[ORCID 0000-0001-8832-7734](https://orcid.org/0000-0001-8832-7734)  
Email: [gabriel.blain@sp.gov.br](mailto:gabriel.blain@sp.gov.br)

**Graciela R. Sobierajski**  
Co-author  
[ORCID 0000-0002-7211-9268](https://orcid.org/0000-0002-7211-9268)

**Leticia L. Martins**  
Co-author  
[ORCID 0000-0002-0299-3005](https://orcid.org/0000-0002-0299-3005)

## Basic Description

The {SPEIChanges} package was created to detect climate changes in the balance
between precipitation and evapotranspiration and quantify how they affect the probability 
of a drought event, quantified by the SPEI (Vicente-Serrano et al. 2010), occurring. The package
applies a nonstationary approach proposed by Blain et al. (2022) and Blain et al. (2025),
designed to isolate the effect of such changes on the central tendency
and dispersion of the SPEI frequency distributions.

The package depends on R (\>= 3.5) and imports the following packages:
{CropWaterBalance},{ismev},  {lubridate}, {zoo}, {extRemes}, {spsUtil}, {stats}, and {utils}.

## Installation

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

``` r
# install.packages("pak")
pak::pak("gabrielblain/SPEIChanges")
```

## Basic Instructions

### Loading the packages

To use the package, first load it into your R session with:
```{r load}
library(SPEIChanges)
# This will also load the required dependencies
```

### Loading dataset from Campinas, state of Sao Paulo, Brazil
The package includes a sample dataset containing daily meteorological data including precipitation, potential evapotranspiration and the difference between them (P - PE). To load the dataset, use the following command:  

```{r dataset}
data(Campinas_daily)
head(Campinas_daily)
```

### Aggregating daily P - PE data at a specified time scale.
To aggregate daily P - PE data at quasi-week time scales, use the `PPEaggreg` function. This function requires a numeric vector or matrix of daily P - PE values, a start date, and the desired time scale (TS) in quasi-weeks. The default TS is 4, which corresponds to a monthly scale.

```{r PPEaggreg}
daily.PPE <- Campinas_daily[,9]
PPE.at.TS <- PPEaggreg(daily.PPE, start.date = "1890-01-01", TS = 4)
head(PPE.at.TS)
```

### Calculating SPEI changes using nonstationary models
To calculate SPEI changes using nonstationary models, use the `SPEIChanges` function. This function requires the aggregated P - PE data and the number of nonstationary models to fit (1 to 3 nonstationary models). The function will return a list containing the SPEI values and the fitted nonstationary models.

```{r SPEIChanges}
Changes_SPEI <- spsUtil::quiet(SPEIChanges(PPE.at.TS=PPE.at.TS, nonstat.models = 3))
head(Changes_SPEI$Changes.Freq.Drought)
head(Changes_SPEI$data.week)
head(Changes_SPEI$GEV.parameters)
```

## Auxiliary functions

The package also includes auxiliary functions such as `Ra.R`, `ET0_HS.R`, `ET0_PM.R`, and `ET0_PT.R`. These functions may be used for calculating daily extraterrestrial solar radiation and potential Evapotranspiration rates, using Hargreaves-Samani, Penman and Monteith, and Preistley-Taylor methods. respectively.

```{r daily Ra}
# Example of using Ra function
daily.Ra <- Ra(lat = -23, start.date = "1995-01-01", end.date = "1995-01-10")
head(daily.Ra)
```

```{r daily PET}
# Example of using ET0_HS function
Tavg <- Campinas[, 2]
Tmax <- Campinas[, 3]
Tmin <- Campinas[, 4]
Ra <- Campinas[, 7]
ET0_HS_values <- ET0_HS(Ra = Ra, Tavg = Tavg, Tmax = Tmax, Tmin = Tmin)
head(ET0_HS_values) 
# Example of using ET0_PM function
Rn <- Campinas[, 8]
WS <- Campinas[, 5]
RH <- Campinas[, 6]
ET0_PM_values <- ET0_PM(Tavg = Tavg,
       Tmax = Tmax,
       Tmin = Tmin,
       Rn = Rn,
       RH = RH,
       WS = WS,
       Alt = 658)
head(ET0_PM_values)
# Example of using ET0_PT function
ET0_PT_values <- ET0_PT(Tavg = Tavg, Rn = Rn)
head(ET0_PT_values)
```

## References

Blain G C, Sobierajski G R, Weight E, Martins L L, Sparks, A. H. 2025. The SPIChanges R-package: Improving the interpretation of the standardized precipitation index under changing climate conditions, Environmental Modelling & Software, 192, DOI: 10.1016/j.envsoft.2025.106573.

Blain G C, Sobierajski G R, Weight E, Martins L L, Xavier A C F 2022. Improving the interpretation of standardized precipitation index estimates to capture drought characteristics in changing climate conditions. International Journal of Climatology, 42, 5586-5608. DOI: 10.1002/joc.7550

Vicente-Serrano, S. M., S. Beguería, and J. I. López-Moreno, 2010: A Multiscalar Drought Index Sensitive to Global Warming: The Standardized Precipitation Evapotranspiration Index. J. Climate, 23, 1696–1718, DOI: 10.1175/2009JCLI2909.1.

Package `CropWaterBalance` Blain et al. DOI: 10.32614/CRAN.package.CropWaterBalance

Package `lubridate` Spinu et al. DOI:	10.32614/CRAN.package.lubridate

Package `zoo` Zeileis and Grothendieck DOI:	10.32614/CRAN.package.zoo

Package `extRemes` Gilleland and Katz DOI:	10.32614/CRAN.package.extRemes

Package `spsUtil` Sproles et al. DOI:	10.32614/CRAN.package.spsUtil

Package `stats` R Core Team DOI: 10.32614/CRAN.package.stats

Package `utils` R Core Team DOI:	10.32614/CRAN.package.utils