hestia

Imported from ACCIDDA/hestia (AGENTS.md). Install upstream with npx skills add ACCIDDA/hestia. Copyright stays with the author.

Agent Guidelines for hestia

This document provides concise instructions and rules for AI coding assistants working in the hestia repository. For full developer documentation and CI architecture, see CONTRIBUTING.md.

1. Core Architecture & Invariants

• Package Purpose: hestia fits Bayesian compartmental infection models (such as SIR and multi-compartment hidden Markov variants) from individual-level outcome data. Models are composed from infection-process and observation-process components and fit using Stan via rstan and flexstanr.
• Stan Backend (flexstanr / rstan):
  • Backend abstraction is provided by imported package flexstanr (>= 0.2.0).
  • Precompiled Stan models live in inst/stan/ (hmm.stan, hmm_cov.stan).
  • R/stanmodels.R and src/stanExports_* are generated by rstantools and must not be edited by hand.
• Tracked vs. Untracked Artifacts:
  • R/globals.R and man/*.Rd are generated by roxygen2 and are untracked in git.
  • NAMESPACE is tracked in git.
  • src/RcppExports.cpp is generated by Rcpp::compileAttributes() and is tracked in git. Although generated, standard remote / GitHub installers (devtools::install_github(), pak::pak()) only download git-tracked files and do not run attribute compilers prior to R CMD INSTALL; src/RcppExports.cpp is required to register DLL entry points. Synchronization with Stan models is verified automatically by just check-rcpp (in just lint) and unit test tests/testthat/test-rcpp_exports.R.
• Model Workflow:
  • Infection models are specified with make_infection_model(transmit(...), progress(...))
  • Observation models are specified with make_observation_model(...)
  • Model fitting is executed via run_model(inf_model, obs_model, data, ...)

2. Coding, Error Handling & Documentation Standards

• Formatting & Linting:
  • Format code with just format (air).
  • Verify lint compliance with just lint (air and lintr).
  • Maximum line length is 100 characters.
• Roxygen Documentation Standards:
  • Explicit @title and @description: Roxygen blocks must use explicit @title and @description tags rather than relying on automatic inference.
  • @autoglobal: Functions containing non-standard evaluation expressions should be annotated with @autoglobal so roxyglobals generates appropriate symbol declarations in R/globals.R.
  • Internal Helper Functions: Unexported internal functions should be marked with @keywords internal and @noRd to keep code documented in source without generating unused .Rd files.
  • Parameter & Return Documentation: Explicitly state input types/classes using standard roxygen conventions, and describe return structures clearly.
• Examples:
  • For computationally heavy functions (e.g. run_model()), combine @examplesIf interactive() with \donttest{ ... } so CRAN --as-cran checks and site builds remain fast.
• Test Suite Conventions:
  • Unit tests live in tests/testthat/.
  • Reusable test helpers and model constructors live in tests/testthat/helper-fixtures.R.
  • Use expect_shape(df, expected_nrow = ..., expected_ncol = ...) for verifying tabular shapes.

3. Common Development Commands & CI Architecture

• justfile as Single Source of Truth:
  • The justfile serves as the single authoritative reference for all build, validation, doc, and test tasks.
  • CI workflows (.github/workflows/*.yaml) and composite actions (.github/actions/setup-hestia/action.yaml) invoke just <recipe>.

Use just recipes for development workflows:

just format        # Format R code (air)
just lint          # Lint R code (air + lintr)
just docs          # Regenerate man/*.Rd, R/globals.R
just install       # Install package into R library
just test          # Run devtools test suite
just test-fast     # Run test suite stopping on first failure
just coverage      # Check test coverage via covr
just spell         # Run spelling checks
just build         # Build package source tarball (hestia_*.tar.gz)
just check-cran    # Run R CMD check --as-cran on built tarball
just site          # Build pkgdown documentation site
just site-preview  # Preview pkgdown site locally on port 8000