HMMHSMM (version 0.1.0)

exceedanceplotHSMMgev: Plot Exceedance Probabilities from GEV-HSMM

Description

Computes and plots exceedance probabilities of a given threshold from a fitted Hidden Semi-Markov Model (HSMM) with generalized extreme value (GEV) state-dependent distributions. Bootstrap confidence intervals are included. Probabilities are aggregated over user-defined time periods.

Usage

exceedanceplotHSMMgev(x, HSMM, threshold, dwelldist, M = NA,
                      varcov = NULL, B = 10000, level = 0.95,
                      time_structure = NULL, shift = FALSE,
                      plot_title = "Exceedance Probabilities Over Time",
                      save_plot = FALSE, filename = NULL,
                      width = 12, height = 8, dpi = 300,
                      verbose = TRUE)

Value

Invisibly returns a list containing:

exceedance_probs

Matrix of exceedance probabilities over time (3 rows: estimate, lower CI, upper CI).

time_info

List containing time axis information and labels.

decoded_states

Vector of decoded hidden states for each time point.

time_unit

Number of observations per aggregation period.

threshold

The threshold value used.

A time-series plot is also produced, showing aggregated exceedance probabilities with confidence intervals.

Arguments

x

Numeric vector. The observed data sequence.

HSMM

A fitted HSMM object (output from findmleHSMM), with state-dependent GEV parameters loc, scale, shape, dwell parameters, and estimated transition probabilities.

threshold

Numeric. The exceedance threshold. Probabilities of exceeding this value are computed.

dwelldist

Character string. The dwell-time distribution used in the HSMM, e.g. "pois", "nbinom", or "betabinom".

M

Optional integer. Truncation parameter for dwell-time distribution. Default is NA (no truncation).

varcov

Optional variance–covariance matrix of parameter estimates. If NULL, computed internally via HSMMVarianceMatrix with obsdist = "gev".

B

Integer. Number of bootstrap replicates used for confidence intervals. Default is 10000.

level

Numeric between 0 and 1. Confidence level for intervals. Default is 0.95.

time_structure

Optional list describing the time scale. Includes unit, observations_per_unit, and optionally start_point, end_point. Supported units: "year", "day", "hour", "week", "month", or "custom" with conversion_factor and unit_name.

shift

Logical. If TRUE, uses shifted dwell-time distributions. Default is FALSE.

plot_title

Character string. Title for the plot. Default is "Exceedance Probabilities Over Time".

save_plot

Logical. If TRUE, the plot is saved to file. Default is FALSE.

filename

Character string or NULL. Filename for saved plot (if save_plot = TRUE). Must be specified when save_plot = TRUE. Default is NULL.

width

Numeric. Width of saved plot in inches. Default is 12.

height

Numeric. Height of saved plot in inches. Default is 8.

dpi

Integer. Resolution of saved plot in dots per inch. Default is 300.

verbose

Logical. If TRUE, progress messages are printed to the console. Default is TRUE.

Author

Aimee Cody

Details

For each state, the exceedance probability of threshold is computed from the fitted GEV parameters. Uncertainty is estimated by parametric bootstrap using draws from a multivariate normal approximation of parameter estimates. Observation-level probabilities are aggregated over time periods defined by time_structure (e.g., years, months, weeks). When verbose = TRUE, progress messages are displayed during computation.

See Also

findmleHSMM, for fitting HSMMs. generateHSMM, for simulating HSMM data. globaldecodeHSMM, for decoding the most likely state sequence. HSMMVarianceMatrix, for variance–covariance estimation.

Examples

set.seed(123)

J <- 2
Pi <- matrix(c(0, 1,
               1, 0), nrow = J, byrow = TRUE)
delta <- c(0.5, 0.5)

obspar <- list(
  loc   = c(0, 5),
  scale = c(1, 2),
  shape = c(0.1, -0.1)
)

dwellpar <- list(lambda = c(5, 10))

sim <- generateHSMM(
  n = 200, J = J, obsdist = "gev", dwelldist = "pois",
  obspar = obspar, dwellpar = dwellpar, Pi = Pi, delta = delta
)

HSMM_fit <- findmleHSMM(
  x = sim$x, J = J, obsdist = "gev", dwelldist = "pois",
  obspar = obspar, dwellpar = dwellpar, Pi = Pi, delta = delta
)

time_struct <- list(
  unit = "week", observations_per_unit = 10, start_point = 1
)

# \donttest{
result <- exceedanceplotHSMMgev(
  x = sim$x, HSMM = HSMM_fit,
  threshold = 20, dwelldist = "pois",
  B = 10000, time_structure = time_struct,
  plot_title = "GEV-HSMM Exceedance Probabilities"
)

result <- exceedanceplotHSMMgev(
  x = sim$x, HSMM = HSMM_fit,
  threshold = 20, dwelldist = "pois",
  B = 10000, time_structure = time_struct,
  save_plot = TRUE,
  filename = tempfile(fileext = ".png"),
  verbose = FALSE
)
# }