Package {droughtevents}

Title:	Identify and Characterize Drought Events from Drought Index Time Series
Version:	0.1.0
Description:	Detects, describes, and analyzes drought events from time series of drought indices, such as the Standardized Precipitation-Evapotranspiration Index (SPEI). Identifies drought episodes based on threshold values and calculates their duration, intensity, severity, and peak month. Includes utilities for summarizing and visualizing drought dynamics over time. The Standardized Precipitation-Evapotranspiration Index is described in Vicente-Serrano et al. (2010) <doi:10.1175/2009JCLI2909.1>.
License:	MIT + file LICENSE
Encoding:	UTF-8
Suggests:	spelling, testthat (≥ 3.0.0)
Config/testthat/edition:	3
URL:	https://github.com/ajpelu/droughtevents, https://ajpelu.github.io/droughtevents/
BugReports:	https://github.com/ajpelu/droughtevents/issues
Imports:	cli, data.table, dplyr, ggplot2, lubridate, rlang, scales
Depends:	R (≥ 4.1)
LazyData:	true
Config/roxygen2/version:	8.0.0
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-06-25 10:18:05 UTC; ajpelu
Author:	Antonio Jesus Perez-Luque [cre, aut, cph]
Maintainer:	Antonio Jesus Perez-Luque <ajpelu@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-30 20:00:06 UTC

Add drought period (bands or markers) to a spei time series plot

Description

Adds shaded polygons, vertical lines, or both to a ggplot object to highlight drought events, based on a drought assessment summary (as returned by droughts()). Optionally, labels or points can be added to indicate drought severity.

Usage

add_drought_events(
  p,
  drought_assessment,
  which_events = c("all", "top"),
  metric = c("duration", "severity", "intensity", "lowest_index"),
  top_n = 5,
  type = c("line", "polygon", "both"),
  line_col = "black",
  line_type = "dashed",
  pol_fill = "gray70",
  pol_alpha = 0.5,
  show_severity = FALSE
)

Arguments

Value

A modified ggplot object.

Examples

data(spei_granada)

result <- droughts(spei_granada, vname = "spei12", threshold = -1.28)

p <- plot_drought_ts(spei_granada, vname = "spei12")

add_drought_events(
  p,
  drought_assessment = result$drought_assessment,
  which_events = "top",
  metric = "severity",
  top_n = 3,
  type = "both",
  show_severity = TRUE
)

Detect and summarize drought events from SPEI droughts index time series

Description

Identifies drought events in a time series when a given index (e.g., SPEI) falls below a specified threshold for at least two consecutive months. Returns the processed dataset, the detected drought events, and a summary of their characteristics.

Usage

droughts(df, vname, threshold, min_duration = 2)

Arguments

Value

A named list with three elements:

• data: the original data frame with drought flags and durations.

• drought_events: only the rows that are part of drought events (duration >= min_duration).

• drought_assessment: summary of each event, including duration, intensity, severity, and timing.

Examples

data(spei_granada)
# Detect droughts in the SPEI-12 time series with a threshold of -1.28
droughts_result <- droughts(spei_granada, vname = "spei12", threshold = -1.28)

Plot Drought Index Time Series with Positive/Negative Bars

Description

Creates a bar plot of a drought-related time series (e.g., SPEI or SPI), where values above and below zero are colored differently. Optionally, the time series can be aggregated and displayed by year.

Usage

plot_drought_ts(
  df,
  vname,
  title = NULL,
  date_col = "date",
  pos_color = "blue",
  neg_color = "red",
  zero_line_color = "black",
  zero_line_linetype = "solid",
  by_year = FALSE,
  y_axis_title = NULL
)

Arguments

Details

This plot is useful for visualizing the temporal dynamics of drought indices, highlighting positive (wet) and negative (dry) periods. When by_year = TRUE, the function averages the index per year and plots one bar per year.

Value

A ggplot object representing the drought index time series as a bar plot.

See Also

droughts()

Examples

data(spei_granada)
plot_drought_ts(spei_granada, vname = "spei12", title = "SPEI-12 Time Series")
plot_drought_ts(spei_granada, vname = "spei12", title = "SPEI-12 Annual Mean", by_year = TRUE)

SPEI time series for Granada

Description

Standardised Precipitation-Evapotranspiration Index (SPEI) time series for Granada, Spain (coordinates -3.75, 37.25), at four different time scales (6, 12, 24, and 48 months). SPEI is a multi-scalar drought index that combines precipitation and evapotranspiration data; negative values indicate drier-than-average conditions, positive values indicate wetter-than-average conditions.

Note that the longer time scales (spei12, spei24, spei48) require that many months of prior data to be computed, so they contain NaN values at the start of the series.

Usage

spei_granada

Format

A data frame (tibble) with 1,483 rows and 5 columns:

date

Date of the observation (class Date), monthly from 1901-06-16 to 2024-12-16.

spei6

SPEI at the 6-month time scale.

spei12

SPEI at the 12-month time scale. NaN for the first months of the series.

spei24

SPEI at the 24-month time scale. NaN for the first months of the series.

spei48

SPEI at the 48-month time scale. NaN for the first months of the series.

Value

A tibble with 1,483 rows and 5 columns, as described in ⁠@format⁠.

Source

https://spei.csic.es/spei_database/

References

Vicente-Serrano, S.M., Beguería, S., López-Moreno, J.I. (2010). A Multi-scalar Drought Index Sensitive to Global Warming: The Standardized Precipitation Evapotranspiration Index. Journal of Climate, 23(7), 1696-1718. doi:10.1175/2009JCLI2909.1

Examples

data(spei_granada)
tail(spei_granada)

# Detect drought events using the 12-month SPEI
droughts(spei_granada, vname = "spei12", threshold = -1.28)