| Title: | R Interface to the 'EpiAware' Infectious Disease Modelling Framework |
|---|---|
| Description: | Provides an R interface to the 'Julia'-based 'EpiAware' compositional infectious disease modelling framework. Enables users to build flexible epidemiological models by composing reusable components for latent processes, infection dynamics, and observation models without requiring 'Julia' expertise. |
| Authors: | Sebastian Funk [aut, cre, cph] |
| Maintainer: | Sebastian Funk <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-05-14 09:33:59 UTC |
| Source: | https://github.com/sbfnk/EpiAwareR |
Constructs an autoregressive (AR) latent process of order p for modeling time-varying log reproduction numbers or other epidemiological parameters.
AR(order = 1, damp_priors, init_priors, std_prior)AR(order = 1, damp_priors, init_priors, std_prior)
order |
Integer. The order of the autoregressive process (p). |
damp_priors |
List of distribution specifications for damping
coefficients. Length must equal |
init_priors |
List of distribution specifications for initial
states. Length must equal |
std_prior |
Distribution specification for innovation standard deviation. |
An S3 object of class c("epiaware_ar", "epiaware_latent",
"epiaware_model") containing:
Reference to the Julia AR object
List of model specifications
epiaware_call for accessing other latent models
## Not run: # AR(2) model with truncated normal priors (Mishra et al. 2020) ar2 <- AR( order = 2, damp_priors = list( truncnorm(0.2, 0.2, 0, 1), truncnorm(0.1, 0.05, 0, 1) ), init_priors = list(norm(0, 0.2), norm(0, 0.2)), std_prior = halfnorm(0.1) ) print(ar2) ## End(Not run)## Not run: # AR(2) model with truncated normal priors (Mishra et al. 2020) ar2 <- AR( order = 2, damp_priors = list( truncnorm(0.2, 0.2, 0, 1), truncnorm(0.1, 0.05, 0, 1) ), init_priors = list(norm(0, 0.2), norm(0, 0.2)), std_prior = halfnorm(0.1) ) print(ar2) ## End(Not run)
Convert epiaware_fit to draws_array
## S3 method for class 'epiaware_fit' as_draws_array(x, ...)## S3 method for class 'epiaware_fit' as_draws_array(x, ...)
x |
An |
... |
Additional arguments passed to
|
A posterior::draws_array object.
Convert epiaware_fit to draws_df
## S3 method for class 'epiaware_fit' as_draws_df(x, ...)## S3 method for class 'epiaware_fit' as_draws_df(x, ...)
x |
An |
... |
Additional arguments passed to
|
A posterior::draws_df object.
Convert epiaware_fit to draws_list
## S3 method for class 'epiaware_fit' as_draws_list(x, ...)## S3 method for class 'epiaware_fit' as_draws_list(x, ...)
x |
An |
... |
Additional arguments passed to
|
A posterior::draws_list object.
Convert epiaware_fit to draws_matrix
## S3 method for class 'epiaware_fit' as_draws_matrix(x, ...)## S3 method for class 'epiaware_fit' as_draws_matrix(x, ...)
x |
An |
... |
Additional arguments passed to
|
A posterior::draws_matrix object.
Convert epiaware_fit to draws_rvars
## S3 method for class 'epiaware_fit' as_draws_rvars(x, ...)## S3 method for class 'epiaware_fit' as_draws_rvars(x, ...)
x |
An |
... |
Additional arguments passed to
|
A posterior::draws_rvars object.
Tests whether Julia is configured and EpiAware packages are accessible.
epiaware_available()epiaware_available()
Logical. TRUE if Julia and EpiAware are available, FALSE otherwise.
## Not run: if (epiaware_available()) { # Run EpiAware analysis } else { epiaware_setup_julia() } ## End(Not run)## Not run: if (epiaware_available()) { # Run EpiAware analysis } else { epiaware_setup_julia() } ## End(Not run)
Provides access to Julia EpiAware functions not yet wrapped in R. This is an "escape hatch" for accessing newer or experimental EpiAware features before they get explicit R wrappers.
epiaware_call( fn_name, ..., .param_map = NULL, .class = c("epiaware_generic", "epiaware_model") )epiaware_call( fn_name, ..., .param_map = NULL, .class = c("epiaware_generic", "epiaware_model") )
fn_name |
Character string. Name of the Julia function to call. |
... |
Named arguments to pass to the Julia function. |
.param_map |
Named character vector mapping R parameter names to Julia names. Use this when Julia uses Greek letters or other characters not easily typed in R. Example: c(theta_priors = "θ_priors", eps_t = "ϵ_t"). |
.class |
Character vector. S3 classes to add to the returned object. Default is c("epiaware_generic", "epiaware_model"). |
An S3 object containing the Julia reference and specifications.
## Not run: # Call a hypothetical new EpiAware component not yet wrapped custom_model <- epiaware_call( "NewLatentModel", param1 = 0.5, param2 = norm(0, 1) ) # For Julia functions with Greek letters, use parameter mapping eps_model <- epiaware_call("HierarchicalNormal", halfnorm(0.1)) ma2 <- epiaware_call( "MA", theta_priors = list(norm(0, 0.1), norm(0, 0.1)), eps_t = eps_model, .param_map = c(theta_priors = "θ_priors", eps_t = "ϵ_t") ) ## End(Not run)## Not run: # Call a hypothetical new EpiAware component not yet wrapped custom_model <- epiaware_call( "NewLatentModel", param1 = 0.5, param2 = norm(0, 1) ) # For Julia functions with Greek letters, use parameter mapping eps_model <- epiaware_call("HierarchicalNormal", halfnorm(0.1)) ma2 <- epiaware_call( "MA", theta_priors = list(norm(0, 0.1), norm(0, 0.1)), eps_t = eps_model, .param_map = c(theta_priors = "θ_priors", eps_t = "ϵ_t") ) ## End(Not run)
Configures Julia and installs required Julia packages for EpiAwareR. This function should be run on first use if automatic setup fails.
epiaware_setup_julia(verbose = TRUE)epiaware_setup_julia(verbose = TRUE)
verbose |
Logical. If TRUE, prints progress messages. Default is TRUE. |
Invisible TRUE if setup succeeds, otherwise throws an error.
## Not run: # Setup Julia and install EpiAware packages epiaware_setup_julia() ## End(Not run)## Not run: # Setup Julia and install EpiAware packages epiaware_setup_julia() ## End(Not run)
Creates an EpiProblem that composes infection, latent, and observation models into a complete epidemiological model specification. The latent model generates time-varying epidemiological parameters, the infection model simulates disease transmission, and the observation model links latent infections to observed data.
EpiProblem(epi_model, latent_model, observation_model, tspan)EpiProblem(epi_model, latent_model, observation_model, tspan)
epi_model |
An infection model object (e.g., from |
latent_model |
A latent process model (e.g., from |
observation_model |
An observation model (e.g., from
|
tspan |
A numeric vector of length 2 specifying the time span for inference or simulation: c(start_time, end_time). |
An S3 object of class c("epiaware_problem", "epiaware_model")
containing:
Reference to the Julia EpiProblem object
List containing the three model components
The time span
## Not run: # Compose a complete epidemiological model (Mishra et al. 2020) ar2 <- AR( order = 2, damp_priors = list(truncnorm(0.2, 0.2, 0, 1), truncnorm(0.1, 0.05, 0, 1)), init_priors = list(norm(0, 0.2), norm(0, 0.2)), std_prior = halfnorm(0.1) ) renewal <- Renewal( gen_distribution = gamma_dist(6.5, 0.62), initialisation_prior = norm(log(1.0), 0.1) ) negbin <- NegativeBinomialError( cluster_factor_prior = halfnorm(0.1) ) model <- EpiProblem( epi_model = renewal, latent_model = ar2, observation_model = negbin, tspan = c(45, 80) ) print(model) ## End(Not run)## Not run: # Compose a complete epidemiological model (Mishra et al. 2020) ar2 <- AR( order = 2, damp_priors = list(truncnorm(0.2, 0.2, 0, 1), truncnorm(0.1, 0.05, 0, 1)), init_priors = list(norm(0, 0.2), norm(0, 0.2)), std_prior = halfnorm(0.1) ) renewal <- Renewal( gen_distribution = gamma_dist(6.5, 0.62), initialisation_prior = norm(log(1.0), 0.1) ) negbin <- NegativeBinomialError( cluster_factor_prior = halfnorm(0.1) ) model <- EpiProblem( epi_model = renewal, latent_model = ar2, observation_model = negbin, tspan = c(45, 80) ) print(model) ## End(Not run)
Specifies an exponential distribution.
exponential(rate)exponential(rate)
rate |
Numeric. Rate parameter (inverse of mean). |
A list specification for an exponential distribution.
## Not run: # Exponential prior with mean 10 prior <- exponential(1 / 10) ## End(Not run)## Not run: # Exponential prior with mean 10 prior <- exponential(1 / 10) ## End(Not run)
Performs Bayesian inference on an epidemiological model using MCMC sampling. This function generates a Turing.jl model from the EpiProblem specification, runs the specified inference method, and returns posterior samples with diagnostics.
fit(model, data, method = nuts_sampler(), ...)fit(model, data, method = nuts_sampler(), ...)
model |
An |
data |
A data frame or list containing observed data. Must have a
column/element named |
method |
A sampler configuration object (e.g., from
|
... |
Additional arguments (currently unused). |
An S3 object of class epiaware_fit containing:
posterior::draws_df object with MCMC samples
tibble with parameter summaries
tibble with convergence diagnostics (Rhat, ESS)
List with generated quantities (Rt, infections, etc.)
The original EpiProblem
The data used for inference
The inference method used
## Not run: # Load data data <- read.csv("south_korea_data.csv") training_data <- data[45:80, ] # Fit model results <- fit( model = mishra_model, data = training_data, method = nuts_sampler(warmup = 1000, draws = 1000, chains = 4) ) # Examine results print(results) summary(results) plot(results, type = "Rt") ## End(Not run)## Not run: # Load data data <- read.csv("south_korea_data.csv") training_data <- data[45:80, ] # Fit model results <- fit( model = mishra_model, data = training_data, method = nuts_sampler(warmup = 1000, draws = 1000, chains = 4) ) # Examine results print(results) summary(results) plot(results, type = "Rt") ## End(Not run)
Specifies a gamma distribution using shape and scale parameterization.
gamma_dist(shape, scale)gamma_dist(shape, scale)
shape |
Numeric. Shape parameter (alpha). |
scale |
Numeric. Scale parameter (theta). Note: this is scale, not rate. |
A list specification for a gamma distribution.
## Not run: # Generation time distribution with mean 6.5 and scale 0.62 gen_time <- gamma_dist(6.5, 0.62) ## End(Not run)## Not run: # Generation time distribution with mean 6.5 and scale 0.62 gen_time <- gamma_dist(6.5, 0.62) ## End(Not run)
Specifies a half-normal distribution (normal distribution truncated to positive values).
halfnorm(sd)halfnorm(sd)
sd |
Numeric. Scale parameter (standard deviation of underlying normal). |
A list specification for a half-normal distribution.
## Not run: # Prior for standard deviation parameters sigma_prior <- halfnorm(0.1) ## End(Not run)## Not run: # Prior for standard deviation parameters sigma_prior <- halfnorm(0.1) ## End(Not run)
Wraps an observation model with a reporting delay, convolving the latent infections with a delay distribution. This is used to model delays between infection and observation (e.g., incubation period, reporting delays).
LatentDelay(model, delay_distribution)LatentDelay(model, delay_distribution)
model |
An observation model object (e.g., from
|
delay_distribution |
Distribution specification for the delay. Can be any continuous distribution that will be discretized. |
An S3 object of class c("epiaware_delay",
"epiaware_observation", "epiaware_model") containing:
Reference to the Julia LatentDelay object
The wrapped observation model
List of model specifications
## Not run: # Add incubation and reporting delays to observation model negbin <- NegativeBinomialError(halfnorm(0.1)) # Add incubation delay incubation_model <- LatentDelay( negbin, delay_distribution = lognorm(1.6, 0.42) ) # Add reporting delay full_model <- LatentDelay( incubation_model, delay_distribution = lognorm(0.58, 0.47) ) ## End(Not run)## Not run: # Add incubation and reporting delays to observation model negbin <- NegativeBinomialError(halfnorm(0.1)) # Add incubation delay incubation_model <- LatentDelay( negbin, delay_distribution = lognorm(1.6, 0.42) ) # Add reporting delay full_model <- LatentDelay( incubation_model, delay_distribution = lognorm(0.58, 0.47) ) ## End(Not run)
Specifies a log-normal distribution.
lognorm(meanlog, sdlog)lognorm(meanlog, sdlog)
meanlog |
Numeric. Mean of the distribution on the log scale. |
sdlog |
Numeric. Standard deviation of the distribution on the log scale. |
A list specification for a log-normal distribution.
## Not run: # Delay distribution delay <- lognorm(1.6, 0.42) ## End(Not run)## Not run: # Delay distribution delay <- lognorm(1.6, 0.42) ## End(Not run)
Links latent infections to observed case counts using a negative binomial distribution. The cluster_factor parameterizes the overdispersion as the coefficient of variation (sqrt(1/phi)), which is more intuitive for setting priors than the dispersion parameter phi directly.
NegativeBinomialError(cluster_factor_prior)NegativeBinomialError(cluster_factor_prior)
cluster_factor_prior |
Distribution specification for the cluster factor (sqrt(1/phi)), which represents the coefficient of variation of observation noise. |
An S3 object of class c("epiaware_negbin",
"epiaware_observation", "epiaware_model") containing:
Reference to the Julia NegativeBinomialError object
List of model specifications
## Not run: # Negative binomial observation model negbin <- NegativeBinomialError( cluster_factor_prior = halfnorm(0.1) ) print(negbin) ## End(Not run)## Not run: # Negative binomial observation model negbin <- NegativeBinomialError( cluster_factor_prior = halfnorm(0.1) ) print(negbin) ## End(Not run)
Specifies a normal (Gaussian) distribution.
norm(mean, sd)norm(mean, sd)
mean |
Numeric. Mean of the distribution. |
sd |
Numeric. Standard deviation of the distribution. |
A list specification for a normal distribution.
## Not run: # Standard normal prior1 <- norm(0, 1) # Prior for log Rt prior2 <- norm(log(1.5), 0.2) ## End(Not run)## Not run: # Standard normal prior1 <- norm(0, 1) # Prior for log Rt prior2 <- norm(log(1.5), 0.2) ## End(Not run)
Creates a configuration for the No-U-Turn Sampler (NUTS), a variant of Hamiltonian Monte Carlo that automatically tunes step size and number of steps.
nuts_sampler(warmup = 1000, draws = 1000, chains = 4, target_acceptance = 0.9)nuts_sampler(warmup = 1000, draws = 1000, chains = 4, target_acceptance = 0.9)
warmup |
Integer. Number of warmup/adaptation iterations. Default: 1000. |
draws |
Integer. Number of post-warmup samples to draw. Default: 1000. |
chains |
Integer. Number of MCMC chains to run. Default: 4. |
target_acceptance |
Numeric. Target acceptance rate for adaptation. Default: 0.9 (recommended for complex models). |
An S3 object of class c("epiaware_nuts", "epiaware_sampler")
containing sampler configuration.
## Not run: # Default NUTS configuration sampler <- nuts_sampler() # Custom configuration for faster testing test_sampler <- nuts_sampler( warmup = 100, draws = 100, chains = 2 ) ## End(Not run)## Not run: # Default NUTS configuration sampler <- nuts_sampler() # Custom configuration for faster testing test_sampler <- nuts_sampler( warmup = 100, draws = 100, chains = 2 ) ## End(Not run)
Creates visualizations of fitted model results, including reproduction number trajectories, infection curves, and posterior predictive distributions.
## S3 method for class 'epiaware_fit' plot(x, type = c("Rt", "cases", "posterior"), ...)## S3 method for class 'epiaware_fit' plot(x, type = c("Rt", "cases", "posterior"), ...)
x |
An |
type |
Character string specifying plot type. Options:
|
... |
Additional arguments passed to plotting functions. |
A ggplot2 object.
## Not run: # Plot Rt trajectory plot(results, type = "Rt") # Plot posterior predictive for cases plot(results, type = "cases") # Plot parameter posteriors plot(results, type = "posterior") ## End(Not run)## Not run: # Plot Rt trajectory plot(results, type = "Rt") # Plot posterior predictive for cases plot(results, type = "cases") # Plot parameter posteriors plot(results, type = "posterior") ## End(Not run)
Print method for AR latent models
## S3 method for class 'epiaware_ar' print(x, ...)## S3 method for class 'epiaware_ar' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for latent delay observation models
## S3 method for class 'epiaware_delay' print(x, ...)## S3 method for class 'epiaware_delay' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print Method for Fitted EpiAware Models
## S3 method for class 'epiaware_fit' print(x, ...)## S3 method for class 'epiaware_fit' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for generic EpiAware calls
## S3 method for class 'epiaware_generic' print(x, ...)## S3 method for class 'epiaware_generic' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for negative binomial observation models
## S3 method for class 'epiaware_negbin' print(x, ...)## S3 method for class 'epiaware_negbin' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for NUTS sampler configuration
## S3 method for class 'epiaware_nuts' print(x, ...)## S3 method for class 'epiaware_nuts' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for EpiAware problems
## S3 method for class 'epiaware_problem' print(x, ...)## S3 method for class 'epiaware_problem' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Print method for renewal infection models
## S3 method for class 'epiaware_renewal' print(x, ...)## S3 method for class 'epiaware_renewal' print(x, ...)
x |
An |
... |
Additional arguments (currently unused). |
Invisibly returns the input object x.
Constructs a renewal process model for infections, where new infections arise from previous infections weighted by a generation time distribution. This implements the renewal equation I_t = R_t * sum(g_s * I_{t-s}).
Renewal(gen_distribution, initialisation_prior = NULL)Renewal(gen_distribution, initialisation_prior = NULL)
gen_distribution |
Distribution specification for the generation time (or serial interval). Can be any continuous distribution that will be discretized using double interval censoring. |
initialisation_prior |
Optional distribution specification for the initial infection level (on log scale). If NULL, uses a default prior. |
An S3 object of class c("epiaware_renewal", "epiaware_epi",
"epiaware_model") containing:
Reference to the Julia Renewal object
List of model specifications
epiaware_call for accessing other infection models
## Not run: # Renewal model with Gamma generation time (Mishra et al. 2020) renewal <- Renewal( gen_distribution = gamma_dist(6.5, 0.62), initialisation_prior = norm(log(1.0), 0.1) ) print(renewal) # For advanced features, use the generic wrapper # to access newer EpiAware infection models custom_model <- epiaware_call("NewInfectionModel", param1 = ...) ## End(Not run)## Not run: # Renewal model with Gamma generation time (Mishra et al. 2020) renewal <- Renewal( gen_distribution = gamma_dist(6.5, 0.62), initialisation_prior = norm(log(1.0), 0.1) ) print(renewal) # For advanced features, use the generic wrapper # to access newer EpiAware infection models custom_model <- epiaware_call("NewInfectionModel", param1 = ...) ## End(Not run)
Summary Method for Fitted EpiAware Models
## S3 method for class 'epiaware_fit' summary(object, ...)## S3 method for class 'epiaware_fit' summary(object, ...)
object |
An |
... |
Additional arguments (currently unused). |
A tibble with parameter summaries.
Specifies a normal distribution truncated to a specified range.
truncnorm(mean, sd, lower, upper)truncnorm(mean, sd, lower, upper)
mean |
Numeric. Mean of the underlying normal distribution. |
sd |
Numeric. Standard deviation of the underlying normal distribution. |
lower |
Numeric. Lower truncation bound. |
upper |
Numeric. Upper truncation bound. |
A list specification for a truncated normal distribution.
## Not run: # AR damping coefficient bounded to [0, 1] damp_prior <- truncnorm(0.8, 0.2, 0, 1) ## End(Not run)## Not run: # AR damping coefficient bounded to [0, 1] damp_prior <- truncnorm(0.8, 0.2, 0, 1) ## End(Not run)