The Core Population Model

Provide tools for sampling and assigning core demographic characteristics to simulants.

class vivarium_public_health.population.base_population.BasePopulation

Produce and age simulants based on demographic data.

This component handles the initialization and lifecycle management of the core demographic attributes of the simulated population. At setup it loads a population structure from the artifact, computes demographic sampling proportions, and registers a population initializer that assigns each simulant an age, sex, location, entrance time, and exit time. On each time step simulants are aged forward by the step size.

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. Components will look for a data_sources block in this dictionary to build lookup tables automatically.

property time_step_priority: int

The event priority for base population time-step updates.

property time_step_cleanup_priority: int

The event priority for base population time-step cleanup.

setup(builder)

Load data, assign demographic proportions, and register the initializer.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

get_randomness_streams(builder)

Build and return the randomness streams used during population generation.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

dict[str, RandomnessStream]

Returns:

A dictionary mapping stream name to a RandomnessStream. Keys are:

'general_purpose'

Used for overall population generation.

'bin_selection'

Used for selecting demographic age bins when initializing with age bounds.

'age_smoothing'

Used for smoothing ages within a bin at a fixed initial age.

'age_smoothing_age_bounds'

Used for smoothing ages when initializing with a range of ages.

initialize_population(pop_data)

Create a population with fundamental demographic and simulation properties.

Parameters:

pop_data (SimulantData) – Metadata about the simulants being initialized.

Return type:

None

Notes

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 ‘entrance_time’ and ‘exit_time’.

The ‘exit_time’ attribute simply marks when the simulant exits the simulation. Here we are agnostic to the methods of exit (e.g., aging out, dying, etc.) as this characteristic can be inferred from this column and other information about the simulant and the simulation parameters.

The ‘exit_time’ attribute is unique in that it is created by this BasePopulation component but we expect other components to be able to modify it as needed (e.g., a Mortality component might change the ‘exit_time’ when a simulant dies). We do this by having the components register attribute modifiers as necessary and then have the BasePopulation component update the underlying private column data accordingly.

on_time_step(event)

Age simulants each time step by the step size.

Parameters:

event (Event) – The event that triggered this method call.

Return type:

None

on_time_step_cleanup(event)

Update the ‘exit_time’ private column with modifications from other components.

Parameters:

event (Event) – The event that triggered this method call.

Return type:

None

static get_demographic_proportions_for_creation_time(demographic_proportions, year)

Subset the demographic proportions table to the closest reference year.

Parameters:

• demographic_proportions – Full table of demographic proportions across all reference years, with a year_start column.

• year (int) – The simulation year for which to retrieve proportions.

Return type:

DataFrame

Returns:

Rows from demographic_proportions whose year_start matches the closest reference year that is less than or equal to year.

class vivarium_public_health.population.base_population.ScaledPopulation(scaling_factor)

Produce and age simulants from a rescaled population structure.

Use this component in place of BasePopulation when simulants represent a subset of the true population. The base population structure is multiplied element-wise by a scaling_factor before simulants are drawn.

Parameters:

scaling_factor (str | DataFrame)

scaling_factor

A multiplicative scaling factor applied to the population structure. May be a pandas.DataFrame or a string artifact key whose data resolves to a pandas.DataFrame.

Example

When specifying via a model configuration file:

components:
    vivarium_public_health:
        population:
            - ScaledPopulation("some.artifact.key")

class vivarium_public_health.population.base_population.AgeOutSimulants

Remove simulants that age beyond the tracking threshold.

When population.untracking_age is configured, simulants that reach or exceed that age are marked as is_aged_out = True during the cleanup phase and subsequently untracked. The exit time for aged-out simulants is set via an exit_time attribute modifier.

setup(builder)

Set up the component by registering the age-out modifier and initializer.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None

update_exit_times(index, target)

Update exit times for simulants who have aged out of the simulation.

Return type:

Series

Parameters:

• index (Index)

• target (Series)

initialize_is_aged_out(pop_data)

Initialize the is_aged_out column to False for all new simulants.

Parameters:

pop_data (SimulantData) – Metadata about the simulants being initialized.

Return type:

None

on_time_step_cleanup(event)

Mark simulants that have exceeded the untracking age as aged out.

Parameters:

event (Event) – The event that triggered this method call.

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

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

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

• age_params (dict[str, float]) –

  Dictionary with keys:

  • age_start: Start of an age range.

  • age_end: End of an age range.

  These keys specify the age interval to use for generating simulants.

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

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

Return type:

DataFrame

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.

’age’

The age of the simulant at the current time step.

’location’

The location indicating where the simulant resides.

’sex’

The sex of the simulant (‘Male’ or ‘Female’).

Notes

This function branches on whether age_start == age_end to handle two distinct initialization strategies with different common random number (CRN) registration requirements:

• Fixed initial age (age_start == age_end): Calls _assign_demography_with_initial_age.

  This applies age fuzz smoothing and registers entrance_time and age to the CRN framework.

• Age range (age_start != age_end): Calls _assign_demography_with_age_bounds.

  This selects from age bins, smooths ages further, and registers the customizable key_columns to the CRN framework.

This branching pattern is necessary because the required CRN attributes differ between the two cases. Rather than specify required_resources in the framework upfront, this initializer defers that distinction to runtime based on the provided age parameters.

class vivarium_public_health.population.base_population.Disability

Handle disability-related attributes and values.

Currently this component only sets up the all-cause disability weight pipeline.

disability_weight_pipeline

Name of the pipeline used to produce disability weights.

setup(builder)

Register the all-cause disability weight pipeline.

Parameters:

builder (Builder) – Access point for utilizing framework interfaces during setup.

Return type:

None