Interpolation

Provides interpolation algorithms across tabular data for vivarium simulations.

vivarium.engine.framework.lookup.interpolation.has_named_row_index(data)[source]

Return True if data carries its lookup attributes on the row index.

Parameters:

data (LookupTableData)

Return type:

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

class vivarium.engine.framework.lookup.interpolation.Interpolation(data, value_columns, order, extrapolate, validate)[source]

A callable that interpolates value columns over categorical/continuous parameters.

Lookup attributes are inferred from the input data: when the data has its lookup attributes in the row index (see has_named_row_index()), the row-index level names are the attributes; when the data is a flat DataFrame (deprecated), the attributes are the columns not listed in value_columns. Attributes whose names follow the <name>_start / <name>_end convention are paired up as continuous binned parameters; all other attributes are treated as categorical key columns.

This naming convention is the only way Interpolation distinguishes continuous from categorical parameters, so the class is not fully generic — it is the interpolation primitive that LookupTable is built on.

Parameters:

  • data (pd.DataFrame | pd.Series[Any])

  • value_columns (pd.Index[Any])

  • order (int)

  • extrapolate (bool)

  • validate (bool)

value_columns: pd.Index[Any]

User-facing column labels (including tuple labels from a column MultiIndex and None from a nameless Series) restored on the output of __call__().

continuous_parameters: list[str]

Lookup attributes used as binned ranges. The base name (e.g. "age") of each <name>_start / <name>_end pair.

categorical_parameters: list[str]

Lookup attributes used to select between interpolation sub-tables.

data: pd.DataFrame

Flat DataFrame the interpolation pipeline operates on. Value columns are renamed to opaque internal IDs (see _FLAT_COLUMN_PREFIX); value_columns carries the original user-facing labels and is reapplied to the output of __call__().

order: int

Order of interpolation. Only 0 is currently supported.

extrapolate: bool

Whether to extrapolate beyond the edges of the supplied bins.

validate: bool

Whether to validate inputs on construction and on call.

interpolations: dict[Any, Order0Interp]

Per-categorical-group Order0Interp instances, keyed by the categorical-parameter tuple (or None when there are no categorical parameters).

vivarium.engine.framework.lookup.interpolation.validate_parameters(data, categorical_parameters, continuous_parameters, value_columns)[source]
Return type:

None

Parameters:
vivarium.engine.framework.lookup.interpolation.validate_call_data(data, categorical_parameters, continuous_parameters)[source]
Return type:

None

Parameters:
vivarium.engine.framework.lookup.interpolation.check_data_complete(data, continuous_parameters)[source]

Check that data is complete for interpolation.

For any parameters specified with edges, make sure edges don’t overlap and don’t have any gaps. Assumes that edges are specified with ends and starts overlapping (but one exclusive and the other inclusive) so can check that end of previous == start of current.

If multiple parameters, make sure all combinations of parameters are present in data.

Requires that bins of each parameter be standard across all values of other parameters, i.e., all bins for one parameter when de-duplicated should cover a continuous range of that parameter with no overlaps or gaps and the range covered should be the same for all combinations of other parameter values.

Return type:

None

Raises:

  • ValueError – If there are missing values for every combinations of continuous parameters.

  • ValueError – If the parameter data contains overlaps.

  • NotImplementedError – If a parameter contains non-continuous bins.

Parameters:
class vivarium.engine.framework.lookup.interpolation.Order0Interp(data, continuous_parameters, value_columns, extrapolate, validate)[source]

A callable that returns the result of order 0 interpolation over input data.

Parameters:

  • data (pd.DataFrame)

  • continuous_parameters (Sequence[str])

  • value_columns (list[str])

  • extrapolate (bool)

  • validate (bool)

data: DataFrame

The data from which to build the interpolation.

value_columns: list[str]

Columns to be interpolated.

extrapolate: bool

Whether to extrapolate beyond the edges of the supplied bins.

parameter_bins: dict[tuple[str, str, str], dict[str, Any]]

Per-continuous-parameter bin metadata. Keys are (name, name_start, name_end) tuples; values are {"bins": <ordered left edges>, "max": <max right edge>}.