Interpolation

Provides interpolation algorithms across tabular data for vivarium simulations.

class vivarium.engine.framework.lookup.interpolation.ContinuousParameter(name, start_column, end_column, left_edges, max_right)[source]

A continuous (binned) lookup parameter.

Parameters:
name: str

Base name, e.g. "age"; the interpolant column.

start_column: str

Left-edge column name; a merge key.

end_column: str

Right-edge column name.

left_edges: ndarray[Any, dtype[Any]]

Ascending unique left bin edges, shared across categorical groups.

max_right: Any

Maximum right bin edge (the exclusive upper bound of the last bin).

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 vivarium.engine.types.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.

For order 0 (currently the only supported order) a call resolves each interpolant to the bin its continuous parameters fall in and returns that bin’s values. This requires that the key columns uniquely identify a data row and that the bin edges are identical across every categorical group; both are validated on construction when validate is set. With validate=False violations surface as a KeyError or pandas.errors.MergeError on call.

Parameters:

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

  • value_columns (pd.Index[Any])

  • order (int)

  • extrapolate (bool)

  • validate (bool)

property continuous_parameters: list[str]

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

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__().

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__().

categorical_parameters: list[str]

Lookup attributes used to select between value rows.

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.

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

Validate that the source data satisfies the lookup contract.

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 provides complete, contiguous bins for each continuous parameter.

For each parameter, require that every combination of parameter bins is present, that each left edge pairs with exactly one right edge, and that the bins tile a continuous range: each bin’s exclusive right edge equals the next bin’s inclusive left edge.

Return type:

None

Raises:

  • ValueError – If bins are duplicated or overlap, or if a combination of continuous parameters is missing.

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

Parameters: