The Population View

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

  1. To provide user access to subsets of the state table when it is safe to do so.

  2. To allow the user to update private data in a controlled way.

class vivarium.framework.population.population_view.PopulationView(manager, component, view_id)[source]

A read/write manager for the population state table.

It can be used to both read and update the state of the population. While a PopulationView can read any column, it can only write those columns that the component it is attached to created (i.e. that component’s private columns).

Attempts to update non-existent columns are ignored except during simulant creation when new columns are allowed to be created.

Parameters:
property name: str
property private_columns: list[str]

The names of private columns managed by this PopulationView.

These private columns are those that were created by the component that created this view.

get(index, attributes, query='', include_untracked=None, skip_post_processor=False, mode='default')[source]

Gets a specific subset of the population state table.

For the rows in index, return the attributes (i.e. columns) from the state table. The resulting rows may be further filtered by the call’s query and whether or not to include untracked simulants.

Parameters:

  • index (pd.Index[int]) – Index of the population to get. This may be further filtered by various query conditions.

  • attributes (str | list[str] | tuple[str, ...]) – The attributes to retrieve. If a single attribute is passed in via a string, the result will be squeezed to a Series if possible.

  • query (str) – Additional conditions used to filter the index.

  • include_untracked (bool | None) – Whether to include untracked simulants. If None (default), untracked simulants are excluded unless this pipeline was called during population creation or inside another pipeline call. Untracked simulants are always included if True and always excluded if False.

  • skip_post_processor (Literal[True, False]) – Whether we should invoke the post-processor on the combined source and mutator output or return without post-processing. This is useful when the post-processor acts as some sort of final unit conversion (e.g. the rescale post processor).

  • mode (Literal['default', 'source', 'no-post-processors']) – The mode for pipeline evaluation. One of “default”, “source”, or “no-post-processors”.

Return type:

Any

Notes

If skip_post_processor is True, the returned data will not be squeezed.

Returns:

The attribute(s) requested subset to the index and filtered using the various optional queries. If skip_post_processor is False, will return a Series if a single attribute is requested or a Dataframe otherwise.

Raises:

ValueError – If the result is expected to be a Series but is not. If an invalid mode is provided.

Parameters:

  • index (pd.Index[int])

  • attributes (str | list[str] | tuple[str, ...])

  • query (str)

  • include_untracked (bool | None)

  • skip_post_processor (Literal[True, False])

  • mode (Literal['default', 'source', 'no-post-processors'])

Return type:

Any

get_frame(index, attribute, query='', include_untracked=None)[source]

Gets a single attribute as a DataFrame.

For the rows in index, return the attributes (i.e. columns) from the state table. The resulting rows may be further filtered by the call’s query and whether or not to include untracked simulants.

Parameters:

  • index (pd.Index[int]) – Index of the population to get.

  • attribute (str) – The attribute to retrieve. This attribute may contain one or more columns.

  • query (str) – Additional conditions used to filter the index.

  • include_untracked (bool | None) – Whether to include untracked simulants. If None (default), untracked simulants are excluded unless this pipeline was called during population creation or inside another pipeline call. Untracked simulants are always included if True and always excluded if False.

Return type:

pd.DataFrame

Notes

The difference between this method and get is subtle. This method always returns a dataframe even if the requested attribute contains a single column. Further, in the event the attribute has multi-level columns, it will be squeezed to only return the inner columns.

Calling get to request a list of a single attribute seems identical to this, but in that case the underlying data would not be squeezed at all, i.e. a dataframe with multi-level columns would also return the outer columns.

Returns:

The attribute requested subset to the index and filtered using the various optional queries. Will always return a DataFrame.

Parameters:

  • index (pd.Index[int])

  • attribute (str)

  • query (str)

  • include_untracked (bool | None)

Return type:

pd.DataFrame

get_filtered_index(index, query='', include_untracked=None)[source]

Gets a specific index of the population.

The requested index may be further filtered by the call’s query and whether or not to include untracked simulants.

Parameters:

  • index (pd.Index[int]) – Index of the population to get.

  • query (str) – Additional conditions used to filter the index.

  • include_untracked (bool | None) – Whether to include untracked simulants. If None (default), untracked simulants are excluded unless this pipeline was called during population creation or inside another pipeline call. Untracked simulants are always included if True and always excluded if False.

Returns:

The requested and filtered population index.

Return type:

pd.Index[int]

initialize(data)[source]

Initialize private columns with the provided data.

Use this method during simulant initialization (both initial and when adding new simulants) to set the initial values of private columns. Column names are inferred from the data (Series name or DataFrame columns).

Parameters:

data (pd.Series[Any] | pd.DataFrame) – The initial values for private columns. If a pandas.Series, its name identifies the column. If a pandas.DataFrame, its column names identify the columns.

Raises:

  • PopulationError –

    • If this view is read-only. - If called outside of simulant initialization. - If the data contains columns not managed by this view. - If the data has simulants not in the population. - If the data is missing simulants during initial population creation.

  • TypeError – If the data is not a Series or DataFrame.

Return type:

None

update(columns, modifier)[source]

Update private columns by applying a modifier to the current data.

Read the current values of the specified private columns, pass them to modifier, and write the result back. The modifier receives a pandas.Series when columns is a string or a pandas.DataFrame when columns is a list. It should return data in the same form, optionally with a subset of the original index (in which case only those rows are updated).

Parameters:

  • columns (str | list[str]) – The private column(s) to update. A string for a single column or a list of strings for multiple columns.

  • modifier (Callable[..., pd.Series[Any] | pd.DataFrame]) – A callable that takes the current column data and returns the updated values. May return a subset of the original index to update only some rows.

Raises:

  • PopulationError –

    • If this view is read-only. - If the modifier returns data with unexpected columns or simulants.

  • TypeError – If the modifier does not return a Series, DataFrame, or scalar.

Return type:

None