The Population Manager

The manager and builder interface for the population management system.

class vivarium.framework.population.manager.SimulantData(index, user_data, creation_time, creation_window)

Data to help components initialize simulants.

Any time simulants are added to the simulation, each initializer is called with this structure containing information relevant to their initialization.

Parameters:

• index (Index) –

• user_data (Dict[str, Any]) –

• creation_time (Timestamp) –

• creation_window (Timedelta) –

index: Index

The index representing the new simulants being added to the simulation.

user_data: Dict[str, Any]

A dictionary of extra data passed in by the component creating the population.

creation_time: Timestamp

The time when the simulants enter the simulation.

creation_window: Timedelta

The span of time over which the simulants are created. Useful for, e.g., distributing ages over the window.

class vivarium.framework.population.manager.InitializerComponentSet

Set of unique components with population initializers.

add(initializer, columns_produced)

Adds an initializer and columns to the set, enforcing uniqueness.

Parameters:

• initializer (Callable) – The population initializer to add to the set.

• columns_produced (List[str]) – The columns the initializer produces.

Raises:

• TypeError – If the initializer is not an object method.

• AttributeError – If the object bound to the method does not have a name attribute.

• PopulationError – If the component bound to the method already has an initializer registered or if the columns produced are duplicates of columns another initializer produces.

class vivarium.framework.population.manager.PopulationManager

Manages the state of the simulated population.

CONFIGURATION_DEFAULTS: Dict[str, Any] = {'population': {'population_size': 100}}

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

property name

The name of this component.

setup(builder)

Registers the population manager with other vivarium systems.

on_initialize_simulants(pop_data)

Adds a tracked column to the state table for new simulants.

Parameters:

pop_data (SimulantData) –

property columns: List[str]

The columns that currently exist in the state table.

get_view(columns, query=None)

Get a time-varying view of the population state table.

The requested population view can be used to view the current state or to update the state with new values.

If the column ‘tracked’ is not specified in the columns argument, the query string ‘tracked == True’ will be added to the provided query argument. This allows components to ignore untracked simulants by default. If the columns argument is empty, the population view will have access to the entire state table.

Parameters:

• columns (List[str] | Tuple[str]) – A subset of the state table columns that will be available in the returned view. If empty, this view will have access to the entire state table.

• query (str) – A filter on the population state. This filters out particular simulants (rows in the state table) based on their current state. The query should be provided in a way that is understood by the pandas.DataFrame.query() method and may reference state table columns not requested in the columns argument.

Returns:

A filtered view of the requested columns of the population state table.

Return type:

PopulationView

register_simulant_initializer(initializer, creates_columns=(), requires_columns=(), requires_values=(), requires_streams=())

Marks a source of initial state information for new simulants.

Parameters:

• initializer (Callable) – A callable that adds or updates initial state information about new simulants.

• creates_columns (List[str]) – A list of the state table columns that the given initializer provides the initial state information for.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the provided initializer is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the provided initializer is called.

• requires_streams (List[str]) – A list of the randomness streams necessary to initialize the simulant attributes.

get_simulant_creator()

Gets a function that can generate new simulants.

Returns:

The simulant creator function. The creator function takes the number of simulants to be created as it’s first argument and a dict population configuration that will be available to simulant initializers as it’s second argument. It generates the new rows in the population state table and then calls each initializer registered with the population system with a data object containing the state table index of the new simulants, the configuration info passed to the creator, the current simulation time, and the size of the next time step.

Return type:

Callable

get_population(untracked)

Provides a copy of the full population state table.

Parameters:

untracked (bool) – Whether to include untracked simulants in the returned population.

Returns:

A copy of the population table.

Return type:

pandas.DataFrame

class vivarium.framework.population.manager.PopulationInterface(manager)

Provides access to the system for reading and updating the population.

The most important aspect of the simulation state is the population table or state table. It is a table with a row for every individual or cohort (referred to as a simulant) being simulated and a column for each of the attributes of the simulant being modeled. All access to the state table is mediated by population views, which may be requested from this system during setup time.

The population system itself manages a single attribute of simulants called tracked. This attribute allows global control of which simulants are available to read and update in the state table by default.

For example, in a simulation of childhood illness, we might not need information about individuals or cohorts once they reach five years of age, and so we can have them “age out” of the simulation at five years old by setting the tracked attribute to False.

Parameters:

manager (PopulationManager) –

get_view(columns, query=None)

Get a time-varying view of the population state table.

The requested population view can be used to view the current state or to update the state with new values.

If the column ‘tracked’ is not specified in the columns argument, the query string ‘tracked == True’ will be added to the provided query argument. This allows components to ignore untracked simulants by default. If the columns argument is empty, the population view will have access to the entire state table.

Parameters:

• columns (List[str] | Tuple[str]) – A subset of the state table columns that will be available in the returned view. If empty, this view will have access to the entire state table.

• query (str) – A filter on the population state. This filters out particular simulants (rows in the state table) based on their current state. The query should be provided in a way that is understood by the pandas.DataFrame.query() method and may reference state table columns not requested in the columns argument.

Returns:

A filtered view of the requested columns of the population state table.

Return type:

PopulationView

get_simulant_creator()

Gets a function that can generate new simulants.

Returns:

• The simulant creator function. The creator function takes the

• number of simulants to be created as it’s first argument and a dict

• population configuration that will be available to simulant

• initializers as it’s second argument. It generates the new rows in

• the population state table and then calls each initializer

• registered with the population system with a data

• object containing the state table index of the new simulants, the

• configuration info passed to the creator, the current simulation

• time, and the size of the next time step.

Return type:

Callable[[int, Dict[str, Any] | None], Index]

initializes_simulants(initializer, creates_columns=(), requires_columns=(), requires_values=(), requires_streams=())

Marks a source of initial state information for new simulants.

Parameters:

• initializer (Callable[[SimulantData], None]) – A callable that adds or updates initial state information about new simulants.

• creates_columns (List[str]) – A list of the state table columns that the given initializer provides the initial state information for.

• requires_columns (List[str]) – A list of the state table columns that already need to be present and populated in the state table before the provided initializer is called.

• requires_values (List[str]) – A list of the value pipelines that need to be properly sourced before the provided initializer is called.

• requires_streams (List[str]) – A list of the randomness streams necessary to initialize the simulant attributes.