plotHSMMParameters: Plot Hidden Semi-Markov Model Parameters Over Time

Description

Plots state-dependent observation parameters and dwell-time parameters of a fitted Hidden Semi-Markov Model (HSMM) over time. Confidence intervals can be included, with optional overlay of observed data for comparison.

Usage

plotHSMMParameters(x, HSMM, obsdist, dwelldist, confint_result = NULL,
                   level = 0.95, B = 100, M = NA, include_dwell = FALSE,
                   shift = FALSE, time_structure = NULL,
                   plot_title = "HSMM Parameters Over Time",
                   overlay_data = NULL, overlay_label = "Data",
                   colors = c("black", "red", "blue", "darkgreen"),
                   save_plot = FALSE, filename = NULL,
                   width = 12, height = 8, dpi = 300,
                   verbose = TRUE, seed = NULL)

Value

Invisibly returns a list containing:

obs_param_series: List of observation parameter time series for each parameter.
obs_ci_series: List of confidence interval time series (lower and upper bounds) for each observation parameter.
dwell_param_series: List of dwell parameter time series for each parameter (if include_dwell = TRUE).
dwell_ci_series: List of confidence interval time series for each dwell parameter (if include_dwell = TRUE).
time_info: List containing time axis information and labels.
decoded_states: Vector of decoded hidden states for each time point.

The function also generates multi-panel plots of parameter trajectories with confidence intervals and optional overlays.

Arguments

x: Numeric vector. The observed data sequence.
HSMM: A fitted HSMM object (typically the output from findmleHSMM), containing estimated transition probabilities Pi, initial probabilities delta, state-dependent observation parameters observationparameters, and dwell-time parameters dwellparameters.
obsdist: Character string. Observation distribution. Supported: "norm", "pois", "weibull", "zip", "nbinom", "zinb", "exp", "gamma", "lnorm", "gev", "ZInormal", "ZIgamma".
dwelldist: Character string. Dwell-time distribution. Supported: "pois", "nbinom", "geom", "betabinom".
confint_result: Optional result from confintHSMM. If not provided, confidence intervals are computed internally.
level: Numeric between 0 and 1. Confidence level for parameter intervals. Default is 0.95.
B: Integer. Number of bootstrap replicates for confidence intervals if not supplied. Default is 100.
M: Integer. Maximum dwell time used in decoding. Defaults to min(1000, length(x)) if NA.
include_dwell: Logical. If TRUE, the dwell parameters will also be plotted through time. Default is FALSE.
shift: Logical. If TRUE, fits shifted dwell-time distributions. Default is FALSE.
time_structure: Optional list specifying the time scale. Must include unit, observations_per_unit, and optionally start_point, end_point. Supports calendar units ("day", "year", "hour") or custom scaling.
plot_title: Character string. Title for the full plot layout. Default is "HSMM Parameters Over Time".
overlay_data: Optional numeric vector of length length(x). External data to overlay on parameter plots.
overlay_label: Character string. Label for overlay axis. Default is "Data".
colors: Character vector of plot colors. Default is c("black", "red", "blue", "darkgreen").
save_plot: Logical. If TRUE, the plot is saved to a file. Default is FALSE.
filename: Character string. File path for saving the plot. Required if save_plot = TRUE.
width: Numeric. Width of saved plot in inches. Default is 12.
height: Numeric. Height of saved plot in inches. Default is 8.
dpi: Numeric. Resolution (dots per inch) for saved plot. Default is 300.
verbose: Logical. If TRUE, progress messages are printed to the console. Default is TRUE.
seed: Integer or NULL. Random seed for reproducibility. Default is NULL.

Author

Aimee Cody

Details

The most likely hidden state sequence is decoded using globaldecodeHSMM. For each decoded state, observation and dwell-time parameters are extracted and plotted over time. If confint_result is not provided, bootstrap intervals are computed via confintHSMM. Plots include observation parameter trajectories, dwell-time parameter trajectories (if include_dwell = TRUE), and optional overlay data on secondary axes. Time scaling is configurable using time_structure. When verbose = TRUE, progress messages are displayed during confidence interval computation. If save_plot = TRUE, the plot is saved as a PNG file to the specified filename with the given dimensions and resolution.

Examples

Run this code

set.seed(42)
J <- 2
Pi <- matrix(c(0.0, 1.0,
               1.0, 0.0), nrow = J, byrow = TRUE)

obspar <- list(mean = c(0, 3), sd = c(1, 1.2))
dwellpar <- list(lambda = c(5, 8))

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

HSMM_fit <- findmleHSMM(x = sim$x, J = J, M = 100,
                        obsdist = "norm", dwelldist = "pois",
                        obspar = obspar, dwellpar = dwellpar,
                        Pi = Pi)

overlay_series <- sim$x
time_struct <- list(unit = "day", observations_per_unit = 10, start_point = 1)

# \donttest{
result <- plotHSMMParameters(x = sim$x, HSMM = HSMM_fit,
                             obsdist = "norm", dwelldist = "pois",
                             overlay_data = overlay_series,
                             overlay_label = "Observed values",
                             time_structure = time_struct,
                             plot_title = "HSMM Parameters with Overlay")

result_silent <- plotHSMMParameters(x = sim$x, HSMM = HSMM_fit,
                                    obsdist = "norm", dwelldist = "pois",
                                    include_dwell = TRUE,
                                    overlay_data = overlay_series,
                                    time_structure = time_struct,
                                    verbose = FALSE)
# }

Run the code above in your browser using DataLab