# Plot Hidden Markov Model Parameters Over Time Plots the estimated state-dependent parameters of a fitted Hidden Markov Model (HMM) over time. Confidence intervals can be included, along with optional overlay of observed data for visual comparison. ```r plotHMMParameters(x, HMM, obsdist, confint_result = NULL, level = 0.95, B = 100, time_structure = NULL, plot_title = "HMM Parameters Over Time", overlay_data = NULL, overlay_label = "Data", colors = c("black", "red", "blue", "green"), save_plot = FALSE, filename = NULL, width = 12, height = 8, dpi = 300, verbose = TRUE, seed=NULL) ``` ## Arguments - `x`: Numeric vector. The observed data sequence. - `HMM`: A fitted HMM object (typically the output from `findmleHMM`), containing estimated transition probabilities `Pi`, initial probabilities `delta`, and state-dependent observation parameters. - `obsdist`: Character string. Observation distribution. Supported distributions include: "norm", "pois", "weibull", "zip", "nbinom", "zinb", "exp", "gamma", "lnorm", "gev", "ZInormal", "ZIgamma". - `confint_result`: Optional result from `confintHMM`. 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 used when computing confidence intervals (if not supplied). Default is 100. - `time_structure`: Optional list specifying the time scale for plotting. May include `unit`, `observations_per_unit`, and optional `start_point`, `end_point`. Supports calendar units (e.g., "day", "year") or custom scaling. - `plot_title`: Character string. Title for the full parameter plot layout. Default is "HMM Parameters Over Time". - `overlay_data`: Optional numeric vector of length `length(x)`. External series to overlay on parameter plots (e.g., covariates or raw data). - `overlay_label`: Character string. Label for overlayed data axis. Default is "Data". - `colors`: Character vector of plotting colors. Default is `c("black", "red", "blue", "green")`. - `save_plot`: Logical. If `TRUE`, saves the plot 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`. - `seed`: Integer or `NULL`. Random seed for reproducibility. Default is `NULL`. ## Returns Invisibly returns a list containing: - **param_series**: List of parameter time series for each parameter. - **ci_series**: List of confidence interval time series (lower and upper bounds) for each parameter. - **time_info**: List containing time axis information and labels. - **decoded_states**: Vector of decoded hidden states for each time point. The function also produces parameter trajectory plots with confidence intervals and optional overlays. ## Details For each observation, the most likely hidden state is decoded using `globaldecodeHMM`. The corresponding state-dependent parameters are extracted and plotted over time. If `confint_result` is not supplied, bootstrap confidence intervals are computed via `confintHMM`. Custom time scaling can be applied using the `time_structure` argument. Overlay data (such as covariates or raw series) can be plotted on a secondary axis for comparison. When `verbose = TRUE`, progress messages are displayed during confidence interval computation. ## Examples ```r set.seed(123) J <- 2 Pi <- matrix(c(0.9, 0.1, 0.2, 0.8), nrow = 2, byrow = TRUE) delta <- c(0.5, 0.5) obspar <- list(lambda = c(2, 7)) sim_data <- generateHMM(n = 120, J = J, obsdist = "pois", obspar = obspar, Pi = Pi, delta = delta) HMM_fit <- findmleHMM(x = sim_data$x, J = J, obsdist = "pois", obspar = obspar, Pi = Pi, delta = delta) overlay_series <- sim_data$x time_struct <- list(unit = "day", observations_per_unit = 12, start_point = 1) result <- plotHMMParameters(x = sim_data$x, HMM = HMM_fit, obsdist = "pois", overlay_data = overlay_series, overlay_label = "Observed counts", time_structure = time_struct, plot_title = "Poisson HMM Parameters with Overlay") result <- plotHMMParameters(x = sim_data$x, HMM = HMM_fit, obsdist = "pois", overlay_data = overlay_series, overlay_label = "Observed counts", time_structure = time_struct, save_plot = TRUE, filename = tempfile(fileext = ".png"), verbose = FALSE) ``` ## See Also `findmleHMM`, for fitting HMMs. `generateHMM`, for simulating HMM data. `globaldecodeHMM`, for decoding the most likely state sequence. `confintHMM`, for bootstrap confidence intervals of HMM parameters. ## Author(s) Aimee Cody

plotHMMParameters function