API Reference

coinfectionsimulator(; initialpop::Vector{<:AbstractMatrix{Bool}}, ages::Vector{Int}, interactions::Matrix{Float64}, diseasetype::Vector{String}, basemortality::Float64, diseasemortality::Vector{Float64}, fecundity::Float64, transmission::Vector{Float64}, timesteps::Int, agematurity::Int, introduction::String = "simultaneous", latency::Union{Vector{Int}, Nothing} = nothing, recovery::Union{Vector{Float64}, Nothing} = nothing, immunityloss::Union{Vector{Float64}, Nothing} = nothing ) -> Tuple{Vector{Vector{<:AbstractMatrix{Bool}}}, Vector{Vector{Int}}}

Simulates multiple pathogen strains spreading through a host population with possible coinfection dynamics.

Arguments

• initial_pop::Vector{<:AbstractMatrix{Bool}}: Vector of matrices representing the initial population. Each matrix represents an individual, with rows corresponding to strains and columns representing disease states (Susceptible, Exposed, Infected, Recovered as [S,E,I,R]). Can be either Matrix{Bool} or BitMatrix.
• ages::Vector{Int}: Ages of each individual in the initial population.
• interactions::Matrix{Float64}: Matrix of interaction factors between strains. Values > 1 indicate synergistic interactions, values < 1 indicate antagonistic interactions.
• disease_type::Vector{String}: Vector specifying model type for each strain. Must be one of: "si", "sir", "seir", or "seirs".
• base_mortality::Float64: Background mortality rate per time step.
• disease_mortality::Vector{Float64}: Additional mortality rate for each strain when infected.
• fecundity::Float64: Mean number of offspring per mature individual per time step.
• transmission::Vector{Float64}: Transmission probability for each strain.
• time_steps::Int: Number of time steps to simulate.
• age_maturity::Int: Age at which individuals can reproduce.
• introduction::String: How strains are introduced: "simultaneous" (all at once) or "random" (randomly throughout simulation) or "none" (no infections are introduced by the function). Default is "simultaneous".
• latency::Union{Vector{Int}, Nothing}: Required for SEIR/SEIRS models. Vector of latency periods for each strain (number of time steps in exposed state).
• recovery::Union{Vector{Float64}, Nothing}: Required for SIR/SEIR/SEIRS models. Recovery probability for each strain.
• immunity_loss::Union{Vector{Float64}, Nothing}: Required for SEIRS models. Probability of losing immunity for each strain.

Returns

A tuple containing:

1. Vector of population states at each time step, where each state is a vector of individual matrices
2. Vector of individual ages at each time step (in the same order as the population states)

Disease State Format

Each individual is represented by an n×4 matrix where n is the number of strains:

• Column 1: Susceptible state (true if susceptible)
• Column 2: Exposed state (true if exposed, for SEIR/SEIRS models)
• Column 3: Infected state (true if infected)
• Column 4: Recovered state (true if recovered, for SIR/SEIR/SEIRS models)

virtual_ecologist_sample(;
	virtual_population,
	proportion_sampled::Float64,
	false_positive_rate::Float64,
	false_negative_rate::Float64
) -> Matrix{Bool}

Simulates sampling by a virtual ecologist with imperfect detection capabilities.

Arguments

• virtual_population: Population data across time steps (Vector{Vector{Matrix{Bool}}} or similar). Each element represents a time step, containing a vector of individual matrices. Each individual matrix has rows for strains and columns for disease states (S,E,I,R).
• proportion_sampled::Float64: Proportion of the population sampled at each time step (0-1).
• false_positive_rate::Float64: Probability of detecting a strain when it's not present (0-1).
• false_negative_rate::Float64: Probability of not detecting a strain when it is present (0-1).

Returns

• Matrix{Bool}: Detection matrix with dimensions (ntimesteps, nstrains). Each element indicates whether a strain was detected at that time step.

Examples

# Create sample population data
pop = [[rand(Bool, 3, 4) for _ in 1:10] for _ in 1:5]  # 5 timesteps, 10 individuals, 3 strains

# Sample with 50% sampling rate and 10% error rates
detections = virtual_ecologist_sample(
	virtual_population=pop,
	proportion_sampled=0.5,
	false_positive_rate=0.1,
	false_negative_rate=0.1
)

prep_interaction_matrix(; df::DataFrame) -> Vector{Matrix{Float64}}

Generates interaction matrices for coinfection simulations based on DataFrame parameters. Interactions are sampled from a uniform distribution, whose bounds are defined by the ratio of competition to facilitation in the pathogen community, and the interaction strength.

Arguments

• df::DataFrame: DataFrame containing the following required columns:
• :interaction_strength (Float64): Defines the outer bounds of the interaction multipliers. For example, an interaction strength of 0.1 means that the interaction multipliers will be sampled from a uniform distribution between 0.9 and 1.1. Interaction strength must be between 0 and 1. If interaction strength is 0, all interactions will be set to neutral (1.0) regardless of the cf_ratio.
• :cf_ratio (Float64): Defines the ratio of facilitation to competition in the interaction matrix. A ratio less than 0.5 means that the matrix will have more competitive interactions, while a ratio greater than 0.5 means that the matrix will have more facilitative interactions. The ratio must be between 0 and 1.
• :priority_effects (Bool): When true, the interaction matrix is asymmetric (priority effects). When false, the matrix is symmetric (no priority effects).
• :strains (Int): Number of strains in the pathogen community (determines interaction matrix dimensions).

Returns

• Vector{Matrix{Float64}}: Vector of interaction matrices, one per DataFrame row. Each matrix is strains × strains with diagonal elements = 1.0.

Details

• Diagonal elements are always 1.0 (self-interaction)
• For priority_effects = true: Off-diagonal elements are independently sampled
• For priority_effects = false: Matrix is symmetric (M[i,j] = M[j,i])

Examples

using DataFrames

# Create parameter DataFrame
df = DataFrame(
	interaction_strength = [0.1, 0.2],
	cf_ratio = [0.3, 0.7],
	priority_effects = [true, false],
	strains = [3, 4]
)

# Generate interaction matrices
matrices = prep_interaction_matrix(df)

prep_interaction_matrix(strains::Int, priority_effects::Bool, interaction_strength::Float64; cf_ratio::Float64=1.0)

Generates a single interaction matrix with specified parameters. Interactions are sampled from a uniform distribution, whose bounds are defined by the ratio of competition to facilitation in the pathogen community, and the interaction strength.

Arguments

• strains::Int: Number of strains (matrix size will be strains × strains)
• priority_effects::Bool: When true, the interaction matrix is asymmetric (priority effects). When false, the matrix is symmetric (no priority effects).
• interaction_strength::Float64: Defines the outer bounds of the interaction multipliers. For example, an interaction strength of 0.1 means that the interaction multipliers will be sampled from a uniform distribution between 0.9 and 1.1. Interaction strength must be between 0 and 1. If interaction strength is 0, all interactions will be set to neutral (1.0) regardless of the cf_ratio.
• cf_ratio::Float64: Defines the ratio of facilitation to competition in the interaction matrix. A ratio less than 0.5 means that the matrix will have more competitive interactions, while a ratio greater than 0.5 means that the matrix will have more facilitative interactions. The ratio must be between 0 and 1. The default is 0.5.

Returns

• Matrix{Float64}: An interaction matrix of size strains × strains

Examples

# Create symmetric 3x3 matrix
matrix = prep_interaction_matrix(3, "symmetric", 0.5)

# Create asymmetric 2x2 matrix with custom competition/facilitation ratio
matrix = prep_interaction_matrix(2, "asymmetric", 0.3, cf_ratio=0.8)

infect(susceptibles, infecteds, interactions, beta, strain)

Core infection function that determines which susceptible individuals become infected based on transmission probability and strain interactions.

handle_si_disease(current_pop, alive, strain, transmission, interactions, base_mortality, disease_mortality, dead_indices)

Handle SI (Susceptible-Infected) disease dynamics for a single strain.

handle_sir_disease(current_pop, alive, strain, transmission, interactions, base_mortality, disease_mortality, recovery, dead_indices)

Handle SIR (Susceptible-Infected-Recovered) disease dynamics for a single strain.

handle_seir_disease(current_pop, alive, strain, transmission, interactions, base_mortality, disease_mortality, recovery, latency, dead_indices)

Handle SEIR (Susceptible-Exposed-Infected-Recovered) disease dynamics for a single strain.

handle_seirs_disease(current_pop, alive, strain, transmission, interactions, base_mortality, disease_mortality, recovery, latency, immunity_loss, dead_indices)

Handle SEIRS (Susceptible-Exposed-Infected-Recovered-Susceptible) disease dynamics for a single strain.

handle_infection(current_pop, alive, strain, transmission, interactions)

Handle the infection process for susceptible individuals.

handle_exposure(current_pop, alive, strain, transmission, interactions)

Handle the exposure process for susceptible individuals in SEIR models.

handle_exposed_infection(current_pop, alive, strain, latency)

Handle the transition from exposed to infected state.

handle_recovery(current_pop, alive, strain, recovery)

Handle recovery from infected to recovered state.

handle_immunity_loss(current_pop, alive, strain, immunity_loss)

Handle loss of immunity (transition from recovered to susceptible).

handle_infected_death(current_pop, strain, base_mortality, disease_mortality, dead_indices)

Handle mortality of infected individuals.