Package ‘SPEI’
June 7, 2017
Type Package
Version 1.7
Date 2017-06-07
Title Calculation of the Standardised Precipitation-Evapotranspiration
Index
Description
A set of functions for computing potential evapotranspiration and several widely used drought in-
dices including the Standardized Precipitation-Evapotranspiration Index (SPEI).
Depends lmomco, parallel, ggplot2
License GPL-2
URL http://sac.csic.es/spei
LazyLoad yes
Encoding UTF-8
NeedsCompilation no
Author Santiago Beguería [aut, cre],
Sergio M. Vicente-Serrano [aut]
Maintainer Santiago Beguería
Repository CRAN
Date/Publication 2017-06-07 17:24:09 UTC
.
.
R topics documented:
2
.
.
SPEI-package .
.
3
.
.
Datasets .
.
.
4
Drought indices .
.
.
Generalized Logistic .
9
Generic methods for spei objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Kernel functions .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Potential evapotranspiration .
SPEINews .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Index
16
1
2
SPEI-package
SPEI-package
Calculation of the Standardised Precipitation-Evapotranspiration In-
dex
Description
A set of functions for computing potential evapotranspiration and several widely used drought in-
dices including the Standardized Precipitation-Evapotranspiration Index (SPEI).
Details
Functions spei and spi are the workhorse of the SPEI library. Other functions such as kern,
cdfglo or pglo are auxiliary low-level functions and they will not be used directly by the typical
user. Functions for computing potential evapotranspiration are provided, too, for helping computing
the SPEI. They are: thornthwaite, hargreaves and penman.
Version history:
1.4. Minor fixes to functions penman and pwm. Documentation of the penman function defined by
mistake ed as the saturation vapour pressure, while it should read ’actual vapour pressure’. Function
zzz.R added to display basic information about the SPEI package at startup. Function SPEINews
added to display the NEWS file.
1.3. Minor fixes to spei and penman functions. New option for user-supplied SPEI parameters in
the spei function. New dataset cabinda.
1.2. A bug causing several functions to fail when a time series not belonging to matrix class was
provided was fixed. Function plot.spei now distinguises between calls to spei and spi and labels
the axis accordingly .
1.1. Functions spei and spi now yield an object of class "spei". New functions for summarizing
and plotting "spei" objects are provided. An option to establish a reference period for the computa-
tion of the indices has been implemented in functions spei and spi.
1.0. First release.
Author(s)
Santiago Beguería and Sergio M. Vicente-Serrano Maintainer: Santiago Beguería
References
S.M. Vicente-Serrano, S. Beguería, J.I. López-Moreno. 2010. A Multi-scalar drought index sensi-
tive to global warming: The Standardized Precipitation Evapotranspiration Index – SPEI. Journal
of Climate 23: 1696, DOI: 10.1175/2009JCLI2909.1.
http://sac.csic.es/spei/
Datasets
3
Datasets
Datasets for illustrating the functions in the SPEI package.
Description
Data used in the examples of the SPEI package: wichita dataset: monthly climate in Wichita
(Kansas, lat=37.6475, elevation=402.6 m. a.s.l.) since January 1980; balance dataset: monthly
climatic water balance (precipitation minus potential evapotranspiration) at eleven locations around
the World, since January 1900; cabinda: one year of data for computing Penman-Monteith ET0
from Allen et al. (1998).
Usage
data(wichita)
data(balance)
data(cabinda)
Format
wichita dataset:
YEAR monthly precipitation totals, in mm.
MONTH monthly precipitation totals, in mm.
PRCP monthly precipitation totals, in mm.
TMAX monthly mean daily maximum temperature, in ºC.
TMIN monthly mean daily minimum temperature, in ºC.
TMED monthly mean temperature, in ºC.
AWND monthly mean wind speed, in km h-1
ACSH monthly mean sun hours, in h.
ACSH monthly mean cloud cover, in %.
balance dataset: monthly climatic water balance (precipitation minus potential evapotranspira-
tion) at Indore (India), Kimberley (South Africa), Albuquerque (US), Valencia (Spain), Wien (Aus-
tria), Abashiri (Japan), Tampa (US), Sao Paulo (Brasil), Lahore (India), Punta Arenas (Chile) and
Helsinki (Finland), in mm.
cabinda dataset: one year of monthly climatic data at Cabinda (Angola, -5.33S 12.11E 20 m),
taken from Allen et al. (1998), page 69, figure 18:
mon month of the year
Tmin monthly mean daily minimum temperature, in ºC.
Tmax monthly mean daily maximum temperature, in ºC.
RH monthly mean relative humidity, in %.
U2 monthly mean wind speed, in km h-1
tsun monthly mean sunshine hours, in h.
Rs monthly mean dialy incoming solar radiation, MJ m-2 d-1.
ET0 monthly ET0 from the original publication, in mm.
4
Author(s)
Data ported to R by S. Beguería.
Source
Drought indices
The wichita data were obtained from the Global Historical Climatology Network (GHCN, https:
//www.ncdc.noaa.gov/data-access/land-based-station-data/land-based-datasets/global-historical-climatology-network-ghcn.
Data for the balance dataset were extracted from CRU TS V3.1 and from the 20th Century Reanal-
ysis V2 dataset. Data for the balance dataset were taken from Allen et al. (1998), page 69, figure
18.
References
S.M. Vicente-Serrano, S. Beguería, J.I. López-Moreno. 2010. A Multi-scalar drought index sensi-
tive to global warming: The Standardized Precipitation Evapotranspiration Index – SPEI. Journal
of Climate 23: 1696, DOI: 10.1175/2009JCLI2909.1. R.G. Allen, L.S. Pereira, D. Raes, M. Smith.
1998. JCrop evapotranspiration - Guidelines for computing crop water requirements - FAO Irriga-
tion and drainage paper 56. FAO, Rome. ISBN 92-5-104219-5.
Examples
data(wichita)
names(wichita)
summary(wichita)
data(balance)
summary(balance)
Drought indices
Calculation of the Standardized Precipitation-Evapotranspiration In-
dex (SPEI) and the Standardized Precipitation Index (SPI).
Description
Given a time series of the climatic water balance (precipitation minus potential evapotranspiration),
gives a time series of the Standardized Precipitation-Evapotranspiration Index (SPEI).
Usage
spei(data, scale, kernel = list(type = ’rectangular’, shift = 0),
distribution = ’log-Logistic’, fit = ’ub-pwm’, na.rm = FALSE,
ref.start=NULL, ref.end=NULL, x=FALSE, params=NULL, ...)
spi(data, scale, kernel = list(type = ’rectangular’, shift = 0),
distribution = ’Gamma’, fit = ’ub-pwm’, na.rm = FALSE,
ref.start=NULL, ref.end=NULL, x=FALSE, params=NULL, ...)
Drought indices
Arguments
data
scale
kernel
distribution
fit
na.rm
ref.start
ref.end
x
params
...
Details
5
a vector, matrix or data frame with time ordered values of precipitation (for the
SPI) or of the climatic balance precipitation minus potential evapotranspiration
(for the SPEI).
an integer, representing the time scale at which the SPEI / SPI will be computed.
optional, a list defining the type of kernel used for computing the SPEI / SPI at
scales higher than one. Defaults to unshifted rectangular kernel.
optional, name of the distribution function to be used for computing the SPEI /
SPI (one of ’log-Logistic’, ’Gamma’ and ’PearsonIII’). Defaults to ’log-Logistic’
for spei, and to ’Gamma’ for spi.
optional, name of the method used for computing the distribution function pa-
rameters (one of ’ub-pwm’, ’pp-pwm’ and ’max-lik’). Defaults to ’ub-pwm’.
optional, a logical value indicating whether NA values should be stripped from
the computations. Defaults to FALSE, i.e. no NA are allowed in the data.
optional, starting point of the reference period used for computing the index.
Defaults to NULL, indicating that the first value in data will be used as starting
point.
optional, ending point of the reference period used for computing the index.
Defaults to NULL, indicating that the last value in data will be used as ending
point.
optional, a logical value indicating wether the data used for fitting the model
should be kept. Defaults to FALSE.
optional, an array of parameters for computing the spei. This option overrides
computation of fitting parameters.
other possible parameters.
The spei and spi functions allow computing the SPEI and the SPI indices. These are climatic
proxies widely used for drought quantification and monitoring. Both functions are identical (in
fact, spi is just a wrapper for spei), but they are kept separated for clarity. Basically, the functions
standardize a variable following a log-Logistic (or Gamma, or PearsonIII) distribution function (i.e.,
they transform it to a standard Gaussian variate with zero mean and standard deviation of one).
Input data: The input variable is a time ordered series of precipitation values for spi, or a
series of the climatic water balance (precipitation minus potential evapotranspiration) for spei.
When used with the default options, it would yield values of both indices exactly as defined in the
references given below.
The SPEI and the SPI were defined for monthly data. Since the PDFs of the data are not ho-
mogenous from month to month, the data is split into twelve series (one for each month) and
independent PDFs are fit to each series. If data is a vector or a matrix it will be treated as a
sequence of monthly values starting in January. If it is a (univariate or multivariate) time series
then the function cycle will be used to determine the position of each observation within the year
(month), allowing the data to start in a month other than January.
6
Drought indices
Time scales: An important advantage of the SPEI and the SPI is that they can be computed at
different time scales. This way it is possible to incorporate the influence of the past values of
the variable in the computation enabling the index to adapt to the memory of the system under
study. The magnitude of this memory is controlled by parameter scale. For example, a value
of six would imply that data from the current month and of the past five months will be used
for computing the SPEI or SPI value for a given month. By default all past data will have the
same weight in computing the index, as it was originally proposed in the references below. Other
kernels, however, are available through parameter kernel. The parameter kernel is a list defining
the shape of the kernel and a time shift. These parameters are then passed to the function kern.
Probability distributions: Following the original definitions spei uses a log-Logistic distribu-
tion by default, and spi uses a Gamma distribution. This behaviour can be modified, however,
through parameter distribution.
Fitting methods: The default method for parameter fitting is based on unbiased Probability
Weighted Moments (’ub-pwm’), but other methods can be used through parameter fit. A valid
alternative is the plotting-position PWM (’pp-pwm’) method. For the log-Logistic distribution,
also the maximum likelihood method (’max-lik’) is available.
User-provided parameters: An option exists to override parameter fitting and provide user
default parameters. This is activated with the parameter params. The exact values provided tothis
parameter depend on the distribution function being used. For log-Logistic and PearsonII it should
be a three-dimensional array with dimensions (3,number of series in data,12), containing twelve
parameter triads (xi, alpha, kappa) for each data series, one for each month. For Gamma, a three-
dimensional array with dimensions (2,number of series in data,12), containing twelve parameter
pairs (alpha, beta). It is a good idea to look at the coefficients slot of a previously fit spei spei
object in order to understand the structure of the parameter array. The parameter distribution
is still used under this option in order to know what distribution function should be used.
Reference period: The default behaviour of the functions is using all the values provided in
data for parameter fitting. However, this can be modified with help of parameters ref.start
and ref.end. These parameters allow defining a subset of values that will be used for parameter
fitting, i.e. a reference period. The functions, however, will compute the values of the indices for
the whole data set. For these options to work it is necessary that data will be a time series object.
The starting and ending points of the reference period will then be defined as pairs of year and
month values, e.g. c(1900,1).
Processing large datasets:
It is possible to use the spei and spi functions for processing mul-
tivariate datasets at once. If a matrix or data frame is supplied as data, with time series of precip-
itation or precipitation minus potential evapotranspiration arranged in columns, the result would
be a matrix (data frame) of spi or spei series. This makes processing large datasets extremely easy,
since no loops need to be used.
Value
Functions spei and spi return an object of class spei. The generic functions print and summary
can be used to obtain summaries of the results. The generic accessor functions coefficients and
fitted extract useful features of the object.
An object of class spei is a list containing at least the following components:
Drought indices
7
call: the call to spei or spi used to generate the object.
fitted: time series with the values of the Standardized Precipitation-Evapotranspiration Index (SPEI)
or the Standardized Precipitation Index (SPI). If data consists of several columns the function will
treat each column as independent data, and the result will be a multivariate time series. The names
of the columns in data will be used as column names in fitted.
coefficients: an array with the values of the coefficients of the distribution function fitted to the
data. The first dimension of the array contains the three (or two) coefficients, the second dimension
will typically consist of twelve values corresponding to each month, and the third dimension will
be equal to the number of columns (series) in data. If a time scale greater than one has been used
then the first elements will have NA value since the kernel can not be applied. The first element
with valid data will be the one corresponding to the time scale chosen.
scale: the scale parameter used to generate the object.
kernel: the parameters and values of the kernel used to generate the object.
distribution: the distribution function used to generate the object.
fit: the fitting method used to generate the object.
na.action: the value of the na.action parameter used.
data: if requested, the input data used.
Note
Dependencies: the spei function depends on the library lmomco.
Author(s)
Santiago Beguería and Sergio M. Vicente-Serrano. Maintainer: Santiago Beguería.
References
S.M. Vicente-Serrano, S. Beguería, J.I. López-Moreno. 2010. A Multi-scalar drought index sensi-
tive to global warming: The Standardized Precipitation Evapotranspiration Index – SPEI. Journal
of Climate 23: 1696, DOI: 10.1175/2009JCLI2909.1.
Beguería S, Vicente-Serrano SM, Reig F, Latorre B. 2014. Standardized precipitation evapotran-
spiration index (SPEI) revisited: parameter fitting, evapotranspiration models, tools, datasets and
drought monitoring. International Journal of Climatology 34(10): 3001-3023.
http://sac.csic.es/spei/
See Also
kern for different kernel functions available. thornthwaite, hargreaves and penman for ways of
calculating potential evapotranspiration. summary.spei and print.spei for summaries of spei
objects. plot.spei for plotting spei objects.
8
Examples
# Load data
data(wichita)
Drought indices
# Compute potential evapotranspiration (PET) and climatic water balance (BAL)
wichita$PET <- thornthwaite(wichita$TMED, 37.6475)
wichita$BAL <- wichita$PRCP-wichita$PET
# Convert to a ts (time series) object for convenience
wichita <- ts(wichita[,-c(1,2)], end=c(2011,10), frequency=12)
plot(wichita)
# One and tvelwe-months SPEI
spei1 <- spei(wichita[,’BAL’], 1)
spei12 <- spei(wichita[,’BAL’], 12)
class(spei1)
# Extract information from spei object: summary, call function, fitted values, and coefficients
summary(spei1)
names(spei1)
spei1$call
spei1$fitted
spei1$coefficients
# Plot spei object
par(mfrow=c(2,1))
plot(spei1, main=’Wichita, SPEI-1’)
plot(spei12, main=’Wichita, SPEI-12’)
# One and tvelwe-months SPI
spi_1 <- spi(wichita[,’PRCP’], 1)
spi_12 <- spi(wichita[,’PRCP’], 12)
par(mfrow=c(2,1))
plot(spi_1, ’Wichita, SPI-1’)
plot(spi_12, ’Wichita, SPI-12’)
# Time series not starting in January
par(mfrow=c(1,1))
plot(spei(ts(wichita[,’BAL’], freq=12, start=c(1980,6)), 12))
# Using a particular reference period (1980-2000) for computing the parameters
plot(spei(ts(wichita[,’BAL’], freq=12, start=c(1980,6)), 12,
ref.start=c(1980,1), ref.end=c(2000,1)))
# Using different kernels
spei24 <- spei(wichita[,’BAL’],24)
spei24_gau <- spei(wichita[,’BAL’], 24, kernel=list(type=’gaussian’, shift=0))
par(mfrow=c(2,1))
plot(spei24, main=’SPEI-24 with rectangular kernel’)
plot(spei24_gau, main=’SPEI-24 with gaussian kernel’)