Skip to contents

evalueHMM

R-CMD-check pkgdown Codecov test coverage License: GPL-3 Lifecycle: experimental

evalueHMM implements predictive e-diagnostics for hidden Markov models of animal movement. It provides tools for observable predictive densities, e-process construction, diagnostic alternatives, predictable mixtures, switching, localization, feature-level diagnostics and blockwise diagnostics.

The repository is both:

  1. an installable R package;
  2. a reproducible research compendium for the manuscript “Predictive e-diagnostics for multi-state movement models”.

Installation

Install the development version from GitHub:

install.packages("remotes")
remotes::install_github("AurelienNicosiaULaval/evalue-HMM")

To clone the research repository with SSH:

git clone git@github.com:AurelienNicosiaULaval/evalue-HMM.git
cd evalue-HMM

Restore the project environment:

renv::restore()

Quick start 

library(evalueHMM)

set.seed(20260522)

null_parameters <- create_hmm_movement_parameters()
validation_data <- simulate_hmm_movement(
  n_times = 150,
  parameters = null_parameters
)

diagnostic_parameters <- perturb_hmm_movement_parameters(
  parameters = null_parameters,
  angle_sd_multiplier = c(1.2, 1.4)
)

log_p0 <- hmm_movement_predictive_log_density(
  data = validation_data,
  parameters = null_parameters
)

log_q <- hmm_movement_predictive_log_density(
  data = validation_data,
  parameters = diagnostic_parameters
)

diagnostic <- make_predictive_diagnostic(
  diagnostic_name = "angle_perturbation",
  log_p0 = log_p0,
  log_q = log_q,
  time = validation_data$time
)

summarise_predictive_diagnostic(diagnostic)
plot_eprocess(compute_eprocess(log_p0, log_q))

Main package features

  • HMM filtering and observable predictive log-densities.
  • Predictive e-process construction and S3 diagnostic summaries.
  • Simulated movement HMM and HSMM-like generators for reproducible examples.
  • Full-density diagnostics for state-number and angular misspecification.
  • Feature-level diagnostics for residual step-angle dependence.
  • Blockwise duration and long-horizon straightness diagnostics.
  • Predictable diagnostic mixtures, switching and localization.
  • Conservative finite-family composite-null envelopes.

Vignettes and online documentation

The package includes vignettes for:

  • getting started with predictive e-diagnostics;
  • using the diagnostic catalog;
  • reproducing package checks and manuscript workflows.

Build the local documentation site with:

pkgdown::build_site()

When GitHub Pages is enabled, the online site is configured for aureliennicosiaulaval.github.io/evalue-HMM.

Research compendium

The manuscript-scale simulations and real-data application are intentionally kept outside the package build.

Run all simulation scenarios:

Rscript simulations/run_all_simulations.R

Run the elk application:

Rscript application/run_application.R

Compile the manuscript:

cd paper
pdflatex predictive_e_diagnostics_hmm_improved.tex
pdflatex predictive_e_diagnostics_hmm_improved.tex
pdflatex supplementary_material.tex
pdflatex supplementary_material.tex

Generated research outputs are written to results/, application/data_processed/, paper/figures/ and manuscript_outputs/.

Package development

Run the package checks:

R CMD build --no-build-vignettes .
R CMD check --no-manual --no-build-vignettes evalueHMM_0.1.0.tar.gz

Run tests from R:

testthat::test_local()

Regenerate documentation:

roxygen2::roxygenise()

Regenerate the hex logo:

Rscript tools/make-logo.R

License

This package is licensed under GPL-3.