Package 'droughtevents'

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

p	A ggplot object created by plot_drought_ts().
drought_assessment	A data frame with columns minyear, month_peak, d_duration, d_severity, and others, as returned by droughts().
which_events	Display "all" droughts or only the "top" events.
metric	If which_events = "top", use this column to rank events. Options: "duration", "severity", "intensity", "lowest_index".
top_n	Number of top events to display when which_events = "top". Default to 5.
type	Type of marker to display: "polygon" (shaded bands), "line" (vertical lines at peak), or "both".
line_col	Color of vertical line (if used).
line_type	Line type of vertical line (e.g. "dashed", "solid").
pol_fill	Fill color of polygon (if used).
pol_alpha	Transparency of polygon fill.
show_severity	Logical. If TRUE, plots a point and label for severity at top of each event.

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

df	A data.frame or tibble containing the time series data. Must include either: a date column of class Date or POSIXct, or separate year and month columns. a numeric column specified by vname that contains the drought index values.
vname	A string indicating the name of the numeric column to be evaluated (e.g., "spei12").
threshold	A numeric threshold below which values are considered part of a drought event.
min_duration	Minimum number of consecutive months below threshold required for an event to be considered a drought. Default is 2.

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

df	A data.frame or tibble containing the time series data.
vname	A string. Name of the numeric column representing the drought index.
title	An optional character string for the plot title.
date_col	A string. Name of the column containing date information (default is "date").
pos_color	Color used for positive values (default is "blue").
neg_color	Color used for negative values (default is "red").
zero_line_color	Color of the horizontal line at zero (default is "black").
zero_line_linetype	Line type for the horizontal zero line (default is "solid").
by_year	Logical. If TRUE, aggregates the drought index by year and plots annual means (default is FALSE).
y_axis_title	Optional label for the y-axis. If NULL, the name of vname is used.

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)

---