Skip to contents

Calculate drought index covariates

Source: R/calculate_covariates.R
calculate_drought.Rd

The calculate_drought() function extracts drought index values at point locations from an object returned by process_drought(). Three source datasets are supported:

  • SPEI / EDDI (SpatRaster): cell values are extracted at each location using the standard raster-extraction pipeline (calc_prepare_locs() -> calc_worker() -> calc_return_locs()). Time column format is "YYYY-MM-DD".

  • USDM (SpatVector polygons): the drought monitor class (DM, integer 0-4) at each location is determined via spatial overlay. A time column of class Date is populated from the date attribute of from.

When .by_time is supplied the extracted result is passed through calc_summarize_by() using the same semantics as all other calculate_*() functions in this package.

Usage

calculate_drought(
  from,
  locs,
  locs_id = "site_id",
  radius = 0L,
  fun = "mean",
  weights = NULL,
  geom = FALSE,
  .by_time = NULL,
  ...
)

Arguments

from

SpatRaster or SpatVector. Output of process_drought().

  • SpatRaster for SPEI or EDDI sources.

  • SpatVector (polygons) for USDM source.

locs

data.frame, character (path to CSV), SpatVector, or sf object. Point locations at which to extract values.

locs_id

character(1). Name of the unique location identifier column in locs. Default "site_id".

radius

integer(1). Circular buffer radius in metres around each site location used for extraction. For SPEI/EDDI this controls raster buffering; for USDM, radius > 0 additionally returns class proportions within the buffer. Default 0L.

fun

character(1). Summary function applied to raster cells within the buffer (SPEI/EDDI only). Default "mean".

weights

NULL, SpatRaster, polygon SpatVector/sf, or file path. Optional weights raster for weighted extraction. If NULL (default), unweighted extraction is performed.

geom

FALSE, "sf", or "terra". Whether to attach geometry to the returned object. Default FALSE.

.by_time

NULL or character(1). Name of the time column to use temporal summarization unit token. NULL disables "time".

...

Reserved for future use; currently ignored.

Value

A data.frame (default) or SpatVector/sf object (when geom is set) with columns:

<locs_id>

Location identifier.

time

Date of the observation (Date or "YYYY-MM-DD" character).

<value_column>

Extracted drought index or class value.

When .by_time is non-NULL, rows are aggregated to the specified resolution via calc_summarize_by().

Note

  • The column name for extracted drought values follows the pattern "<source>_<timescale>_<radius>" (e.g. "spei_01_0") for SPEI/EDDI, and "usdm_dm_0" for USDM.

  • For USDM with radius > 0, proportion columns are added as "usdm_dm_<class>_<radius>" for classes 0–4.

See also

process_drought, download_drought, calc_summarize_by

Author

Insang Song

Examples

if (FALSE) { # \dontrun{
locs <- data.frame(site_id = "001", lon = -97.5, lat = 35.5)
## SPEI example
spei <- process_drought(
  source = "spei",
  path = "./data/drought",
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L
)
calculate_drought(
  from = spei,
  locs = locs,
  locs_id = "site_id",
  radius = 0L,
  fun = "mean"
)
## USDM example
usdm <- process_drought(
  source = "usdm",
  path = "./data/drought",
  date = c("2020-01-07", "2020-03-31")
)
calculate_drought(
  from = usdm,
  locs = locs,
  locs_id = "site_id"
)
} # }