Skip to content

laser.generic.SIRS

laser.generic.SIRS

Export required components for an SIRS model.

Agents transition from Susceptible to Infectious upon infection. Agents transition from Infectious to Recovered upon recovery after the infectious duration. Agents transition from Recovered back to Susceptible upon waning immunity after the waning duration.

Infectious(model, infdurdist, wandurdist, infdurmin=1, wandurmin=1, validating=False)

Infectious Component for SIRS/SEIRS Models (Recovery with Waning Immunity)

This component manages infectious individuals in models where recovery confers temporary immunity, after which agents become susceptible again (SIRS/SEIRS).

Agents transition from Infectious to Recovered after the infectious period (itimer). Set the waning immunity timer (rtimer) upon recovery. Tracks number of agents recovering each tick in model.nodes.newly_recovered.

Responsibilities
  • Initializes infectious agents from model.scenario.I
  • Assigns and tracks infectious timers (itimer) per agent
  • Transitions agents from INFECTIOUS to RECOVERED when itimer == 0
  • Assigns a waning immunity timer (rtimer) upon recovery
  • Updates patch-level state:
    • I[t, i]: current infectious count
    • R[t, i]: current recovered count
    • recovered[t, i]: number of agents recovering on tick t
Required Inputs
  • model.scenario.I: number of initially infected agents per node
  • infdurdist: function that samples the infectious duration distribution
  • wandurdist: function that samples the waning immunity duration distribution
  • infdurmin: minimum infectious period (default = 1 day)
  • wandurmin: minimum duration of immunity (default = 1 day)
Outputs
  • model.people.itimer: days remaining in the infectious state
  • model.people.rtimer: days remaining in the recovered state
  • model.nodes.I, model.nodes.R: counts per node per tick
  • model.nodes.recovered[t]: number of recoveries recorded on tick t
Step Behavior
  • Infectious agents decrement their itimer
  • When itimer == 0, agents become recovered and receive an rtimer
  • Patch-level totals are updated
  • Downstream components (e.g., Recovered) handle rtimer countdown and eventual return to SUSCEPTIBLE
Validation
  • Ensures timer consistency and population accounting
  • Confirms correct infectious-to-recovered transitions
  • Can be chained with recovery and waning components for full SIRS/SEIRS loops
Plotting

Two plots are provided:

  1. Infected counts per node
  2. Total infected and recovered counts across time

Examples:

1
2
3
4
5
6
model.components = [
    SIR.Susceptible(model),
    InfectiousIRS(model, infdurdist, wandurdist),
    Exposed(model, ...),
    Recovered(model),
]

step(tick)

Step function for the Infected component.

Parameters:

Name Type Description Default
tick int

The current tick of the simulation.

 required

Recovered(model, wandurdist, wandurmin=1, validating=False)

Recovered Component for SIRS/SEIRS Models (Waning Immunity)

This component manages agents in the recovered state in models where immunity is temporary. It supports per-agent recovery timers, enabling individuals to return to the susceptible state after a configurable waning period. This is essential for SEIRS/SIRS model dynamics.

Agents transition from Recovered back to Susceptible after the waning immunity period (rtimer). Tracks number of agents losing immunity each tick in model.nodes.newly_waned.

Responsibilities
  • Initializes agents in the RECOVERED state using model.scenario.R
  • Assigns rtimer values to track the duration of immunity
  • Decrements rtimer each tick; transitions agents to SUSCEPTIBLE when rtimer == 0
  • Updates patch-level counts:
    • R[t, i]: number of recovered individuals in node i at time t
    • waned[t, i]: number of agents who re-entered susceptibility on time step t
Required Inputs
  • model.scenario.R: initial number of recovered individuals per node
  • wandurdist: a function sampling the waning immunity duration distribution
  • wandurmin: minimum duration of immunity (default = 1 time step)
Outputs
  • model.people.rtimer: per-agent countdown to immunity expiration
  • model.nodes.R: recovered count per patch per timestep
  • model.nodes.waned: number of immunity losses per patch per tick
Step Behavior
  • Agents with state == RECOVERED decrement rtimer
  • When rtimer == 0, they return to SUSCEPTIBLE
  • R and S counts are updated to reflect this transition
  • waned[t] logs the number of agents who lost immunity on time step t
Validation
  • Ensures population conservation and consistency between agent states and patch totals
  • Detects unexpected changes in R or invalid transitions
Plotting

The plot() method provides two views:

  1. Per-node recovered trajectories
  2. Total recovered and waned agents over time

Examples:

1
2
3
4
5
6
model.components = [
    SIR.Susceptible(model),
    SEIRS.Infectious(model, infdurdist, wandurdist),
    Exposed(model, ...),
    RecoveredRS(model, wandurdist),
]

Susceptible(model, validating=False)

Susceptible Component for Patch-Based Agent-Based Models (S, SI, SIS, SIR, SEIR, etc.)

This component initializes and tracks the count of susceptible individuals (S) in a spatially structured agent-based model. It is compatible with all standard LASER disease progression models that include a "susceptible" state.

Responsibilities
  • Initializes agent-level properties:
    • nodeid: Patch ID of each agent (uint16)
    • state: Infection state (int8), defaulting to State.SUSCEPTIBLE
  • Initializes node-level property:
    • S[t, i]: Susceptible count in node i at time t
  • At each timestep, propagates the susceptible count forward (S[t+1] = S[t]), unless modified by other components (e.g., exposure, births).
  • Validates consistency between patch-level susceptible counts and agent-level state.
Usage

Add this component early in the component list for any model with SUSCEPTIBLE agents, typically before transmission or exposure components. Compatible with:

  • SIR.Transmission
  • SIR.Exposure
  • SIR.Infectious
  • SIR.Recovered
  • Custom SEIRS extensions
Requires
  • model.people: A LaserFrame for all agents
  • model.nodes: Patch-level state
  • model.scenario: Input DataFrame with population and optionally S columns
  • model.params.nticks: Number of simulation ticks
Validation
  • Ensures consistency of susceptible counts before and after each step
  • Prevents unintentional state drift by validating against agent state values
Output
  • model.nodes.S: A (nticks+1, num_nodes) array of susceptible counts
  • Optional plotting via plot() for visual inspection of per-node and total S
Step Behavior

For tick t: S[t+1] = S[t] # Unless explicitly modified by other components

This component does not alter agent states directly but serves as a synchronized counter and validator of susceptible individuals.

Examples:

1
2
3
4
5
6
7
model.components = [
    SIR.Susceptible(model),
    SIR.Transmission(model, ...),
    SIR.Exposure(model),
    SIR.Infectious(model, ...),
    SIR.Recovered(model),
]

Transmission(model, infdurdist, infdurmin=1, seasonality=None, validating=False)

Transmission Component for SIS/SIR/SIRS Models (S → I with Duration)

This component simulates the transition from SUSCEPTIBLE to INFECTIOUS in models where infectious individuals have a finite infection duration (itimer). It supports full spatial coupling and allows infection durations to vary by node and tick.

Agents transition from Susceptible to Infectious based on force of infection. Sets newly infectious agents' infection timers (itimer) based on infdurdist and infdurmin. Tracks number of new infections each tick in model.nodes.newly_infected.

Responsibilities
  • Computes force of infection (FOI) λ = β * (I / N) per patch each tick
  • Applies optional spatial coupling via model.network (infection pressure transfer)
  • Converts FOI into Bernoulli probabilities using p = 1 - exp(-λ)
  • Infects susceptible agents stochastically, assigning per-agent itimer
  • Updates patch-level susceptible (S) and infectious (I) counts
  • Records number of new infections per tick in model.nodes.newly_infected
Required Inputs
  • model.params.beta: transmission rate (global)
  • model.network: [n x n] matrix of transmission coupling
  • infdurdist(tick, node): callable sampling the infectious duration distribution
  • model.people.itimer: preallocated per-agent infection timer
Outputs
  • model.nodes.forces[t, i]: computed FOI in node i at time t
  • model.nodes.newly_infected[t, i]: new infections in node i on time step t
Step Behavior
  • Computes FOI (λ) for each node
  • Applies inter-node infection pressure via model.network
  • Converts FOI into a Bernoulli probability using: p = 1 - exp(-λ)
  • Infects susceptible agents probabilistically
  • Updates state and records incidence
Validation
  • Ensures consistency between incidence and change in I
  • Checks for correct state and population accounting before and after tick
Plotting

The plot() method visualizes per-node FOI (λ) over simulation time.

Examples:

1
2
3
4
5
model.components = [
    SIR.Susceptible(model),
    TransmissionSI(model, infdurdist),
    InfectiousIR(model, infdurdist),
]

Initializes the TransmissionSI component.

Parameters:

Name Type Description Default
model Model

The epidemiological model instance.

 required
infdurdist Callable[[int, int], float]

A function that returns the infectious duration for a given tick and node.

 required
infdurmin int

Minimum infectious duration.

 1
seasonality Union[ValuesMap, ndarray]

Seasonality modifier for transmission rate. Defaults to None.

 None
validating bool

Enable component-level validation. Defaults to False.

 False