Type:	Package
Title:	Calculate Standardised Drought Indices Using NASA POWER Data
Version:	1.0.0
Description:	A set of functions designed to calculate the standardised precipitation and standardised precipitation evapotranspiration indices using NASA POWER data as described in Blain et al. (2023) <doi:10.2139/ssrn.4442843>. These indices are calculated using a reference data source. The functions verify if the indices' estimates meet the assumption of normality and how well NASA POWER estimates represent real-world data. Indices are calculated in a routine mode. Potential evapotranspiration amounts and the difference between rainfall and potential evapotranspiration are also calculated. The functions adopt a basic time scale that splits each month into four periods. Days 1 to 7, days 8 to 14, days 15 to 21, and days 22 to 28, 29, 30, or 31, where 'TS=4' corresponds to a 1-month length moving window (calculated 4 times per month) and 'TS=48' corresponds to a 12-month length moving window (calculated 4 times per month).
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Depends:	R (≥ 3.1.0)
Imports:	graphics, lmom, lubridate, nasapower, stats
URL:	https://github.com/gabrielblain/PowerSDI
BugReports:	https://github.com/gabrielblain/PowerSDI/issues
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), vcr (≥ 0.6.0), vdiffr (≥ 1.0.0)
Config/testthat/edition:	3
Config/testthat/parallel:	true
VignetteBuilder:	knitr
Language:	en-GB
NeedsCompilation:	no
Packaged:	2024-01-15 10:46:29 UTC; Gabriel
Author:	Gabriel Constantino Blain [aut, cre], Graciela R. Sobierajski [aut], Leticia L. Martins [aut], Adam H. Sparks [aut]
Maintainer:	Gabriel Constantino Blain <gabriel.blain@sp.gov.br>
Repository:	CRAN
Date/Publication:	2024-01-15 11:20:02 UTC

PowerSDI: Calculate Standardised Drought Indices Using NASA POWER Data

Description

A set of functions designed to calculate the standardised precipitation and standardised precipitation evapotranspiration indices using NASA POWER data as described in Blain et al. (2023) doi:10.2139/ssrn.4442843. These indices are calculated using a reference data source. The functions verify if the indices' estimates meet the assumption of normality and how well NASA POWER estimates represent real-world data. Indices are calculated in a routine mode. Potential evapotranspiration amounts and the difference between rainfall and potential evapotranspiration are also calculated. The functions adopt a basic time scale that splits each month into four periods. Days 1 to 7, days 8 to 14, days 15 to 21, and days 22 to 28, 29, 30, or 31, where 'TS=4' corresponds to a 1-month length moving window (calculated 4 times per month) and 'TS=48' corresponds to a 12-month length moving window (calculated 4 times per month).

Author(s)

Maintainer: Gabriel Constantino Blain gabriel.blain@sp.gov.br (ORCID)

Authors:

• Graciela R. Sobierajski (ORCID)

• Leticia L. Martins (ORCID)

• Adam H. Sparks adamhsparks@gmail.com (ORCID)

See Also

Useful links:

• https://github.com/gabrielblain/PowerSDI

• Report bugs at https://github.com/gabrielblain/PowerSDI/issues

Verify how well NASA-POWER Data Represent Observed Data

Description

Calculates scalar measures of accuracy.

Usage

Accuracy(obs_est, conf.int = "Yes", sig.level = 0.95)

Arguments

Value

An object of class PowerSDI.Accuracy, a list, which contains:

• Absolute mean error (AME),

• square root of the mean squared error (RMSE),

• Willmott's indices of agreement:

  • original (dorig),

  • modified (dmod) and

  • refined (dref)

• Pearson determination coefficient (R2), and

• if conf.int = "Yes", confidence intervals.

Examples

a <- Accuracy(obs_est = ObsEst, conf.int = "No")
a

# A generic plotting method is also supplied
plot(a)

Parameters for Calculating the SDIs Provided by the ScientSDI Function

Description

Contains parameters of the gamma and GEV distributions and the Pr(Rain = 0), "probzero.rain".

Usage

DistPar

Format

A data.frame with 13 variables and 48 rows.

lon

longitude in decimal degrees

lat

latitude in decimal degrees

quart.month

The quartile of each month

alfa.rain

Shape parameter of the gamma distribution

beta.rain

Scale parameter of the gamma distribution

probzero.rain

Probability of rain=0

loc.harg

Location parameter of the GEV distribution, PE calculated by HS method

sc.harg

Scale parameter of the GEV distribution, PE calculated by HS method

sh.harg

Shape parameter of the GEV distribution, PE calculated by HS method

loc.pm

Location parameter of the GEV distribution, PE calculated by PM method

sc.pm

Scale parameter of the GEV distribution, PE calculated by PM method

sh.pm

Shape parameter of the GEV distribution, PE calculated by PM method

TS

Time scale at which the SDIs will be calculated

Source

Generated by the ScientSDI() function using NASA POWER data.

Examples

data(DistPar)

Example Data of the Input Required by the Accuracy Function

Description

Contains pairs of reference and estimated data.

Usage

ObsEst

Format

A data.frame with 2 variables and 1434 rows.

PE_obs

PE data from a reference weather station

PE_est

PE data from the NASA POWER project

Source

Generated by the PowerSDI package using data from NASA POWER and Agronomic Institute.

Examples

data(ObsEst)

Calculate Routine NASA-SPI and NASA-SPEI Estimates

Description

Calculates the SPI (Standardized Precipitation Index) and SPEI (Standardized Precipitation-Evapotranspiration Index) using NASA POWER data.

Usage

OperatSDI(
  lon,
  lat,
  start.date,
  end.date,
  PEMethod = "HS",
  distr = "GEV",
  parms,
  TS = 4L
)

Arguments

Value

A data frame with six columns

• rainfall,

• potential evapotranspiration (PE),

• difference between rainfall and PE (in millimiters),

• the NASA-SPI,

• the NASA-SPEI and

• the SDI categories corresponding to each indices estimates.

Examples

# This example is not run as it requires data to be downloaded from an API,
#  which may fail.  It also uses data included in this package, "DistPar" for
#  `parms` here

OperatSDI(
  lon = -47.3,
  lat = -22.67,
  start.date = "2023-06-01",
  end.date = "2023-06-30",
  PEMethod = "HS",
  distr = "GEV",
  parms = DistPar,
  TS = 4)

Plot Rainfall and Potential Evapotranspiration Data

Description

Plots rainfall and potential evapotranspiration, both Penman-Monteith and Hargreaves and Samani, amounts using NASA POWER data.

Usage

PlotData(lon, lat, start.date, end.date)

Arguments

Value

No return value, called for side effects. Using this will display scatter plots of rainfall and potential evapotranspiration accumulated at the 1-quart.month time scale in the active R session.

Examples

# This example requires an Internet connection to fetch data and so is only
# run in interactive sessions

PlotData(
  lon = -47.3,
  lat = -22.87,
  start.date = "2021-12-28",
  end.date = "2022-12-31"
)

Calculate the SPI and SPEI Using a Reference Data Source

Description

Calculates the Standardised Precipitation Index (SPI) and Standardised Precipitation-Evapotranspiration Index (SPEI) using a reference data source.

Usage

Reference(ref, distr = "GEV", PEMethod = "HS", TS = 4L)

Arguments

Value

A data frame with five columns

• rain,

• potential evapotranspiration,

• difference between rainfall and potential evapotranspiration,

• SPI calculated at the time scale selected by the user, and

• SPIE calculated at the time scale selected by the user

Examples

Reference(ref = refHS, distr = "GEV", PEMethod = "HS", TS = 4)

Estimate parameters of Gamma, Generalized Extreme Value, or Generalized Logistic Distributions

Description

Verifies concepts expected from SDI. The first step of the SPI and SPEI algorithms is to calculate the cumulative probabilities of their input variables (Guttman 1999). Function estimates the parameters of the gamma, generalized extreme value (GEV), or generalized logistic distributions (GLO) through the L-moments method are provided. This function also allows users to remove suspicious values from the data sample.

Usage

ScientSDI(
  lon,
  lat,
  start.date,
  end.date,
  distr = "GEV",
  TS = 4L,
  Good = "No",
  sig.level = 0.95,
  RainUplim = NULL,
  RainLowlim = NULL,
  PEUplim = NULL,
  PELowlim = NULL
)

Arguments

Value

A list object with data calculated at the time scale selected by the user. If Good = "Yes", this list object includes:

SDI

The “NASA-SPI”, “NASA-SPEI.HS” and “NASA-SPEI.PM.”

DistPar

The parameters of the distributions (gamma and GEV) used to calculate the indices.

GoodFit

The Lilliefors and Anderson-Darling tests goodness-of-fit tests.

Normality

The outcomes of the two normality checking procedures (Wu et al., 2006 and Stagge et al., 2015).

If Good = "No", this list object includes SDI and DistPar.

This function also presents other data (in millimiters) calculated from the NASA POWER project:

• Rainfall amounts (Rain),

• potential evapotranspiration values estimated through the Hargreaves and Samani method (PEHS),

• potential evapotranspiration values estimated through the FAO-56 Penman-Monteith method (PEPM), and

• the difference between rainfall and potential evapotranspiration (PPEHS and PPEPM).

References

Guttman, N.B., 1999. Accepting the standardized precipitation index: a calculation algorithm 1. JAWRA Journal of the American Water Resources Association, 35(2), pp.311-322.

Stagge, J.H., Tallaksen, L.M., Gudmundsson, L., Van Loon, A.F. and Stahl, K., 2015. Candidate distributions for climatological drought indices (SPI and SPEI). International Journal of Climatology, 35(13), pp.4027-4040.

Wu, H., Svoboda, M.D., Hayes, M.J., Wilhite, D.A. and Wen, F., 2006. Appropriate application of the standardized precipitation index in arid locations and dry seasons. International Journal of Climatology: A Journal of the Royal Meteorological Society, 27(1), pp.65-79.

Examples

# This example requires an Internet connection to fetch data and takes >5s
#  to run, and so is only run in interactive sessions

ScientSDI(
  lon = -47.3,
  lat = -22.87,
  start.date = "1993-01-01",
  end.date = "2022-12-31",
  TS = 1,
  Good = "no"
)

Plots PowerSDI.Accuracy Objects

Description

Custom plot() method for PowerSDI.Accuracy objects.

Usage

## S3 method for class 'PowerSDI.Accuracy'
plot(x, ...)

Arguments

Value

No return value, called for side effects. Using this will display a scatter plot of reference ETP data (x-axis) and estimated ETP (y-axis) in the active R session.

Prints PowerSDI.Accuracy Objects

Description

Custom print() method for PowerSDI.Accuracy objects.

Usage

## S3 method for class 'PowerSDI.Accuracy'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

Nothing. Side-effect: pretty prints a PowerSDI.Accuracy object in the R console.

Example of the Input Required by the Reference Function

Description

Contains data for calculating the SPI and SPEI.

Usage

refHS

Format

A data.frame with 10950 rows and 8 variables.

YEAR

Year

MM

Month

DD

Day

tavg

Daily average air temperature at 2 metres above the ground (degrees C)

tmax

Daily maximum air temperature at 2 metres above the ground (degrees C)

tmin

Daily minimum air temperature at 2 metres above the ground (degrees C)

Ra

Daily top of the atmosphere radiation (MJ/m^2/day)

Rain

Daily rainfall amounts (mm)

Source

Agronomic Institute and NASA POWER.

Examples

data(refHS)

Example of the Input Required by the Reference Function

Description

Contains data for calculating the SPI and SPEI.

Usage

refPM

Format

A data.frame with 10958 rows and 11 variables.

YEAR

Year

MM

Month

DD

Day

tavg

Daily average air temperature at 2 metres above the ground (degrees C)

tmax

Daily maximum air temperature at 2 metres above the ground (degrees C)

tmin

Daily minimum air temperature at 2 metres above the ground (degrees C)

Ra

Daily top of the atmosphere radiation (MJ/m^2/day)

Rs

Daily global horizontal irradiance (MJ/m^2/day)

W

Daily average wind speed at 2 metres above the ground (m/s)

RH

Daily average relative humidity at 2 metres above the ground (in percentage)

Rain

Daily rainfall amounts (mm)

Source

Agronomic Institute and NASA POWER.

Examples

data(refPM)