The Core Population Model

This module contains tools for sampling and assigning core demographic characteristics to simulants.

class vivarium_public_health.population.base_population.BasePopulation

Component for producing and aging simulants based on demographic data.

CONFIGURATION_DEFAULTS: Dict[str, Any] = {'population': {'include_sex': 'Both', 'initialization_age_max': 125, 'initialization_age_min': 0, 'untracking_age': None}}

A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations.

property columns_created: List[str]

Provides names of columns created by the component.

Returns:

Names of the columns created by this component, or an empty list if none.

Return type:

List[str]

property time_step_priority: int

Provides the priority of this component’s time_step listener.

Returns:

The priority of this component’s time_step listener. This value can range from 0 to 9, inclusive.

Return type:

int

setup(builder)

Defines custom actions this component needs to run during the setup lifecycle phase.

This method is intended to be overridden by subclasses to perform any necessary setup operations specific to the component. By default, it does nothing.

Parameters:

builder (Builder) – The builder object used to set up the component.

Return type:

None

static get_randomness_streams(builder)

Parameters:

builder (Builder) –

Return type:

Dict[str, RandomnessStream]

on_initialize_simulants(pop_data)

Creates a population with fundamental demographic and simulation properties.

When the simulation framework creates new simulants (essentially producing a new set of simulant ids) and this component is being used, the newly created simulants arrive here first and are assigned the demographic qualities ‘age’, ‘sex’, and ‘location’ in a way that is consistent with the demographic distributions represented by the population-level data. Additionally, the simulants are assigned the simulation properties ‘alive’, ‘entrance_time’, and ‘exit_time’.

The ‘alive’ parameter is alive or dead. In general, most simulation components (except for those computing summary statistics) ignore simulants if they are not in the ‘alive’ category. The ‘entrance_time’ and ‘exit_time’ categories simply mark when the simulant enters or leaves the simulation, respectively. Here we are agnostic to the methods of entrance and exit (e.g., birth, migration, death, etc.) as these characteristics can be inferred from this column and other information about the simulant and the simulation parameters.

Parameters:

pop_data (SimulantData) –

Return type:

None

on_time_step(event)

Ages simulants each time step.

Parameters:

event (Event) –

Return type:

None

static get_demographic_proportions_for_creation_time(demographic_proportions, year)

Parameters:

year (int) –

Return type:

DataFrame

class vivarium_public_health.population.base_population.AgeOutSimulants

Component for handling aged-out simulants

property columns_required: List[str]

A list of the columns this component requires that it did not create.

setup(builder)

Defines custom actions this component needs to run during the setup lifecycle phase.

This method is intended to be overridden by subclasses to perform any necessary setup operations specific to the component. By default, it does nothing.

Parameters:

builder (Builder) – The builder object used to set up the component.

Return type:

None

on_time_step_cleanup(event)

Method that vivarium will run during the time_step__cleanup event.

This method is intended to be overridden by subclasses if there are operations they need to perform specifically during the time_step__cleanup event.

Parameters:

event (Event) – The event object associated with the time_step__cleanup event.

Return type:

None

vivarium_public_health.population.base_population.generate_population(simulant_ids, creation_time, step_size, age_params, demographic_proportions, randomness_streams, register_simulants, key_columns=('entrance_time', 'age'))

Produces a random set of simulants sampled from the provided population_data.

Parameters:

• simulant_ids (Index) – Values to serve as the index in the newly generated simulant DataFrame.

• creation_time (Timestamp) – The simulation time when the simulants are created.

• age_params (Dict[str, float]) –

  Dictionary with keys

  age_start : Start of an age range age_end : End of an age range

  The latter two keys can have values specified to generate simulants over an age range.

• demographic_proportions (DataFrame) – Table with columns ‘age’, ‘age_start’, ‘age_end’, ‘sex’, ‘year’, ‘location’, ‘population’, ‘P(sex, location, age| year)’, ‘P(sex, location | age, year)’.

• randomness_streams (Dict[str, RandomnessStream]) – Source of random number generation within the vivarium common random number framework.

• step_size (Timedelta) – The size of the initial time step.

• register_simulants (Callable[[DataFrame], None]) – A function to register the new simulants with the CRN framework.

• key_columns (Iterable[str]) – A list of key columns for random number generation.

Returns:

Table with columns

’entrance_time’

The pandas.Timestamp describing when the simulant entered the simulation. Set to creation_time for all simulants.

’exit_time’

The pandas.Timestamp describing when the simulant exited the simulation. Set initially to pandas.NaT.

’alive’

One of ‘alive’ or ‘dead’ indicating how the simulation interacts with the simulant.

’age’

The age of the simulant at the current time step.

’location’

The location indicating where the simulant resides.

’sex’

Either ‘Male’ or ‘Female’. The sex of the simulant.

Return type:

pandas.DataFrame