HMMHSMM (version 0.1.0)

conditionalreturnsHSMMgev: Plot Conditional Return Levels from GEV-HSMM

Description

Computes and plots conditional return levels from a fitted Hidden Semi-Markov Model (HSMM) with generalized extreme value (GEV) state-dependent distributions. Bootstrap confidence intervals are included. Return levels are aggregated over user-defined time periods.

Usage

conditionalreturnsHSMMgev(x, HSMM, dwelldist, M = NA,
                          return_periods = c(50, 100, 200, 500),
                          varcov = NULL, B = 10000, level = 0.95,
                          time_structure = NULL, shift = FALSE,
                          plot_title = "Return Levels Over Time",
                          save_plot = FALSE, filename = NULL,
                          width = 12, height = 8, dpi = 300,
                          verbose = TRUE)

Value

Invisibly returns a list containing:

return_levels_states

List of matrices, one per return period, containing estimated return levels and confidence intervals for each state (3 rows: estimate, lower CI, upper CI).

return_levels_time

List of matrices, one per return period, mapping state-specific return levels to the time series.

return_periods

Numeric vector of return periods used.

time_info

List containing time axis information and labels.

A time-series plot is also produced, showing aggregated conditional return levels with bootstrap 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.

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

return_periods

Numeric vector. Return periods (in years) for which conditional return levels are computed. Default is c(50, 100, 200, 500).

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 "Return Levels 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 conditional return level for a given return period 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 return levels are aggregated over time periods defined by time_structure (e.g., years, weeks, months).

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 <- conditionalreturnsHSMMgev(
  x = sim$x, HSMM = HSMM_fit,
  return_periods = c(50, 100, 200, 500),
  dwelldist = "pois", B = 1000,
  time_structure = time_struct,
  plot_title = "GEV-HSMM Conditional Return Levels"
)

result <- conditionalreturnsHSMMgev(
  x = sim$x, HSMM = HSMM_fit,
  return_periods = c(50, 100),
  dwelldist = "pois", B = 1000,
  time_structure = time_struct,
  save_plot = TRUE,
  filename = tempfile(fileext = ".png")
)
# }