The Population Management System

This module provides tools for managing the state table in a vivarium simulation, which is the record of all simulants in a simulation and their state. It’s main tasks are managing the creation of new simulants and providing the ability for components to view and update simulant state safely during runtime.

exception vivarium.framework.population.PopulationError[source]

Error raised when the population is invalidly queried or updated.

class vivarium.framework.population.PopulationView(manager, view_id, columns=(), query=None)[source]

A read/write manager for the simulation state table.

It can be used to both read and update the state of the population. A PopulationView can only read and write columns for which it is configured. Attempts to update non-existent columns are ignored except during simulant creation when new columns are allowed to be created.

Parameters:
  • manager (PopulationManager) – The population manager for the simulation.
  • columns (Union[List[str], Tuple[str], None]) – The set of columns this view should have access too. If explicitly specified as None, this view will have access to the entire state table.
  • query (Optional[str]) – A pandas-style filter that will be applied any time this view is read from.

Notes

By default, this view will filter out untracked simulants unless the tracked column is specified in the initialization arguments.

name
columns

The columns that the view can read and update.

If the view was created with None as the columns argument, then the view will have access to the full table by default. That case should be only be used in situations where the full state table is actually needed, like for some metrics collection applications.

Return type:List[str]
query

A pandas style query to filter the rows of this view.

This query will be applied any time the view is read. This query may reference columns not in the view’s columns.

Return type:str
subview(columns)[source]

Retrieves a new view with a subset of this view’s columns.

Parameters:columns (Union[List[str], Tuple[str]]) – The set of columns to provide access to in the subview. Must be a proper subset of this view’s columns.
Returns:
Return type:A new view with access to the requested columns.
Raises:PopulationError – If the requested columns are not a proper subset of this view’s columns.

Notes

Subviews are useful during population initialization. The original view may contain both columns that a component needs to create and update as well as columns that the component needs to read. By requesting a subview, a component can read the sections it needs without running the risk of trying to access uncreated columns because the component itself has not created them.

get(index, query='')[source]

Select the rows represented by the given index from this view.

For the rows in index get the columns from the simulation’s state table to which this view has access. The resulting rows may be further filtered by the view’s query and only return a subset of the population represented by the index.

Parameters:
  • index (Index) – Index of the population to get.
  • query (str) – Additional conditions used to filter the index. These conditions will be unioned with the default query of this view. The query provided may use columns that this view does not have access to.
Returns:

Return type:

A table with the subset of the population requested.

Raises:

PopulationError – If this view has access to columns that have not yet been created and this method is called. If you see this error, you should request a subview with the columns you need read access to.

See also

subview <PopulationView.subview()

update(population_update)[source]

Updates the state table with the provided data.

Parameters:population_update (Union[DataFrame, Series]) – The data which should be copied into the simulation’s state. If the update is a pandas.DataFrame, it can contain a subset of the view’s columns but no extra columns. If pop is a pandas.Series it must have a name that matches one of this view’s columns unless the view only has one column in which case the Series will be assumed to refer to that regardless of its name.
Raises:PopulationError – If the provided data name or columns does not match columns that this view manages or if the view is being updated with a data type inconsistent with the original population data.
class vivarium.framework.population.SimulantData[source]

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.

index

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

user_data

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

creation_time

The time when the simulants enter the simulation.

creation_window

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

index

Alias for field number 0

user_data

Alias for field number 1

creation_time

Alias for field number 2

creation_window

Alias for field number 3

class vivarium.framework.population.InitializerComponentSet[source]

Set of unique components with population initializers.

add(initializer, columns_produced)[source]

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.PopulationManager[source]

Manages the state of the simulated population.

configuration_defaults = {'population': {'population_size': 100}}
name

The name of this component.

setup(builder)[source]

Registers the population manager with other vivarium systems.

on_initialize_simulants(pop_data)[source]

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

metrics(index, metrics)[source]

Reports tracked and untracked population sizes at simulation end.

get_view(columns, query=None)[source]

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.

Parameters:
  • columns (Union[List[str], Tuple[str]]) – A subset of the state table columns that will be available in the returned view.
  • query (Optional[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=())[source]

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()[source]

Gets a function that can generate new simulants.

Return type:Callable
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.
get_population(untracked)[source]

Provides a copy of the full population state table.

Parameters:untracked (bool) – Whether to include untracked simulants in the returned population.
Returns:
Return type:A copy of the population table.
class vivarium.framework.population.PopulationInterface(manager)[source]

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.

get_view(columns, query=None)[source]

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.

Parameters:
  • columns (Union[List[str], Tuple[str]]) – A subset of the state table columns that will be available in the returned view.
  • query (Optional[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()[source]

Gets a function that can generate new simulants.

Return type:Callable[[int, Optional[Dict[str, Any]]], Index]
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.
initializes_simulants(initializer, creates_columns=(), requires_columns=(), requires_values=(), requires_streams=())[source]

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.