laser.generic.utils

laser.generic.utils

This module provides utility functions for the laser-measles project.

laser.generic.utils.TimingContext(label, stats, parent)

Internal class for timing context management.

laser.generic.utils.ValuesMap(nnodes, nticks)

A class to efficiently represent values mapped over nodes and time steps.

Parameters:

Name	Type	Description	Default
nnodes	int	Number of nodes.	required
nticks	int	Number of time steps.	required

Methods to create ValuesMap from different data sources

• from_scalar(scalar: float, nticks: int, nnodes: int)
• from_timeseries(data: np.ndarray, nnodes: int)
• from_nodes(data: np.ndarray, nticks: int)
• from_array(data: np.ndarray, writeable: bool = False)

laser.generic.utils.ValuesMap.nnodes property

Number of nodes.

laser.generic.utils.ValuesMap.nticks property

Number of time steps.

laser.generic.utils.ValuesMap.shape property

Shape of the underlying data array (nticks, nnodes).

laser.generic.utils.ValuesMap.values property

Underlying data array of shape (nticks, nnodes).

laser.generic.utils.ValuesMap.from_array(data, writeable=False) staticmethod

Create a ValuesMap from a 2D array of data.

Parameters:

Name	Type	Description	Default
data	ndarray	2D array of shape (nticks, nnodes).	required
writeable	bool	If True, the underlying data array is writeable and can be modified during simulation. Default is False.	False

Returns:

Name	Type	Description
ValuesMap	ValuesMap	The created ValuesMap instance.

laser.generic.utils.ValuesMap.from_nodes(data, nticks) staticmethod

Create a ValuesMap from a nodes array for all time steps.

All time steps have the same node data.

nnodes is inferred from the length of data.

Parameters:

Name	Type	Description	Default
data	ndarray	1D array of node data.	required
nticks	int	Number of time steps.	required

Returns:

Name	Type	Description
ValuesMap	ValuesMap	The created ValuesMap instance.

laser.generic.utils.ValuesMap.from_scalar(scalar, nticks, nnodes) staticmethod

Create a ValuesMap with the same scalar value for all nodes and time steps.

Parameters:

Name	Type	Description	Default
scalar	float	The scalar value to fill the map.	required
nnodes	int	Number of nodes.	required
nticks	int	Number of time steps.	required

Returns:

Name	Type	Description
ValuesMap	ValuesMap	The created ValuesMap instance.

laser.generic.utils.ValuesMap.from_timeseries(data, nnodes, nticks=None) staticmethod

Create a ValuesMap from a time series array for all nodes.

All nodes have the same time series data.

nticks is inferred from the length of data if not explicitly provided.

Parameters:

Name	Type	Description	Default
data	ndarray	1D array of time series data.	required
nnodes	int	Number of nodes.	required
nticks	int	Number of ticks. Defaults to None.	None

Returns:

Name	Type	Description
ValuesMap	ValuesMap	The created ValuesMap instance.

laser.generic.utils.get_centroids(gdf)

Get centroids of geometries in gdf in degrees (EPSG:4326).

laser.generic.utils.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.

laser.generic.utils.seed_infections_in_patch(model, ipatch, ninfections=1)

Seed initial infections in a specific patch of the people at the start of the simulation.

This function randomly selects up to ninfections individuals from the specified patch who are currently susceptible (state == State.SUSCEPTIBLE) and marks them as infected by: - Setting their infection timer (itimer) to the model's mean infectious duration (inf_mean), - Setting their infection state to State.INFECTIOUS.

Parameters:

Name	Type	Description	Default
model	Any	The simulation model containing the people and parameters. It must expose: - model.people.state (integer infection state), - model.people.itimer (infection timers), - model.people.nodeid (patch index), - model.params.inf_mean (mean infectious period).	required
ipatch	int	The identifier of the patch where infections should be seeded.	required
ninfections	int	The number of initial infections to seed. Defaults to 1.	1

Returns:

Type	Description
None	None

laser.generic.utils.seed_infections_randomly(model, ninfections=100)

Randomly seed initial infections across the entire people.

This function selects up to ninfections susceptible individuals at random from the full people. It marks them as infected by: - Setting their infection timer (itimer) to the model's mean infectious duration (inf_mean), - Setting their susceptibility to zero.

Parameters:

Name	Type	Description	Default
model	Any	The simulation model, which must contain a people with susceptibility, itimer, and nodeid arrays, and a params object with inf_mean.	required
ninfections	int	The number of individuals to infect. Defaults to 100.	100

Returns:

Type	Description
ndarray	np.ndarray: The node IDs of the newly infected individuals.

laser.generic.utils.validate(pre, post)

Decorator to add pre- and post-validation to a method.

Calls the given pre- and post-validation methods if the model or component is in validating mode.