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. It may draw from simulation parameters to do so. As there are many valid ways to do this, this module provides a uniform interface to accomplish the task as well as a few common implementations.

Initializer

Bases: SimulationFunction[SimArray], ABC

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.

Parameters:

  • name_or_index (int | str) –

    Identifies the compartment; usually a compartment name. However this can also be an integer index, in which case we check that the index is valid and then return it.

Raises:

  • InitError –

    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 individuals in a single compartment. Requires "population" as a data attribute.

Parameters:

  • initial_compartment (int | str, default: 0 ) –

    The compartment name or index in which to start the population.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

Explicit 

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

Bases: Initializer

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

Parameters:

initials instance-attribute 

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

The initial compartment values to use.

evaluate 

evaluate() -> SimArray

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

Proportional 

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

Bases: Initializer

An initializer that sets all compartments as a proportion of their population. Requires "population" as a data attribute.

Parameters:

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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 initial infection. It assumes most people start out in a particular compartment (default: the first) and if chosen for infection, are moved to another compartment (default: the second).

You can customize which two compartments to use, but it can only be two.

Parameters:

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

DEFAULT_INITIAL class-attribute instance-attribute 

DEFAULT_INITIAL: ClassVar = 0

DEFAULT_INFECTION class-attribute instance-attribute 

DEFAULT_INFECTION: ClassVar = 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 in each node is used to distribute infections.

Requires "population" as a data attribute.

Parameters:

  • selection (NDArray[intp] | list[int]) –

    The list of node indices to infect; all values must be in range (-N,+N).

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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

Requires "population" as a data attribute.

Parameters:

  • location (int) –

    The index of the node in which to seed an initial infection.

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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

Requires "population" and "label" as data attributes.

Parameters:

  • labels (NDArray[str_] | list[str]) –

    The labels of the locations to select for infection.

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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.

Requires "population" as a data attribute.

Parameters:

  • num_locations (int) –

    The number of locations to choose.

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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 data attribute.

Requires "population" and the top attribute as data attributes.

Parameters:

  • top_attribute (AttributeDef[type[int]] | AttributeDef[type[float]]) –

    The attribute to use in determining the "top" locations. Must be numeric data.

  • num_locations (int) –

    The number of locations to choose.

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.

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.

Requires "population" and the bottom attribute as data attributes.

Parameters:

  • bottom_attribute (AttributeDef[type[int]] | AttributeDef[type[float]]) –

    The attribute to use in determining the "bottom" locations. Must be numeric data.

  • num_locations (int) –

    The number of locations to choose.

  • seed_size (int) –

    The number of individuals to infect in total.

  • initial_compartment (int | str, default: DEFAULT_INITIAL ) –

    Which compartment (by index or name) is "not infected", where most individuals start out.

  • infection_compartment (int | str, default: DEFAULT_INFECTION ) –

    Which compartment (by index or name) will be seeded as the initial infection.

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

Evaluate the initializer in the current context.

Returns:

  • SimArray –

    The initial populations for each node and IPM compartment.