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)[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.
- Parameters:
- class vivarium.framework.population.manager.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:
- 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[source]
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.
- on_initialize_simulants(pop_data)[source]
Adds a
tracked
column to the state table for new simulants.- Parameters:
pop_data (SimulantData) –
- 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. 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 thecolumns
argument.
- Returns:
A filtered view of the requested columns of the population state table.
- Return type:
- 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.
- 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
- class vivarium.framework.population.manager.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
orstate 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 bypopulation 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 toFalse
.- Parameters:
manager (PopulationManager) –
- 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. 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 thecolumns
argument.
- Returns:
A filtered view of the requested columns of the population state table.
- Return type:
- get_simulant_creator()[source]
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:
- 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.