Simulation

Simulation

A struct for the management of a single run, holding all necessary informations.

Initialization

Simulation(; kwargs...)
Simulation(params::Dict)

You can initialize a simulation without any parameters, which will then use the default configuration file. Providing any additional keyword arguments will override the respective configuration file parameter. If you provide a custom config file, the parameters in the config file will be used as defaults and only the provided keyword arguments will override them.

Here's a list of all available parameters:

Examples

# Initialize a simulation with default configuration
sim = Simulation()

# Initialize a simulation with a custom configuration file
sim = Simulation(configfile="path/to/configfile.toml")

# Initialize a simulation with custom parameters
sim = Simulation(
    tickunit='d',
    label="My Simulation",
    avg_household_size=5,
)

# Initialize a simulation with a predefined population model
sim = Simulation(population="SH") # Schleswig-Holstein, Germany

# Initialize a simulation with a custom population file
sim = Simulation(population="path/to/populationfile.csv")

# Initialize a simulation with a custom start condition
sim = Simulation(start_condition=PatientZero()) # starts with a single infected individual

# Initialize a simulation with a custom transmission rate
sim = Simulation(transmission_rate=0.1) # sets a constant per-contact transmission rate (chance) of 0.1

# Initialize a simulation with a parameter dictionary
params = Dict(
    :tickunit => 'd',
    :label => "My Simulation",
    :avg_household_size => 5,
)
sim = Simulation(params)

Internal Simulation Struct Fields

• Data Sources
  • configfile::String: Path to config file
• General
  • tick::Int16: Current tick/timestep
  • tickunit::Char: Time unit of one simulation step (tick)
  • startdate::Date: Start date of the simulation
  • enddate::Date: End date of the simulation
  • start_condition::StartCondition: Starting condition that sets the initial situation
  • prior_immunity::Vector{AbstractPriorImmunity}: Immunity acquired before the start, applied before the start condition
  • stop_criterion::StopCriterion: Criterion that terminates a simulation run
  • label::String: Label for plot visualizations
• Model
  • population::Population: Container to hold all present individuals
  • settings::SettingsContainer: All settings present in the simulation
  • pathogens::Tuple: A Tuple of Pathoges of which infections are simulated
• Logger
  • infectionlogger::InfectionLogger: A logger tracking all infections
  • deathlogger::DeathLogger: A logger specifically for the deaths of individuals
  • testlogger::TestLogger: A logger tracking all individual tests
  • pooltestlogger::PoolTestLogger: A logger tracking all pool tests
  • seroprevalencelogger::SeroprevalenceLogger: A logger tracking all seroprevalence tests
  • quarantinelogger::QuarantineLogger: A tracking cumulative quarantines per tick
  • customlogger::CustomLogger: A logger running custom methods on the Simulation object in each tick
• Interventions
  • symptom_triggers::Vector{ITrigger}: List of all SymptomTriggers
  • tick_triggers::Vector{TickTrigger}: List of all TickTriggers
  • hospitalization_triggers::Vector{ITrigger}: List of all HospitalizationTriggers
  • event_queue::EventQueue: Event Queue to apply intervention measures
  • strategies::Vector{Strategy}: List of all registered intervention strategies
  • testtypes::Vector{AbstractTestType}: List of all TestTypes (e.g. Antigen- or PCR-Test)
• Runtime Modifiers
  • stepmod::Function: Single-argment function that runs custom code on the simulation object in each tick
• RNG
  • seed::Int64: Seed used to initialize the main RNG
  • rngs::Vector{Xoshiro}: RNG instances for each thread

add_hospitalization_trigger!(simulation, trigger)

Adds a HospitalizationTrigger to the simulation.

add_strategy!(simulation, strategy)

Adds an intervention Strategy to the simulation object. A strategy must be added to the simulation object to make it appear in the report. In order to execute a strategy during the simulation run, you must define a Trigger and link this strategy. Just adding it here will not execute the strategy.

add_symptom_trigger!(simulation, trigger)

Adds a SymptomTrigger to the simulation.

add_testtype!(simulation, testtype)

Adds a test type to the simulation.

add_tick_trigger!(simulation, trigger)

Adds a TickTrigger to the simulation.

ags(patientzeros::PatientZeros)::Vector{Int64}

Returns the vector of ags where intial seeds should be planted.

configfile(simulation)

Returns configfile that was used to initialize simulation.

customlogger!(simulation, customlogger)

Sets the Simulation's CustomLogger.

customlogger(simulation)

Returns the CustomLogger of the simulation.

customlogs(simulation::Simulation)

Calls the dataframe() function on the internal simulation's CustomLogger.

deaths(simulation::Simulation)

Calls the dataframe() function on the internal simulation's DeathLogger.

deathlogger(simulation)

Returns the DeathLogger of the simulation.

event_queue(simulation)

Returns the simulation's intervention event queue.

fraction(infectedFraction::InfectedFraction)

Returns fraction of individuals that shall be infected at the beginning using the InfectedFraction start condition.

hospitalization_triggers(simulation)

Returns the list of HospitalizationTriggers registered in the simulation.

incidence(simulation::Simulation, pathogen::Pathogen, base_size::Int = 100_000, duration::Int16 = Int16(7))

Returns the incidence at a particular pathogen and a point in time (current simulation tick). The duration defines a time-span for which the incidence is measured (default: 7 ticks). The base_size provides the population size reference (default: 100_000 individuals)

Parameters

• simulation::Simulation: Simulation object
• pathogen::Pathogen: Pathogen for which the incidence shall be calculated
• base_size::Int = 100_000 (optional): Reference population size for incidence calculation
• duration::Int16 = Int16(7) (optional): Reference duration (in ticks) for the incidence calculation

Returns

• Float64: Incidence

incidence(simulation::Simulation, pathogen_id::Int8, base_size::Int = 100_000, duration::Int16 = Int16(7))

Convenience wrapper to calculate incidence using a pathogen ID.

incidence(simulation::Simulation, pathogen_name::String, base_size::Int = 100_000, duration::Int16 = Int16(7))

Convenience wrapper to calculate incidence using a pathogen name.

infectionlogger(simulation)

Returns the InfectionLogger of the simulation.

infections(simulation::Simulation)

Calls the dataframe() function on the internal simulation's InfectionLogger.

info(sim::Simulation)

Summary output for Simulation object configuration.

interval(trigger::TickTrigger)

Returns the interval associated with a TickTrigger.

label(simulation::Simulation)

Returns simulation object's string label.

limit(criterion::StopCriterion)

Returns the maximum number of ticks for the criterion, or nothing if the criterion does not have a fixed limit.

limit(timesUp::TimesUp)

Returns time limit of a timesUp stop criterion.

pathogen(sim::Simulation)

Returns the single pathogen in the simulation. Throws an ArgumentError if the simulation contains more than one pathogen; use pathogens(sim) or get_pathogen(sim, id) in that case.

pathogen(importedCases::ImportedCases)

Returns the pathogen used to seed the imported cases.

pathogen(infectedFraction::InfectedFraction)

Returns pathogen used to infect individuals at the beginning using the InfectedFraction start condition.

pathogen(patientzero::PatientZero)

Returns pathogen used to infect individuals at the beginning in this start condition.

pathogen(patientzeros::PatientZeros)

Returns pathogen used to infect individuals at the beginning in this start condition.

pathogen(regionalseeds::RegionalSeeds)

Returns pathogen used to infect individuals at the beginning using the RegionalSeeds start condition.

pooltests(simulation::Simulation)

Calls the dataframe() function on the internal simulation's PoolTestLogger.

pooltestlogger(simulation)

Returns the PoolTestLogger of the simulation.

population(simulation)

Returns the population associated with the simulation run.

populationDF(simulation::Simulation)

Calls the dataframe() function on the simulation's Population object.

populationfile(simulation)

Returns populationfile that was used to initialize simulation.

quarantinelogger(simulation)

Returns the QuarantineLogger of the simulation.

quarantines(simulation::Simulation)

Calls the dataframe() function on the internal simulation's QuarantineLogger.

reset!(simulation::Simulation; reset_interventions::Bool = false)

Resets the simulation model to its initial state according to its start condition. This resets all individuals, loggers, the event queue, tick, and RNGs, and re-applies the start condition. If reset_interventions is true (default), all intervention triggers and strategies are also cleared.

region_info(sim::Simulation)

Returns a DataFrame containing information about the Municipalitys in the model with the following columns:

Note: This function will download the Germany shapefile, if it's not available locally, and return missing values for pop_size and area if the download cannot be completed.

rng(simulation::Simulation)

Returns the thread-local RNG associated with the simulation run. This way, rng(simulation) can be called inside multi-threaded code to get the correct RNG for the current thread.

run!(simulation::Simulation; with_progressbar::Bool = true)

Takes and initializes Simulation object and calls the stepping function (step!) until the stop criterion is met.

Returns

• Simulation: Simulation object

seroprevalencelogger(simulation)

Returns the SeroprevalenceLogger of the simulation.

seroprevalencetests(simulation::Simulation)

Calls the dataframe() function on the internal simulation's SeroprevalenceLogger.

settings(simulation::Simulation)

Returns a dictionary containing all settings, separated by setting type (key).

settingscontainer(simulation::Simulation)

Returns the container object of all settings of the simulation.

should_fire(trigger::TickTrigger, tick::Int16)

Evaluates whether a trigger should be fired at a given tick. Considers switch_tick and interval.

Returns

• Bool: True, if the trigger should fire at this tick. False otherwise.

should_fire(trigger::TickTrigger, sim::Simulation)

Evaluates whether a trigger should be fired in the given simulation at its current tick. Considers switch_tick, interval, and the trigger's trigger-level condition.

Returns

• Bool: True, if the trigger should fire now. False otherwise.

start_condition(simulation)

Returns start condition associated with the simulation run.

start_condition(rd::ResultData)

Returns the StartCondition object the simulation was initialized with. Returns an empty dictionary if the data is not available in the input ResultData object.

statelogger(simulation)

Returns the StateLogger of the simulation.

states(simulation::Simulation)

Calls the dataframe() function on the internal simulation's StateLogger.

step!(simulation::Simulation)

Increments the simulation status by one tick and executes all events that shall be handled during this tick.

stepmod(simulation::Simulation)

Returns the defined step mod.

stop_criterion(simulation)

Returns stop criterion associated with the simulation run.

strategy(simulation)

Returns the intervention Strategys registered in the simulation.

symptom_triggers(simulation)

Returns the list of SymptomTriggers registered in the simulation.

testlogger(simulation)

Returns the TestLogger of the simulation.

tests(simulation::Simulation)

Calls the dataframe() function on the internal simulation's TestLogger.

testtypes(simulation)

Returns the test types registered in the simulation.

tick(simulation)

Returns current tick of the simulation run.

tick_triggers(simulation)

Returns the list of TickTriggers registered in the simulation.

tickunit(simulation)

Returns the unit of the ticks as a char like in date formats, i.e. 'd' means days, 'h' mean hours, etc.

supertype for all start conditions

InfectedFraction <: StartCondition

A StartCondition that specifies a fraction of infected individuals (drawn at random).

Fields

• fraction::Float64: A fraction of the whole population that has to be infected
• pathogen::String: Pathogen to infect the fraction with; empty string = the only pathogen, ALL_PATHOGENS = every pathogen (each infecting its own fraction)

Example

condition = InfectedFraction(fraction=0.05) # 5% of the population infected at random
sim = Simulation(start_condition = condition)

PatientZero <: StartCondition

A StartCondition that infects a single individual at random at the beginning of the simulation.

Fields

• pathogen::String: Pathogen to infect the individual with; empty string = the only pathogen, ALL_PATHOGENS = every pathogen (one individual each)

Example

condition = PatientZero() # single individual infected at random
sim = Simulation(start_condition = condition)

PatientZeros <: StartCondition

A StartCondition that infects a single individual in each of the given AGS (community identification numbers) at the beginning of the simulation.

Fields

• pathogen::String: Pathogen to infect the individuals with; empty string = the only pathogen, ALL_PATHOGENS = every pathogen
• ags::Vector{Int64}: A vector of AGS (community identification number) where the initial seeds should be planted

Example

# single individual infected at random in regions 13003000 and 13076033
# needs to be used with a population that contains these regions, e.g., "MV"
condition = PatientZeros(ags=[13003000, 13076033]) 
sim = Simulation(population = "MV", start_condition = condition)

RegionalSeeds <: StartCondition

A StartCondition that infects the provided number of individual at the beginning (drawn at random) in the regions provided by their AGS (community identification number).

Fields

• pathogen::String: Pathogen to infect the individual(s) with; empty string = the only pathogen, ALL_PATHOGENS = every pathogen
• seeds::Dict{Int64, Int64}: Dict that holds {AGS, NUMBER} pairs specifying the regions and the respective number of individuals that shall be infected at initialization.

Example

# 5 and 7 individuals infected at random in regions 13003000 and 13076033
# needs to be used with a population that contains these regions, e.g., "MV"
condition = RegionalSeeds(seeds = Dict(13003000=>5, 13076033=>7))
sim = Simulation(population = "MV", start_condition = condition)

ImportedCases <: StartCondition

A StartCondition that seeds infections at scheduled ticks during the run, modelling importation of cases. initialize! only stages the schedule; seed_scheduled! executes each import at its tick.

The three dimensions of an import schedule are independent, and each accepts several forms:

Fields

• pathogen::String: Pathogen to seed with; empty string = the only pathogen, ALL_PATHOGENS = every pathogen
• ticks: when imports happen
  • Integer: a single import at that tick
  • AbstractVector{<:Integer}: exactly these ticks (ranges included); a repeated tick schedules several imports on it
  • Function: f(sim) returning the ticks, resolved during initialize!
  • NamedTuple: window form (start_tick =, stop_tick =, interval =, offset =), where interval (gap between imports) and offset (gap from start_tick to the first import, default 0) are each a number or a Distribution
• count: how many individuals each import infects. An import sized below 1 is skipped, so a 0 entry keeps a per-import vector aligned with its ticks without seeding anything.
  • Integer: the same number every time
  • AbstractVector{<:Integer}: one entry per import
  • Distribution: drawn per import
  • Function: f(sim, tick) returning an integer
• ags: where the imports land; nothing seeds from the whole population
  • Integer: the same region every time
  • AbstractVector{<:Integer}: one region per import
  • Function: f(sim, tick) returning a community identification number

A vector ags has no way of saying "whole population" for individual entries. Combine several ImportedCases in a MultiStartCondition for mixed regional/nationwide schedules.

Each form is normalized by _ticks_spec/_count_spec/_region_spec at construction and evaluated by _resolve_ticks/_resolve_count/_resolve_region during initialize!. Both halves of a dimension live in the same section below, so a new form is added in one place.

Example

# 3 individuals every 7 ticks, from tick 30 to 200
condition = ImportedCases(count = 3, ticks = 30:7:200)

# the same, written as a window (the form config files use)
condition = ImportedCases(count = 3, ticks = (start_tick = 30, stop_tick = 200, interval = 7))

# a Poisson import process: on average one import every 10 ticks, 2 individuals each
condition = ImportedCases(count = 2,
    ticks = (start_tick = 30, stop_tick = 200, interval = Exponential(10), offset = Exponential(10)))

# two regions on the same tick, with per-import counts
condition = ImportedCases(ticks = [10, 10, 20], count = [5, 3, 1],
    ags = [13003000, 13076033, 13003000])

sim = Simulation(start_condition = condition)

initialize!(simulation::Simulation, condition::StartCondition; kwargs...)

Initializes the simulation model according to a provided start condition. This is an 'abstract' function that must be implemented for concrete start condition types.

initialize!(simulation)

Initializes the simulation model with its prior immunity and its start condition.

initialize!(simulation::Simulation, condition::ImportedCases)

Resolves the import schedule and stages one InfectionSeed per import in simulation.seeding_schedule; seeds nothing here (see seed_scheduled!).

initialize!(simulation::Simulation, condition::InfectedFraction; seed_sample::Union{Int64,Nothing}=nothing)

Initialize the simulation model with a fraction of infected individuals, provided by the start condition. For sampling the individuals to infect, a new Xoshiro RNG is created. If seed_sample is nothing (default), the seed is drawn from rng(simulation). Otherwise, the provided seed_sample is used.

initialize!(simulation::Simulation, condition::PatientZero)

Initialize the simulation model by infecting a single individual at random at the beginning of the simulation.

initialize!(simulation::Simulation, condition::PatientZeros)

Initializes the simulation model, infecting a single individual in each of the regions provided by their AGS (community identification number).

initialize!(simulation::Simulation, condition::RegionalSeeds; seed_sample::Union{Int64,Nothing}=nothing)

Initializes the simulation model, infecting the number of individuals in the regions, both provided by the RegionalSeeds start condition. Regions can be specified as states, counties or municipalities.

It would also be possible to provide, e.g., a municiaplity AND its surrounding county. In that case, an individual could be sampled twice. This function will not prevent that but throw a warning.

seeds(regionalseeds::RegionalSeeds)

Returns the dictionary holding the {AGS, NUMBER} pairs, specifying the regions (via community identification number (AGS)) and the number of initial infections using the RegionalSeeds start condition.

PriorImmunity(; pathogen = "", fraction, age_groups = String[], ags = nothing, ticks_ago)

Natural immunity that a fraction of the population (per age group and, optionally, within the region ags) acquired ticks_ago ticks before the start, a number or a Distribution drawn per individual.

Fields

• pathogen::String: Pathogen the immunity is against; empty string = the only pathogen, ALL_PATHOGENS = every pathogen (each with its own draw)
• fraction::Vector{Float64}: Fraction of each age group (or a single fraction for everyone) that is immune
• age_groups::Vector{AgeGroup}: Age groups; empty = no grouping, ages outside all groups get no immunity
• ags::Union{Int64, Nothing}: Community identification number of the region; nothing = whole population
• ticks_ago::Union{Float64, Distribution}: Ticks between acquisition and tick 0, between 1 and MAX_PRIOR_TICKS_AGO (16384). Values are rounded up; draws beyond the bounds are clamped.

Several entries for the same individual and pathogen overwrite each other; the last one applied wins.

Example

prior = PriorImmunity(age_groups = ["-17", "18-64", "65-"], fraction = [0.2, 0.35, 0.5], ticks_ago = Uniform(30, 365))
sim = Simulation(prior_immunity = prior)

supertype for all stop criteria

NoneInfected <: StopCriterion

A StopCriterion that stops the simulation once no individual is infected.

TimesUp <: StopCriterion

A StopCriterion that specifies a time limit.

Fields

• limit::Int16: A time limit. When reached, the simulation should be terminated.

Ticks are stored as Int16, so limit (and the reachable tick range in general) cannot exceed typemax(Int16) (32767)n

evaluate(simulation::Simulation, criterion::StopCriterion)

Evaluates whether the specified stop criterion is met for the simulation model. Return True if criterion was met. This is an 'abstract' function that must be implemented for concrete criterion types.

evaluate(simulation, criterion)

Returns true if none of the individuals are infected.

evaluate(simulation::Simulation, criterion::TimesUp)

Returns true if specified termination tick has been met.