# Plot Conditional Return Levels from GEV-HSMM 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. ```r 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) ``` ## 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`. ## Returns 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. ## 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). ## Examples ```r 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 ) 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") ) ``` ## See Also `findmleHSMM`, for fitting HSMMs. `generateHSMM`, for simulating HSMM data. `globaldecodeHSMM`, for decoding the most likely state sequence. `HSMMVarianceMatrix`, for variance–covariance estimation. ## Author(s) Aimee Cody

conditionalreturnsHSMMgev function