The Population View

The PopulationView is a user-facing abstraction that manages read and write access to the underlying simulation State Table. It has two primary responsibilities:

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)[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 (List[str] | Tuple[str]) – The set of columns this view should have access too. If empty, this view will have access to the entire state table.
query (str) – A pandas-style filter that will be applied any time this view is read from.
view_id (int) –

Notes

By default, this view will filter out untracked simulants unless the tracked column 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 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.

property query: str | None

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.

subview(columns)[source]

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

Parameters:: columns (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:: A new view with access to the requested columns.
Return type:: PopulationView
Raises:: PopulationError – If the requested columns are not a proper subset of this view’s columns or no columns are requested.

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:

A table with the subset of the population requested.

Return type:

pandas.DataFrame

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.