Package 'PowerSDI'

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

obs_est	A 2-column matrix. The reference or observed and the estimated or predicted data. See ObsEst object as an example.
conf.int	A character variable (Yes or No) defining if the function must calculate confidence intervals. Default is “Yes”.
sig.level	A numeric variable (between 0.90 and 0.95) defining the significance level for parameter the confidence intervals. Default is 0.95.

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

lon	longitude in decimal degrees.
lat	latitude in decimal degrees.
start.date	Date at each time when the calculation must start (“YYYY-MM-DD”).
end.date	Date at each time when the calculation must end (“YYYY-MM-DD”).
PEMethod	A character variable (“HS” (Hargreaves & Samani) or “PM” (Penman-Monteith) defining the potential evapotranspiration method. Default is “HS”.
distr	A character variable (“GEV” or “GLO”) defining which distribution is used to calculate the SPEI. Default is “GEV” (generalized extreme value) with “GLO” (generalized logistic distributions) as an option.
parms	Parameters required for calculating the SPI and SPEI. It is provided by the ScientSDI function's DistPar.
TS	Time scale on the “quart.month” basis (integer values between 1 and 96).

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)

---

Plots PowerSDI.Accuracy Objects

Description

Custom plot() method for PowerSDI.Accuracy objects.

Usage

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

Arguments

x	a 'PowerSDI.Accuracy' object
...	Other parameters as passed to plot()

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.

---

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

lon	longitude in decimal degrees: (+) Eastern Hemisphere (-) Western Hemisphere.
lat	latitude in decimal degrees: (+) Northern Hemisphere (-) Southern Hemisphere.
start.date	date at which the indices estimates should start ("YYYY-MM-DD").
end.date	date at which the indices estimates should end ("YYYY-MM-DD").

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"
)

---

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

x	a PowerSDI.Accuracy object
digits	The number of digits to be used after the decimal when displaying accuracy values.
...	ignored

Value

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

---

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

ref	A data frame with the variables required for calculating the SDIs. See refHS or refPM as examples.
distr	A character variable (“GEV” or “GLO”) defining which distribution is used to calculate the SPEI. Default is “GEV”.
PEMethod	A character variable (“HS” or “PM”) defining the potential evapotranspiration method. Default is “HS”.
TS	Time scale on the “quart.month” basis (whole values between 1 and 96). Default is 4.

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)

---

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)

---

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

lon	longitude in decimal degrees: (+) Eastern Hemisphere, (-) Western Hemisphere.
lat	latitude in decimal degrees: (+) Northern hemisphere, (-) Southern Hemisphere.
start.date	date at which the indices estimates should start. Format: “YYYY-MM-DD”.
end.date	date at which the indices estimates should end. Format: “YYYY-MM-DD”.
distr	A character variable (“GEV” or “GLO”) defining the distribution to calculate the SPEI. Default is GEV.
TS	Time scale on the quart.month basis (integer values between 1 and 96). Default is 4.
Good	A character variable ("Yes" or "No") to calculate or not the goodness-of-fit and normality tests. Default is "No".
sig.level	A numeric variable (between 0.90 and 0.95) defining the significance level for parameter Good. Default is "0.95".
RainUplim	Optional. Upper limit in millimetres from which rainfall values larger than it will be removed. Default is NULL.
RainLowlim	Optional. Lower limit in millimetres from which rainfall values smaller than it will be removed. Default is NULL.
PEUplim	Optional. Upper limit in millimetres from which evapotranspiration values larger than it will be removed. Valid for Hargreaves and Samani method Default is NULL.
PELowlim	Optional. Lower limit in millimetres from which evapotranspiration values smaller than it will be removed. Valid for Hargreaves and Samani method Default is NULL.

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"
)

---