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.InterpolatedTable(data, population_view, key_columns, parameter_columns, value_columns, interpolation_order, clock, extrapolate, validate)

A callable that interpolates data according to a given strategy.

Parameters:

• data (DataFrame) –

• population_view (PopulationView) –

• 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) –

data

The data from which to build the interpolation.

population_view

View of the population to be used when the table is called with an index.

key_columns

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

parameter_columns

Column names to be used as continuous parameters in Interpolation.

value_columns

Names of value columns to be interpolated over. All non parameter- and key- columns in data.

interpolation_order

Order of interpolation. Used to decide interpolation strategy.

clock

Callable for current time in simulation.

extrapolate

Whether or not to extrapolate beyond edges of given bins.

Notes

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

class vivarium.framework.lookup.ScalarTable(values, value_columns)

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

Parameters:

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

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

values

The scalar value(s) from which to build table columns.

value_columns

List of string names to be used to name the columns of the table built from values.

Notes

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

class vivarium.framework.lookup.LookupTable(table_number, data, population_view, key_columns, parameter_columns, value_columns, interpolation_order, clock, extrapolate, validate)

Wrapper for different strategies for looking up values for an 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 (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) –

property name: str

Tables are generically named after the order they were created.

vivarium.framework.lookup.validate_parameters(data, key_columns, parameter_columns, value_columns)

Makes sure the data format agrees with the provided column layout.

Parameters:

• data (DataFrame) –

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

• parameter_columns (List[str] | Tuple) –

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

class vivarium.framework.lookup.LookupTableManager

Manages complex data in the simulation.

Notes

Client code should never access this class directly. Use lookup on the builder during setup to get references to LookupTable objects.

configuration_defaults = {'interpolation': {'extrapolate': True, 'order': 0, 'validate': True}}

property name

setup(builder)

build_table(data, key_columns, parameter_columns, value_columns)

Construct a lookup table from input data.

Parameters:

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

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

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

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

Return type:

LookupTable

class vivarium.framework.lookup.LookupTableInterface(manager)

The lookup table management system.

Simulations tend to require a large quantity of data to run. vivarium provides the Lookup Table abstraction to ensure that accurate data can be retrieved when it’s needed.

For more information, see here.

Parameters:

manager (LookupTableManager) –

build_table(data, key_columns=None, parameter_columns=None, value_columns=None)

Construct a LookupTable from input data.

If data is a pandas.DataFrame, an interpolation function of the order specified in the simulation configuration will be calculated for each permutation of the set of key_columns. The columns in parameter_columns will be used as parameters for the interpolation functions which will estimate all remaining columns in the table.

If data is a number, time, list, or tuple, a scalar table will be constructed with the values in data as the values in each column of the table, named according to value_columns.

Parameters:

• data (Number | timedelta | datetime | DataFrame | List[Number | timedelta | datetime] | Tuple[Number | timedelta | datetime]) – The source data which will be used to build the resulting LookupTable.

• key_columns (List[str] | Tuple[str] | None) – Columns used to select between interpolation functions. These should be the non-continuous variables in the data. For example ‘sex’ in data about a population.

• parameter_columns (List[str] | Tuple[str] | None) – The columns which contain the parameters to the interpolation functions. These should be the continuous variables. For example ‘age’ in data about a population.

• value_columns (List[str] | Tuple[str] | None) – The data columns that will be in the resulting LookupTable. Columns to be interpolated over if interpolation or the names of the columns in the scalar table.

Return type:

LookupTable