Skip to content

epymorph.initializer

Initializers are responsible for setting up the initial conditions for the simulation: the populations at each node, and which disease compartments they belong to. There are potentially many ways to do this, driven by source data from the geo or simulation parameters, so this module provides a uniform interface to accomplish the task, as well as a few common implementations.

Initializer

Bases: SimulationFunction[SimArray], ABC

Represents an initialization routine responsible for determining the initial values of populations by IPM compartment for every simulation node.

as_compartment 

as_compartment(name_or_index: int | str) -> int

Convert a compartment identifier to a compartment index. You can specify a string -- which will be interpreted as a compartment name -- or an integer -- which will be interpreted as an index. Raises InitException if the compartment identifier is not valid.

validate 

validate(result) -> None

Override this method to validate the function evaluation result. If not overridden, the default is to do no validation. Implementations should raise an appropriate error if results are not valid.

Parameters:

  • result (ResultT) –

    The result produced from function evaluation.

NoInfection 

NoInfection(initial_compartment: int | str = 0)

Bases: Initializer

An initializer that places all 'population' individuals in a single compartment (default: the first compartment).

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR,)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

initial_compartment instance-attribute 

initial_compartment: int | str = initial_compartment

The IPM compartment where people should start, as either a name or index.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

Explicit 

Explicit(initials: NDArray | list[list[int]])

Bases: Initializer

An initializer that sets all compartment populations directly. You provide the (N,C) array and we use a copy of it.

initials instance-attribute 

initials: NDArray | list[list[int]] = initials

The initial compartment values to use.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

Proportional 

Proportional(
    ratios: NDArray[int64 | float64]
    | list[int]
    | list[float]
    | list[list[int]]
    | list[list[float]],
)

Bases: Initializer

Set all compartments as a proportion of their population according to the geo. The parameter array provided to this initializer will be normalized, then multiplied element-wise by the geo population. So you're free to express the proportions in any way, (as long as no row is zero). Parameters: - ratios a (C,) or (N,C) numpy array describing the ratios for each compartment

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR,)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

ratios instance-attribute 

ratios: (
    NDArray[int64 | float64]
    | list[int]
    | list[float]
    | list[list[int]]
    | list[list[float]]
) = ratios

The initialization ratios to use.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

SeededInfection 

SeededInfection(
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: Initializer, ABC

Abstract base class for initializers which seed an infection to start. We assume most people start out in a particular compartment (default: the first) and if chosen for infection, are placed in another compartment (default: the second). The user can identify which two compartments to use, but it can only be two compartments. Parameters: - initial_compartment which compartment (by index) is "not infected", where most individuals start out - infection_compartment which compartment (by index) will be seeded as the initial infection

DEFAULT_INITIAL class-attribute instance-attribute 

DEFAULT_INITIAL = 0

DEFAULT_INFECTION class-attribute instance-attribute 

DEFAULT_INFECTION = 1

initial_compartment instance-attribute 

initial_compartment: int | str = initial_compartment

The IPM compartment for non-infected individuals.

infection_compartment instance-attribute 

infection_compartment: int | str = infection_compartment

The IPM compartment for infected individuals.

IndexedLocations 

IndexedLocations(
    selection: NDArray[intp] | list[int],
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: SeededInfection

Infect a fixed number of people distributed (proportional to their population) across a selection of nodes. A multivariate hypergeometric draw using the available populations is used to distribute infections. Parameters: - selection a one-dimensional array of indices; all values must be in range (-N,+N) - seed_size the number of individuals to infect in total

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR,)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

selection instance-attribute 

selection: NDArray[intp] | list[int] = selection

Which locations to infect.

seed_size instance-attribute 

seed_size: int = seed_size

How many individuals to infect, randomly distributed to selected locations.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

SingleLocation 

SingleLocation(
    location: int,
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: IndexedLocations

Infect a fixed number of people at a single location (by index). Parameters: - location the index of the node in which to seed an initial infection - seed_size the number of individuals to infect in total

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR,)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

LabeledLocations 

LabeledLocations(
    labels: NDArray[str_] | list[str],
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: SeededInfection

Infect a fixed number of people distributed to a selection of locations (by label). Parameters: - labels the labels of the locations to select for infection - seed_size the number of individuals to infect in total

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR, _LABEL_ATTR)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

labels instance-attribute 

labels: NDArray[str_] | list[str] = labels

Which locations to infect.

seed_size instance-attribute 

seed_size: int = seed_size

How many individuals to infect, randomly distributed to selected locations.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

RandomLocations 

RandomLocations(
    num_locations: int,
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: SeededInfection

Seed an infection in a number of randomly selected locations. Parameters: - num_locations the number of locations to choose - seed_size the number of individuals to infect in total

requirements class-attribute instance-attribute 

requirements = (_POPULATION_ATTR,)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

num_locations instance-attribute 

num_locations: int = num_locations

The number of locations to choose (randomly).

seed_size instance-attribute 

seed_size: int = seed_size

How many individuals to infect, randomly distributed to selected locations.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

TopLocations 

TopLocations(
    top_attribute: AttributeDef[type[int]]
    | AttributeDef[type[float]],
    num_locations: int,
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: SeededInfection

Infect a fixed number of people across a fixed number of locations, selecting the top locations as measured by a given geo attribute.

top_attribute instance-attribute 

top_attribute: (
    AttributeDef[type[int]] | AttributeDef[type[float]]
) = top_attribute

The attribute to by which to judge the 'top' locations. Must be an N-shaped attribute.

requirements instance-attribute 

requirements = (_POPULATION_ATTR, top_attribute)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

num_locations instance-attribute 

num_locations: int = num_locations

The number of locations to choose (randomly).

seed_size instance-attribute 

seed_size: int = seed_size

How many individuals to infect, randomly distributed between all selected locations.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns:

BottomLocations 

BottomLocations(
    bottom_attribute: AttributeDef[type[int]]
    | AttributeDef[type[float]],
    num_locations: int,
    seed_size: int,
    initial_compartment: int | str = DEFAULT_INITIAL,
    infection_compartment: int | str = DEFAULT_INFECTION,
)

Bases: SeededInfection

Infect a fixed number of people across a fixed number of locations, selecting the bottom locations as measured by a given geo attribute.

bottom_attribute instance-attribute 

bottom_attribute: (
    AttributeDef[type[int]] | AttributeDef[type[float]]
) = bottom_attribute

The attribute to by which to judge the 'bottom' locations. Must be an N-shaped attribute.

requirements instance-attribute 

requirements = (_POPULATION_ATTR, bottom_attribute)

The attribute definitions describing the data requirements for this function.

For advanced use-cases, you may specify requirements as a property if you need it to be dynamically computed.

num_locations instance-attribute 

num_locations: int = num_locations

The number of locations to choose (randomly).

seed_size instance-attribute 

seed_size: int = seed_size

How many individuals to infect, randomly distributed between all selected locations.

evaluate 

evaluate() -> SimArray

Implement this method to provide logic for the function. Use self methods and properties to access the simulation context or defer processing to another function.

Returns: