Lookup Tables

Simulations tend to require a large quantity of data to run. vivarium provides the LookupTable abstraction to ensure that accurate data can be retrieved when it’s needed. It’s a callable object that takes in a population index and returns data specific to the individuals represented by that index. See the lookup concept note for more.

class vivarium.framework.lookup.table.LookupTable(table_number, data, population_view_builder=None, key_columns=(), parameter_columns=(), value_columns=(), interpolation_order=0, clock=None, extrapolate=True, validate=True)

A callable to produces values for a population index.

In vivarium simulations, the index is synonymous with the simulated population. The lookup system allows the user to provide different kinds of data and strategies for using that data. When the simulation is running, then, components can lookup parameter values based solely on the population index.

Notes

These should not be created directly. Use the lookup method on the builder during setup.

Parameters:

• table_number (int) –

• data (Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]) –

• population_view_builder (Callable) –

• key_columns (List[str] | Tuple[str]) –

• parameter_columns (List[str] | Tuple) –

• value_columns (List[str] | Tuple[str]) –

• interpolation_order (int) –

• clock (Callable) –

• extrapolate (bool) –

• validate (bool) –

table_number: int

Unique identifier of the table.

data: Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]

The data from which to build the interpolation.

population_view_builder: Callable = None

Callable to get a population view to be used by the lookup table.

key_columns: List[str] | Tuple[str] = ()

Column names to be used as categorical parameters in Interpolation to select between interpolation functions.

parameter_columns: List[str] | Tuple = ()

Column names to be used as continuous parameters in Interpolation.

value_columns: List[str] | Tuple[str] = ()

Names of value columns to be interpolated over.

interpolation_order: int = 0

Order of interpolation. Used to decide interpolation strategy.

clock: Callable = None

Callable for current time in simulation.

extrapolate: bool = True

Whether to extrapolate beyond edges of given bins.

validate: bool = True

Whether to validate the data before building the LookupTable.

property name: str

Tables are generically named after the order they were created.

abstract call(index)

Private method to allow LookupManager to add constraints.

Parameters:

index (Index) –

Return type:

DataFrame

class vivarium.framework.lookup.table.InterpolatedTable(table_number, data, population_view_builder, key_columns, parameter_columns, value_columns, interpolation_order, clock, extrapolate, validate)

A callable that interpolates data according to a given strategy.

Notes

These should not be created directly. Use the lookup interface on the builder during setup.

Parameters:

• table_number (int) –

• data (Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]) –

• population_view_builder (Callable) –

• key_columns (List[str] | Tuple[str]) –

• parameter_columns (List[str] | Tuple) –

• value_columns (List[str] | Tuple[str]) –

• interpolation_order (int) –

• clock (Callable) –

• extrapolate (bool) –

• validate (bool) –

call(index)

Get the interpolated values for the rows in index.

Parameters:

index (Index) – Index of the population to interpolate for.

Returns:

A table with the interpolated values for the population requested.

Return type:

pandas.DataFrame

class vivarium.framework.lookup.table.CategoricalTable(table_number, data, population_view_builder, key_columns, value_columns, **kwargs)

A callable that selects values from a table based on categorical parameters across an index.

Notes

These should not be created directly. Use the lookup interface on the builder during setup.

Parameters:

• table_number (int) –

• data (Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]) –

• population_view_builder (Callable) –

• key_columns (List[str] | Tuple[str]) –

• value_columns (List[str] | Tuple[str]) –

call(index)

Get the mapped values for the rows in index.

Parameters:

index (Index) – Index of the population to interpolate for.

Returns:

A table with the mapped values for the population requested.

Return type:

pandas.DataFrame

class vivarium.framework.lookup.table.ScalarTable(table_number, data, population_view_builder=None, key_columns=(), parameter_columns=(), value_columns=(), interpolation_order=0, clock=None, extrapolate=True, validate=True)

A callable that broadcasts a scalar or list of scalars over an index.

Notes

These should not be created directly. Use the lookup interface on the builder during setup.

Parameters:

• table_number (int) –

• data (Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]) –

• population_view_builder (Callable) –

• key_columns (List[str] | Tuple[str]) –

• parameter_columns (List[str] | Tuple) –

• value_columns (List[str] | Tuple[str]) –

• interpolation_order (int) –

• clock (Callable) –

• extrapolate (bool) –

• validate (bool) –

call(index)

Broadcast this tables values over the provided index.

Parameters:

index (Index) – Index of the population to construct table for.

Returns:

A table with a column for each of the scalar values for the population requested.

Return type:

pandas.DataFrame