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.

Arguments

• df::DataFrame: DataFrame containing the following required columns:
  • :interaction_strength (Float64): Standard deviation for interaction value generation
  • :cf_ratio (Float64): Mean ratio of competitive to facilitative interactions
  • :priority_effects (Bool): If true, creates asymmetric matrices; if false, symmetric
  • :strains (Int): Number of strains (determines 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])
• Values are sampled from Normal(cfratio, interactionstrength)

Examples

using DataFrames

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

# Generate interaction matrices
matrices = prep_interaction_matrix(df)

prep_interaction_matrix(strains::Int, matrix_type::String, interaction_strength::Float64; cf_ratio::Float64=1.0)

Generates a single interaction matrix with specified parameters (convenience function).

Arguments

• strains::Int: Number of strains (matrix size will be strains × strains)
• matrix_type::String: Either "symmetric" or "asymmetric"
• interaction_strength::Float64: Standard deviation for random interaction values
• cf_ratio::Float64: Mean for interaction values (default: 1.0)

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 mean
matrix = prep_interaction_matrix(2, "asymmetric", 0.3, cf_ratio=1.2)

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.