laser.generic.SIS

`laser.generic.SIS`

Export required components for an SIS model.

Agents transition from Susceptible to Infectious upon infection and are infectious for a duration. Agents transition from Infectious back to Susceptible upon recovery.

`Infectious(model, infdurdist, infdurmin=1, validating=False)`

Infectious Component for SIS Models (Infection + Recovery to Susceptible)

This component handles the infectious state in SIS-style models, where agents recover from infection and immediately return to the susceptible pool. It supports per-agent infection durations and manages patch-level infectious counts over time.

Agents transition from Infectious back to Susceptible after the infectious period (itimer). Tracks number of agents recovering each tick in model.nodes.newly_recovered.

Responsibilities

Initializes infected agents and their infection timers (itimer)
Decrements itimer daily for infectious agents
Automatically transitions agents from INFECTIOUS to SUSCEPTIBLE when itimer == 0
Tracks per-day recoveries at the node level in model.nodes.recovered
Maintains node-level I and S counts with full timestep resolution

Required Inputs

model.scenario.I: initial number of infectious agents per patch
infdurdist: a callable function which samples the infectious duration distribution
infdurmin: the minimum infection period (default = 1 time step)

Outputs

model.people.itimer: per-agent infection countdown timer
model.nodes.I[t, i]: number of infectious individuals at tick t in node i
model.nodes.recovered[t, i]: number of recoveries at tick t in node i

Step Behavior

At each tick:

Infectious agents decrement their itimer
Agents with itimer == 0 are transitioned back to susceptible
model.nodes.I is updated accordingly
Recovered counts are recorded in model.nodes.recovered

Validation

Ensures consistency between agent state and infection timer (itimer)
Validates I census against agent-level state before and after each tick

Plotting

The plot() method displays both per-node and total infectious counts over time.

Examples:

model.components = [
    SIR.Susceptible(model),
    InfectiousIS(model, infdurdist),
    SIR.Transmission(model, ...),
]

`step(tick)`

Step function for the Infected component.

Parameters:

Name	Type	Description	Default
`tick`	`int`	The current tick of the simulation.	required

`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:

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:

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`