laser.generic.SEIR

`laser.generic.SEIR`

Export required components for an SEIR model.

Agents transition from Susceptible to Exposed upon infection, with an incubation duration. Agents transition from Exposed to Infectious after the incubation period and are infectious for a duration. Agents transition from Infectious to Recovered after the infectious period. Agents remain in the Recovered state indefinitely (no waning immunity).

`laser.generic.SEIR.Exposed(model, expdurdist, infdurdist, expdurmin=1, infdurmin=1, validating=False)`

Exposed Component for SEIR/SEIRS Models with Explicit Incubation Period

This component handles the incubation phase in models where agents must transition from an 'exposed' (E) state to 'infectious' (I) after a delay. It supports custom incubation and infectious duration distributions and handles both initialization and per-tick dynamics.

Agents transition from Exposed to Infectious when their incubation timer (etimer) expires. Tracks number of agents becoming infectious each tick in model.nodes.newly_infectious.

Responsibilities: - Initializes exposed individuals at time 0 (if provided in the scenario) - Assigns and tracks per-agent incubation timers (etimer) - Transitions agents from EXPOSED to INFECTIOUS when etimer == 0 - Assigns new infection timers (itimer) upon becoming infectious - Updates patch-level EXPOSED (E) and INFECTIOUS case counts - Provides validation hooks for state and timer consistency

Required Inputs: - model.scenario.E: initial count of exposed individuals per node (optional) - expdurdist: callable returning sampled incubation durations - infdurdist: callable returning sampled infectious durations - expdurmin: minimum incubation period (default 1 day) - infdurmin: minimum infectious period (default 1 day)

Outputs: - model.people.etimer: agent-level incubation timer - model.nodes.E[t, i]: number of exposed individuals at time t in node i - model.nodes.newly_infectious[t, i]: number of newly infectious cases per node per day

Validation: - Ensures consistency between individual states and etimer values - Ensures that agents becoming infectious have valid itimer values assigned - Prevents agents with expired etimer from remaining in EXPOSED state

Step Behavior

For each agent: - Decrease etimer - If etimer == 0, change state to INFECTIOUS and assign itimer - Update model.nodes.E and model.nodes.I counts accordingly

Plotting: The plot() method provides a time series of exposed individuals per node and total across all nodes.

Example

model.components = [ SIR.Susceptible(model), Exposed(model, expdurdist, infdurdist), SIR.Infectious(model, infdurdist), ... ]

`laser.generic.SEIR.Infectious(model, infdurdist, infdurmin=1, validating=False)`

Infectious Component for SIR/SEIR Models (With Recovery to Immune)

This component manages agents in the infectious state for models where infected individuals recover permanently (i.e., transition to a RECOVERED state without waning). It supports agent-level infection durations and patch-level tracking of recoveries over time.

Infectious component for an SIR/SEIR model - includes infectious duration, no waning immunity in newly_recovered state.

Agents transition from Infectious to Recovered 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) based on scenario input - Decrements itimer daily for infectious agents - Transitions agents from INFECTIOUS to RECOVERED when itimer == 0 - Updates patch-level state variables: • I[t, i]: infectious count at tick t in node i • R[t, i]: recovered count • recovered[t, i]: number of recoveries during tick t

Required Inputs: - model.scenario.I: number of initially infected individuals per patch - infdurdist: function returning infection durations - infdurmin: minimum infectious period (default = 1 day)

Outputs: - model.people.itimer: countdown timers per agent - model.nodes.I[t], .R[t]: infectious and recovered counts per patch - model.nodes.recovered[t]: daily recoveries per patch

Step Behavior: - Infectious agents decrement itimer - When itimer == 0, agent state is set to RECOVERED - Patch-level I and R are updated; recovered logs today's transitions

Validation: - Ensures internal consistency between agent state and timer - Confirms agents with itimer == 1 recover exactly one day later - Validates population conservation (S + I + R = N)

Plotting: The plot() method shows per-node and total infectious counts across time.

Example

model.components = [ SIR.Susceptible(model), InfectiousIR(model, infdurdist), SIR.Recovered(model), ... ]

`laser.generic.SEIR.Infectious.step(tick)`

Step function for the Infected component.

Parameters:

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

`laser.generic.SEIR.Recovered(model, validating=False)`

Recovered Component for SIR/SEIR Models (Permanent Immunity)

This component manages agents in the recovered state in models where immunity does not wane (i.e., once recovered, agents stay recovered permanently). It tracks the number of recovered individuals over time at the patch level, but performs no active transitions itself — recovery transitions must be handled by upstream components.

Responsibilities: - Initializes agents as recovered if specified in model.scenario.R - Tracks per-patch recovered counts over time in model.nodes.R - Verifies consistency between agent state and aggregate recovered counts - Propagates recovered totals forward unchanged (unless modified by other components)

Required Inputs: - model.scenario.R: number of initially recovered individuals per node

Outputs: - model.nodes.R[t, i]: number of recovered individuals at tick t in node i

Step Behavior: - At each tick, carries forward: R[t+1] = R[t] - This component does not change any agent's state or internal timers

🧪 Validation: - Ensures per-agent state matches aggregate R counts before and after each step - Detects accidental changes to recovered counts not explained by upstream logic

Plotting: The plot() method shows per-node and total recovered counts over time.

Example

model.components = [ SIR.Susceptible(model), InfectiousIR(model, infdurdist), Recovered(model), # passive tracker, assumes recovery handled upstream ]

`laser.generic.SEIR.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.

Example

model.components = [ SIR.Susceptible(model), SIR.Transmission(model, ...), SIR.Exposure(model), SIR.Infectious(model, ...), SIR.Recovered(model), ]

`laser.generic.SEIR.Transmission(model, expdurdist, expdurmin=1, seasonality=None, validating=False)`

Transmission component for an SEIR/SEIRS model with S -> E transition and incubation duration.

This component simulates the transition from `SUSCEPTIBLE` to `EXPOSED` in models
where infection includes an incubation period before agents become infectious.
It handles stochastic exposure based on per-node force of infection (FOI), and
assigns individual incubation timers to newly exposed agents.

Agents transition from Susceptible to Exposed based on force of infection.
Sets newly exposed agents' infection timers (etimer) based on `expdurdist` and `expdurmin`.
Tracks number of new infections each tick in `model.nodes.newly_infected`.

Responsibilities:
- Computes force of infection `λ = β * (I / N)` at each tick per node
- Adjusts FOI using `model.network` for inter-node transmission coupling. Required but can be nullified by filling with all zeros.
- Applies FOI to susceptible agents to determine exposure
- Assigns incubation durations (`etimer`) to each newly exposed agent
- Updates node-level counts for `S` and `E` and logs daily incidence

Required Inputs:
- `model.params.beta`: global transmission rate
- `model.network`: [n x n] matrix for FOI migration
- `expdurdist(tick, node)`: callable that samples the exposure/incubation duration distribution
- `expdurmin`: minimum incubation period (default = 1)

Outputs:
- `model.nodes.forces[t, i]`: computed FOI in node `i` at tick `t`
- `model.nodes.incidence[t, i]`: new exposures per node per day
- `model.people.etimer`: per-agent incubation countdown

Step Behavior:
- Computes FOI (`λ`) for each node
- Optionally 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:
- Validates consistency between agent states and patch-level counts before and after tick
- Confirms that `incidence[t] == E[t+1] - E[t]`

Plotting:
The `plot()` method shows per-node FOI (`λ`) trajectories over time.

Example:
    model.components = [
        SIR.Susceptible(model),
        TransmissionSE(model, expdurdist),
        Exposed(model, ...),
        InfectiousIR(model, ...),
        Recovered(model),
    ]

Initializes the TransmissionSE component.

Parameters:

Name	Type	Description	Default
`model`	`Model`	The epidemiological model instance.	required
`expdurdist`	`Callable[[int, int], float]`	A function that returns the incubation duration for a given tick and node.	required
`expdurmin`	`int`	Minimum incubation 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`