laser.generic

laser.generic

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).

__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

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

Infect_Random_Agents(model, verbose=False)

A LASER model component that introduces random infections into the population at regular intervals. This is typically used to simulate importation events or background infection pressure.

Initialize an Infect_Random_Agents instance.

Parameters:

Name	Type	Description	Default
model	object	The LASER model object that contains the population, patches, and parameters. The following attributes must exist in model.params: - importation_period (int): Number of ticks between each infection event. - importation_count (int): Number of agents to infect per event. - nticks (int): Total number of ticks in the simulation. - importation_start (int, optional): First tick to introduce infections. Defaults to 0 if not provided. - importation_end (int, optional): Last tick to introduce infections. Defaults to nticks if not provided.	required
verbose	bool	If True, enables verbose output. Defaults to False.	False

Attributes:

Name	Type	Description
model	object	The LASER model object used by the component.
period	int	Number of ticks between infection events.
count	int	Number of agents infected at each event.
start	int	First tick to apply infections.
end	int	Last tick to apply infections.

__call__(model, tick)

Introduce random infections into the population at the given tick.

Infections are seeded if

• The current tick is greater than or equal to start.
• The tick falls on a multiple of period (relative to start).
• The tick is less than end.

This updates both the agent-level infections and, if present, the test arrays in model.patches for validation.

Parameters:

Name	Type	Description	Default
model	object	The LASER model containing the population and patches.	required
tick	int	The current tick (time step) of the simulation.	required

Returns:

Type	Description
None	None

plot(fig=None)

Placeholder for visualization of infection events.

Parameters:

Name	Type	Description	Default
fig	Figure	A matplotlib Figure to plot into. If None, no plot is generated.	None

Returns:

Type	Description
Any	None

Model(scenario, params, birthrates=None, name='generic', skip_capacity=False, states=None, additional_states=None)

Initialize the SI model.

Parameters:

Name	Type	Description	Default
scenario	GeoDataFrame	The scenario data containing per patch population, initial S and I counts, and geometry.	required
params	PropertySet	The parameters for the model, including 'nticks' and 'beta'.	required
birthrates	ndarray	Birth rates in CBR per patch per tick. Defaults to None.	None
name	str	Name of the model instance. Defaults to "generic".	'generic'
skip_capacity	bool	If True, skips capacity checks. Defaults to False.	False
states	list	List of state names. Defaults to None == {"S", "E", "I", "R"}.	None
additional_states	list	List of additional state names. Defaults to None.	None

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.

__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

plot(fig=None)

Placeholder for RI visualization.

Parameters:

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

get_default_parameters()

Returns a default PropertySet with common parameters used across laser-generic models.

Each parameter in the returned PropertySet is described below, along with its default value and rationale:

nticks (int, default=730): Number of simulation ticks (days). Default is 2 years (365*2), which is a typical duration for seasonal epidemic simulations.
beta (float, default=0.15): Transmission rate per contact. Chosen as a moderate value for SIR-type models to reflect realistic disease spread.
biweekly_beta_scalar (list of float, default=[1.0]*biweekly_steps): Scalar for beta for each biweekly period. Default is 1.0 for all periods, meaning no seasonal variation unless specified.
cbr (float, default=0.03): Constant birth rate. Set to 0.03 to represent a typical annual birth rate in people models.
exp_shape (float, default=2.0): Shape parameter for the exposed period distribution. Default chosen for moderate dispersion.
exp_scale (float, default=2.0): Scale parameter for the exposed period distribution. Default chosen for moderate mean duration.
inf_mean (float, default=4.0): Mean infectious period (days). Set to 4.0 to reflect typical infectious durations for diseases like measles.
inf_sigma (float, default=1.0): Standard deviation of infectious period. Default is 1.0 for moderate variability.
seasonality_factor (float, default=0.2): Amplitude of seasonal forcing. Chosen to allow moderate seasonal variation in transmission.
seasonality_phase (float, default=0.0): Phase offset for seasonality. Default is 0.0, meaning no phase shift.
importation_count (int, default=1): Number of cases imported per importation event. Default is 1 for sporadic importation.
importation_period (int, default=30): Days between importation events. Default is 30 to represent monthly importation.
importation_start (int, default=0): Start day for importation events. Default is 0 (simulation start).
importation_end (int, default=730): End day for importation events. Default is 2 years (365*2).
seed (int, default=123): Random seed for reproducibility. Default is 123.
verbose (bool, default=False): If True, enables verbose output. Default is False for minimal output.

These values are chosen to be broadly reasonable for seasonal SIR-type models with importation.

We need a function like this because even-though laser-core requires no particular param name, laser-generic code does presume certain parameters and there's no elegant way to just discover what those are. So we put them here.