| Title: | Bayesian Compartmental Infection Models from Individual Outcomes |
|---|---|
| Description: | Fit Bayesian compartmental infection models (such as susceptible-infected-recovered 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'. |
| Authors: | Claire Perrin Smith [aut, cre] (ORCID: <https://orcid.org/0000-0003-1069-9460>), Jack Goodall [aut] |
| Maintainer: | Claire Perrin Smith <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-10-20 19:47:49 UTC |
| Source: | https://github.com/cran/hestia |
A DESCRIPTION OF THE PACKAGE
Maintainer: Claire Perrin Smith [email protected] (ORCID)
Authors:
Claire Perrin Smith [email protected] (ORCID)
Jack Goodall [email protected]
Stan Development Team (NA). RStan: the R interface to Stan. R package version 2.32.7. https://mc-stan.org
Useful links:
Report bugs at https://github.com/ACCIDDA/hestia/issues
Create Transmission Probability Matrix
get_transmission_details(inf_model)get_transmission_details(inf_model)
inf_model |
infection process model object yielded by make_infection_model() |
A list with the following entries:
"states", a character vector of state names
"trans_matrix", a matrix with transition rate values between origin (column) and destination (row) compartments where given. Where no values are provided for transition rates the entry is equal to 1e-10.
"mult_matrix", a matrix with split values for the transition between origin (column) and destination (row) compartments where given. Where no split values are provided for transition rates the entry is equal to 1.
"trans_to_fit", a data frame with information on all transitions within the model, with parameter indexing details if the transition rate is being fit
"mult_to_fit", a data frame with information on all splits specified in the model, with parameter indexing details if the split is being fit
"inf_states", numeric values corresponding to the indices in "states" which are the infectious states
"mult_ih_inf_probs", indicator for whether infectious states have shared or separate inta-household infection probabilities. If FALSE then all infection probabilities are shared across infectious compartments.
# Split the infectious compartment into symptomatic (I_s) and asymptomatic # (I_a) infections, with separate intra-household infection probabilities. inf_model <- make_infection_model( transmit(from = "S", to = c("I_s", "I_a"), source = c("I_s", "I_a"), split = "phi"), progress(from = "I_s", to = "R", gamma_s = NA), progress(from = "I_a", to = "R", gamma_a = NA), mult_ih_inf_probs = TRUE) get_transmission_details(inf_model)# Split the infectious compartment into symptomatic (I_s) and asymptomatic # (I_a) infections, with separate intra-household infection probabilities. inf_model <- make_infection_model( transmit(from = "S", to = c("I_s", "I_a"), source = c("I_s", "I_a"), split = "phi"), progress(from = "I_s", to = "R", gamma_s = NA), progress(from = "I_a", to = "R", gamma_a = NA), mult_ih_inf_probs = TRUE) get_transmission_details(inf_model)
Build Infection Process Model
make_infection_model(..., mult_ih_inf_probs = FALSE, mult_eh_inf_probs = FALSE)make_infection_model(..., mult_ih_inf_probs = FALSE, mult_eh_inf_probs = FALSE)
... |
|
mult_ih_inf_probs |
If FALSE then all intra-household infection probabilities are shared across infectious compartments. If TRUE, each infection compartment has a distinct probability. |
mult_eh_inf_probs |
If FALSE then all extra-household infection probabilities are shared across infectious compartments. If TRUE, each infection compartment has a distinct probability. |
A data frame with a row for each unique transition in the infection process model and the following columns:
"from", the name of the origin compartment
"to", the name of the destination compartment
"source", NA (so output columns match with transmit)
"rate_name", name of transition rate parameter if fitting
"rate_value", numeric value of transition rate if not fitting
"split_name", name of split parameter if fitting
"split_value", numeric value of split if not fitting
"source", names of compartment(s) that are the source of new infections
"mult_ih_inf_probs", a logical indicator for whether infectious compartments
have separate (TRUE) or shared (FALSE) intra-household infection
probabilities
# Basic SIR model with recovery rate gamma to be fit make_infection_model(transmit(from = "S", to = "I"), progress(from = "I", to = "R", gamma = NA)) # Split the infectious compartment into symptomatic (I_s) and asymptomatic # (I_a) infections, with separate intra-household infection probabilities. make_infection_model( transmit(from = "S", to = c("I_s", "I_a"), source = c("I_s", "I_a"), split = "phi"), progress(from = "I_s", to = "R", gamma_s = NA), progress(from = "I_a", to = "R", gamma_a = NA), mult_ih_inf_probs = TRUE)# Basic SIR model with recovery rate gamma to be fit make_infection_model(transmit(from = "S", to = "I"), progress(from = "I", to = "R", gamma = NA)) # Split the infectious compartment into symptomatic (I_s) and asymptomatic # (I_a) infections, with separate intra-household infection probabilities. make_infection_model( transmit(from = "S", to = c("I_s", "I_a"), source = c("I_s", "I_a"), split = "phi"), progress(from = "I_s", to = "R", gamma_s = NA), progress(from = "I_a", to = "R", gamma_a = NA), mult_ih_inf_probs = TRUE)
Make Observation Process Model
make_observation_model(...)make_observation_model(...)
... |
A series of named vectors. Each vector corresponds to an observation type. Each entry in the vector is named for the corresponding compartment in the infection process model. The value is the probability of observing a positive observation given the individual is in the compartment. |
A list with one entry for each observation type.
# Observation process for an SIR model with two observations, PCR test # results and presence of IgG antibodies. make_observation_model( pcr = c("S" = 0.05, "I" = 0.95, "R" = 0.05), igg = c("S" = 0.01, "I" = 0.01, "R" = 0.8) )# Observation process for an SIR model with two observations, PCR test # results and presence of IgG antibodies. make_observation_model( pcr = c("S" = 0.05, "I" = 0.95, "R" = 0.05), igg = c("S" = 0.01, "I" = 0.01, "R" = 0.8) )
Defines a state transition in the infection process model which does not represent an transmission (infection) event
progress(from, to, split = NA, ...)progress(from, to, split = NA, ...)
from |
string giving name of origin compartment |
to |
string or vector of strings giving the name of the destination compartment |
split |
an optional character or numeric vector indicating what
proportion of individuals transition into each of the |
... |
Argument specifying the name and optionally the value of the
transition rate parameter. For example if the parameter name is "gamma" and
it is being fit this argument should be |
Data frame with a row for each unique transition and the following columns:
"from", the name of the origin compartment
"to", the name of the destination compartment
"source", NA (so output columns match with transmit)
"rate_name", name of transition rate parameter if fitting
"rate_value", numeric value of transition rate if not fitting
"split_name", name of split parameter if fitting
"split_value", numeric value of split if not fitting
# Transition from compartment A to B which occurs at rate gamma where # gamma is a user-specified value of 0.2 progress(from = "A", to = "B", gamma = 0.2) # Transition from compartment A to B which occurs at rate gamma where # gamma is fit progress(from = "A", to = "B", gamma = NA) # Transition from compartment A split into two destination compartments, B1 # and B2, were individuals leave A at rate delta (fit) and phi (fit) is the # proportion of those who leave A who go into B1 (i.e. 1-phi go into B2). # gamma is fit progress(from = "A", to = c("B1", "B2"), split = "phi", delta = NA)# Transition from compartment A to B which occurs at rate gamma where # gamma is a user-specified value of 0.2 progress(from = "A", to = "B", gamma = 0.2) # Transition from compartment A to B which occurs at rate gamma where # gamma is fit progress(from = "A", to = "B", gamma = NA) # Transition from compartment A split into two destination compartments, B1 # and B2, were individuals leave A at rate delta (fit) and phi (fit) is the # proportion of those who leave A who go into B1 (i.e. 1-phi go into B2). # gamma is fit progress(from = "A", to = c("B1", "B2"), split = "phi", delta = NA)
Run Household Transmission Model
run_model( inf_model, obs_model, data, init_probs, t_start = 1, epsilon = 1e-10, ih_cov = NULL, eh_cov = NULL, init = NULL, save_llik = FALSE, save_states = FALSE, stan_opts = stan_options() )run_model( inf_model, obs_model, data, init_probs, t_start = 1, epsilon = 1e-10, ih_cov = NULL, eh_cov = NULL, init = NULL, save_llik = FALSE, save_states = FALSE, stan_opts = stan_options() )
inf_model |
Infection process model object generated by make_infection_model |
obs_model |
Observation process model object generated by make_observation_model |
data |
data frame with columns the following columns:
|
init_probs |
vector of initial probabilities for each infection process model state |
t_start |
integer value corresponding to the start of model time |
epsilon |
very small number to use for zero probability transitions |
ih_cov |
NULL for run without covariates, otherwise data frame with intra-household covariates for each participant |
eh_cov |
NULL for run without covariates, otherwise data frame with extra-household covariates for each participant |
init |
initial conditions for MCMC chains |
save_llik |
whether to write the per-household log-likelihood
( |
save_states |
whether to write the per-participant log forward
probabilities ( |
stan_opts |
a named list of Stan sampler options, as produced by
|
draws_array object with chains for each model parameter
# Subset sir package data to 10 households (for speedy example) sir_sub <- sir[sir$hh_id <= 10, ] # Make infetion process model for SIR model inf_mod <- make_infection_model( transmit(from = "S", to = "I"), progress(from = "I", to = "R", gamma = NA)) # Make observation process model obs_mod <- make_observation_model( pcr = c("S" = 0.05, "I" = 0.95, "R" = 0.05), igg = c("S" = 0.01, "I" = 0.01, "R" = 0.8)) # Fitting the Stan model is slow, so it is not run on CRAN. run_model(inf_model = inf_mod, obs_model = obs_mod, data = sir_sub, init_probs = c(1 - 2 * 1e-10, 1e-10, 1e-10))# Subset sir package data to 10 households (for speedy example) sir_sub <- sir[sir$hh_id <= 10, ] # Make infetion process model for SIR model inf_mod <- make_infection_model( transmit(from = "S", to = "I"), progress(from = "I", to = "R", gamma = NA)) # Make observation process model obs_mod <- make_observation_model( pcr = c("S" = 0.05, "I" = 0.95, "R" = 0.05), igg = c("S" = 0.01, "I" = 0.01, "R" = 0.8)) # Fitting the Stan model is slow, so it is not run on CRAN. run_model(inf_model = inf_mod, obs_model = obs_mod, data = sir_sub, init_probs = c(1 - 2 * 1e-10, 1e-10, 1e-10))
Individual-level outcomes simulated from an SIIR model for 500 households, in
which infection splits into symptomatic (Is) and asymptomatic (Ia)
compartments. The two infectious compartments have separate intra-household
infection probabilities. Each individual has three binary observations: one
informative about active infection (e.g. a PCR test), one informative about
recovery (e.g. an IgG antibody test), and one indicating symptoms.
siirsiir
A data frame with one row per individual per day and the following columns:
Day of observation.
Participant identifier within the household.
Enrollment indicator (1 = enrolled, 0 = not enrolled).
True latent compartment (1 = S, 2 = Is, 3 = Ia, 4 = R).
Household size.
Household identifier.
Binary outcome informative about active infection.
Binary outcome informative about recovery.
Binary outcome indicating symptoms.
Generated by data-raw/siir_data.R.
Posterior draws from run_model() fit to the siir data using an infection
process with separate symptomatic and asymptomatic compartments. Bundling the
result lets the vignette display model output without re-running the Stan
model. Parameters are on the natural (model) scale: probabilities, rates, and
the symptomatic split are returned in their original units rather than on the
logit fitting scale.
siir_ressiir_res
A posterior draws_array with parameters eh_prob, ih_prob_Is,
ih_prob_Ia, gamma_s, gamma_a, and phi.
Generated by data-raw/siir_res.R.
Individual-level outcomes simulated from a basic susceptible-infected-recovered (SIR) model for 500 households. Everyone starts susceptible, the daily extra-household infection probability is 1%, and the daily intra-household infection probability is 5%. Each individual has two binary observations: one informative about active infection (e.g. a PCR test) and one informative about recovery (e.g. an IgG antibody test).
sirsir
A data frame with one row per individual per day and the following columns:
Day of observation.
Participant identifier within the household.
Enrollment indicator (1 = enrolled, 0 = not enrolled).
True latent compartment (1 = S, 2 = I, 3 = R).
Household size.
Household identifier.
Binary outcome informative about active infection.
Binary outcome informative about recovery.
Generated by data-raw/sir_data.R.
Individual-level outcomes simulated from a basic SIR model for 500 households, together with two binary individual-level covariates that affect the intra- and extra-household infection probabilities. Used to demonstrate fitting covariate effects.
sir_covsir_cov
A list with two elements:
A data frame of outcomes with the same columns as sir.
A data frame with one row per individual and two binary
covariate columns, x1 and x2.
Generated by data-raw/sir_cov_data.R.
Posterior draws from run_model() fit to sir_cov with both intra- and
extra-household covariates. Bundling the result lets the vignette display
model output without re-running the Stan model. Parameters are on the natural
(model) scale: infection probabilities and rates in their original units and
covariate coefficients exponentiated, rather than on the logit and log
fitting scales.
sir_cov_ressir_cov_res
A posterior draws_array with parameters eh_prob, ih_prob,
gamma, x1_eh, x2_eh, x1_ih, and x2_ih.
Generated by data-raw/sir_cov_res.R.
Posterior draws from run_model() fit to the sir data using a basic SIR
infection process (fitting the recovery rate) and a two-test observation
process. Bundling the result lets the vignette display model output without
re-running the Stan model. Parameters are on the natural (model) scale:
probabilities and rates are returned in their original units rather than on
the logit fitting scale.
sir_ressir_res
A posterior draws_array with parameters eh_prob, ih_prob,
and gamma.
Generated by data-raw/sir_res.R.
Defines a state transition in the infection process model which is the result of a transmission (infection) event
transmit(from, to, source = NA, split = NA)transmit(from, to, source = NA, split = NA)
from |
string giving name of origin compartment |
to |
string giving the name of the destination compartment |
source |
string (or vector of strings) designating which compartments are infectious. If NA, the destination compartment is presumed to be the infectious compartment. |
split |
an optional character or numeric vector indicating what
proportion of individuals transition into each of the |
Data frame with a row for each unique transition and the following columns:
"from", the name of the origin compartment
"to", the name of the destination compartment
"split_name", name of split parameter if fitting
"split_value", numeric value of split if not fitting
"source", names of compartment(s) that are the source of new infections i.e. the infectious compartments
# Specify S > E transition in an SEIR model transmit(from = "S", to = "E", source = "I") # Upon infection, individuals either enter Is (symptomatic infections) or # Ia (asymptomatic infection) where 30% of infections are symptomatic. transmit(from = "S", to = c("Is", "Ia"), split = 0.3)# Specify S > E transition in an SEIR model transmit(from = "S", to = "E", source = "I") # Upon infection, individuals either enter Is (symptomatic infections) or # Ia (asymptomatic infection) where 30% of infections are symptomatic. transmit(from = "S", to = c("Is", "Ia"), split = 0.3)