The Population View
To provide user access to subsets of the simulation state table when it is safe to do so.
To allow the user to update the simulation state in a controlled way.
- class vivarium.framework.population.population_view.PopulationView(manager, view_id, columns=(), query=None)
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.
manager (PopulationManager) – The population manager for the simulation.
view_id (int) –
By default, this view will filter out
untrackedsimulants unless the
trackedcolumn is specified in the initialization arguments.
- property name
- property columns: List[str]
The columns that the view can read and update.
If the view was created with
Noneas 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.
- property query: Optional[str]
pandasstyle 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.
Retrieves a new view with a subset of this view’s columns.
A new view with access to the requested columns.
- Return type
PopulationError – If the requested columns are not a proper subset of this view’s columns or no columns are requested.
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='')
Select the rows represented by the given index from this view.
For the rows in
indexget 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.
A table with the subset of the population requested.
- Return type
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.
Updates the state table with the provided data.
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
pandas.Seriesit 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.
PopulationError – If the provided data name or columns do not match columns that this view manages or if the view is being updated with a data type inconsistent with the original population data.
- Return type