SimInf (version 11.1.0)

prevalence,SimInf_model-method: Calculate prevalence from a model object with trajectory data

Description

Calculate the proportion of cases (specified on the left-hand side of the formula) relative to the population at risk (specified on the right-hand side) at different aggregation levels. The function supports three levels of calculation:

• Level 1 (Population Prevalence): The proportion of cases in the total population at risk across all nodes.

• Level 2 (Node Prevalence): The proportion of nodes that contain at least one case, considering only nodes where the population at risk is greater than zero.

• Level 3 (Within-Node Prevalence): The proportion of cases relative to the population at risk calculated separately for each node.

Usage

# S4 method for SimInf_model
prevalence(model, formula, level, index, format = c("data.frame", "matrix"))

Value

A data.frame if format = "data.frame", else a matrix.

Arguments

model

The model with trajectory data to calculate the prevalence from.

formula

A formula that specifies the compartments that define the cases with a disease or that have a specific characteristic (numerator), and the compartments that define the entire population of interest (denominator). The left-hand-side of the formula defines the cases, and the right-hand-side defines the population, for example, I~S+I+R in a ‘SIR’ model (see ‘Examples’). The . (dot) is expanded to all compartments, for example, I~. is expanded to I~S+I+R in a ‘SIR’ model (see ‘Examples’). The formula can also contain a condition (indicated by |) for each node and time step to further control the population to include in the calculation, for example, I ~ . | R == 0 to calculate the prevalence when the recovered is zero in a ‘SIR’ model. The condition must evaluate to TRUE or FALSE in each node and time step. Please note, if the denominator is zero, the prevalence is NaN. Additionally, when level=3 (within-node prevalence) and the formula contains a condition that evaluates to FALSE, the prevalence is also NaN.

level

The level at which the prevalence is calculated at each time point in tspan. 1 (population prevalence): calculates the proportion of the individuals (cases) in the population. 2 (node prevalence): calculates the proportion of nodes with at least one case. 3 (within-node prevalence): calculates the proportion of cases within each node. Default is 1.

index

indices specifying the subset of nodes to include when extracting data. Default (index = NULL) is to extract data from all nodes.

format

The default (format = "data.frame") is to generate a data.frame with one row per time-step with the prevalence. Using format = "matrix" returns the result as a matrix.

Examples

## For reproducibility, specify the number of threads.
set_num_threads(1)

## Create an 'SIR' model with 6 nodes.
u0 <- data.frame(
  S = 100:105,
  I = c(0, 1, 0, 2, 0, 3),
  R = rep(0, 6)
)

model <- SIR(
  u0 = u0,
  tspan = 1:10,
  beta = 0.16,
  gamma = 0.077
)

## Run the model with a fixed seed for reproducibility.
result <- run(model, seed = 12)

## 1. Population Prevalence (level = 1, default)
## Proportion of infected individuals in the total population.
prevalence(result, I ~ S + I + R)

## Shorthand: '.' represents all compartments in the model (S + I + R).
prevalence(result, I ~ .)

## 2. Node Prevalence (level = 2)
## Proportion of nodes with at least one infected individual.
prevalence(result, I ~ S + I + R, level = 2)

## 3. Within-Node Prevalence (level = 3)
## Prevalence calculated separately for each node.
prevalence(result, I ~ S + I + R, level = 3)

## 4. Conditional Prevalence
## Calculate prevalence only in nodes where the number of
## recovered is zero.
prevalence(result, I ~ S + I + R | R == 0, level = 3)