laser.generic.immunization

laser.generic.immunization

Immunization components for LASER models.

These components introduce immunity into the agent population during a simulation.

Notes

• Deployment is currently global (all patches). Future extensions may include:
• targeting by patch or lists of patches,
• patch-varying coverage,
• time-varying routine immunization (RI) coverage.
• The routine immunization window centers on the target age with width ≈ period, i.e., [age - period/2, age + period/2).

laser.generic.immunization.ImmunizationCampaign(model, period, coverage, age_lower, age_upper, start=0, end=-1, verbose=False)

A LASER component that applies an immunization campaign over an age band.

On eligible ticks, all agents with age in [age_lower, age_upper) are considered and immunized with probability coverage. Susceptibles become immune (population.susceptibility[idx] = 0). This aligns with the campaign-style immunization component described in the laser-generic docs.

Initialize an ImmunizationCampaign instance.

Parameters:

Name	Type	Description	Default
model	object	LASER Model with population, patches, and params. params.nticks must be defined.	required
period	int	Number of ticks between campaign events. Must be >= 1.	required
coverage	float	Per-event immunization probability in [0.0, 1.0].	required
age_lower	int	Inclusive lower bound of target age band (ticks).	required
age_upper	int	Exclusive upper bound of target age band (ticks). Must be > age_lower.	required
start	int	First tick (inclusive) to run campaigns. Default 0.	0
end	int	Last tick (exclusive) to run campaigns. If -1, defaults to model.params.nticks. Default -1.	-1
verbose	bool	Enable verbose logging. Default False.	False

Attributes:

Name	Type	Description
model	object	The LASER model instance.
period	int	Ticks between campaign events.
coverage	float	Immunization probability at each event.
age_lower	int	Inclusive lower age (ticks).
age_upper	int	Exclusive upper age (ticks).
start	int	First campaign tick (inclusive).
end	int	Last campaign tick (exclusive).
verbose	bool	Verbosity flag.

Raises:

Type	Description
ValueError	If inputs are out of range (e.g., period < 1, coverage not in [0, 1], age bounds invalid).

laser.generic.immunization.ImmunizationCampaign.__call__(model, tick)

Apply the immunization campaign at the given tick, if eligible.

Triggers when

tick >= start and ((tick - start) % period == 0) and tick < end

On each event

• Agents with age in [age_lower, age_upper) are considered.
• A Binomial draw with probability coverage selects agents to immunize.
• Selected agents have susceptibility set to 0 (immune).
• If present, test arrays on model.nodes are updated for validation.

Parameters:

Name	Type	Description	Default
model	object	LASER model (unused; provided for signature parity).	required
tick	int	Current simulation tick.	required

Returns:

Type	Description
None	None

laser.generic.immunization.ImmunizationCampaign.plot(fig=None)

Placeholder for campaign visualization.

Parameters:

Name	Type	Description	Default
fig	Figure	A Matplotlib Figure to draw into.	None

Returns:

Type	Description
None	None

laser.generic.immunization.RoutineImmunization(model, period, coverage, age, start=0, end=-1, verbose=False)

A LASER component that updates immunity via routine immunization (RI).

At eligible ticks, agents whose age (in ticks) falls within an RI window centered at age with half-width period // 2 are sampled with probability coverage and made immune (by setting population.susceptibility[idx] = 0).

This component follows the general component style in laser-generic and can be added to Model.components. See package documentation for details on the component pattern.

Initialize a RoutineImmunization instance.

Parameters:

Name	Type	Description	Default
model	object	LASER Model with population, patches, and params. params.nticks must be defined.	required
period	int	Number of ticks between RI events. Must be >= 1.	required
coverage	float	Per-event immunization probability in [0.0, 1.0].	required
age	int	Target age (in ticks) around which to immunize.	required
start	int	First tick (inclusive) to run RI. Default 0.	0
end	int	Last tick (exclusive) to run RI. If -1, defaults to model.params.nticks. Default -1.	-1
verbose	bool	Enable verbose logging. Default False.	False

Attributes:

Name	Type	Description
model	object	The LASER model instance.
period	int	Ticks between RI events.
coverage	float	Immunization probability at each event.
age	int	Target age in ticks.
start	int	First RI tick (inclusive).
end	int	Last RI tick (exclusive).
verbose	bool	Verbosity flag.

Raises:

Type	Description
ValueError	If period < 1, coverage not in [0, 1], or age < 0.

laser.generic.immunization.RoutineImmunization.__call__(model, tick)

Apply routine immunization at the given tick, if eligible.

An event fires when

tick >= start and ((tick - start) % period == 0) and tick < end

On each event

• Agents with age in [age - period//2, age + period//2) are considered.
• A Binomial draw with probability coverage selects agents to immunize.
• Selected agents have susceptibility set to 0 (immune).
• If present, test arrays on model.nodes are updated for validation.

Parameters:

Name	Type	Description	Default
model	object	LASER model (unused; provided for signature parity).	required
tick	int	Current simulation tick.	required

Returns:

Type	Description
None	None

laser.generic.immunization.RoutineImmunization.plot(fig=None)

Placeholder for RI visualization.

Parameters:

Name	Type	Description	Default
fig	Figure	A Matplotlib Figure to draw into.	None

laser.generic.immunization.immunize_in_age_window(model, lower, upper, coverage, tick)

Immunize susceptible agents whose age is in [lower, upper).

This function updates agent-level susceptibility and returns the corresponding node IDs for accounting or test-array updates.

Parameters:

Name	Type	Description	Default
model	object	LASER Model containing population with fields: - dob (array[int]): Agent date-of-birth ticks. - susceptibility (array[int|bool]): 1/True if susceptible, 0/False if immune. - nodeid (array[int]): Patch index per agent.	required
lower	int	Inclusive lower bound on age (in ticks). Clamped to >= 0.	required
upper	int	Exclusive upper bound on age (in ticks). Must be >= lower.	required
coverage	float	Probability in [0, 1] to immunize each eligible susceptible.	required
tick	int	Current simulation tick.	required

Returns:

Type	Description
Optional[ndarray]	np.ndarray | None: Array of nodeid for immunized agents, or None if none.

Raises:

Type	Description
ValueError	If upper < lower or coverage not in [0, 1].