LookupTable Interface

This module provides an interface to the LookupTableManager.

class vivarium.engine.framework.lookup.interface.LookupTableInterface(manager)

The interface to 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, name='', value_columns=None)

Construct and register a LookupTable from input data.

Data can be provided as a pandas.DataFrame, a pandas.Series, a scalar, or a list/tuple of scalars. The form of the input data determines what form the result of calling the resulting lookup table will take. If a scalar or list/tuple is provided, that result will be broadcast over the calling index. Scalars will return a Series, whereas a list/tuple will return a DataFrame. If a DataFrame or Series is provided, the returned columns will be in exactly the form of the input data.

Row-index level names that follow the <name>_start / <name>_end convention are treated as continuous binned ranges and interpolated using order 0 (step function) interpolation; other row-index level names are treated as exact-match categorical columns.

For indexed pandas.DataFrame / pandas.Series inputs (lookup attributes on the row index), value_columns must be None because value columns are inferred from the DataFrame columns or the Series name. For flat DataFrame inputs (deprecated), value_columns selects which column(s) are returned. For list/tuple inputs, value columns are required to name the resulting DataFrame columns. For scalar inputs, value columns can be provided to name the resulting Series column; if not provided, the resulting Series is named "value".

Deprecated since version 4.2.0: Passing a Mapping or a flat pandas.DataFrame (one whose row index is the default pandas.RangeIndex) is deprecated. Construct your DataFrame (or pandas.Series) with parameter/key columns on a named Index or MultiIndex and value columns as the DataFrame columns. Scalars and lists/tuples remain fully supported.

Parameters:

• data (LookupTableData) – The source data which will be used to build the resulting Lookup Table.

• name (str) – The name of the table. Defaults to ""; when empty, the manager assigns a generic "lookup_table_<n>" name. The stored table is keyed as "<component_name>.<name>" so an empty name produces a trailing dot in that key.

• value_columns (list[str] | tuple[str, ...] | str | None) – Names of the value column(s) of the resulting lookup table. Should only be provided for scalar or list/tuple input data.

Returns:

LookupTable

Raises:

ValueError – If value_columns is provided alongside an indexed pandas.DataFrame or pandas.Series.

Return type:

LookupTable[pd.Series[Any]] | LookupTable[pd.DataFrame]