biogeme.model_elements.database_adapter module

Database adapters (strategy objects) for ModelElements.

This module provides a small adapter interface that encapsulates the preparation and exposure of the working database used to evaluate model expressions, together with a factory for the corresponding ExpressionRegistry.

Two concrete adapters are provided:

• RegularAdapter – uses the database as-is (no transformation).

• FlatPanelAdapter – flattens a panel database and updates expressions with the maximum number of observations per individual.

These adapters allow the ModelElements container to remain generic and free of conditional logic about database variants.

Michel Bierlaire Tue Nov 11 2025, 17:40:56

class biogeme.model_elements.database_adapter.FlatPanelAdapter(database)

Bases: object

Adapter that flattens a panel database for expression evaluation.

This adapter converts an input panel database into a flat database using PanelDatabase. It also updates each expression with the maximum number of observations per individual.

Note:

• After prepare(), :pyattr:`database` points to the flat database.

• sample_size is the number of rows in the flat database. number_of_observations is the number of rows in the original database.

Parameters:

database (Database | None)

build_registry(expressions)

Build an ExpressionRegistry bound to the flat database.

Parameters:

expressions (dict[str, Expression]) – Mapping of expression names to expressions.

Returns:

Registry bound to :pyattr:`database`.

Return type:

ExpressionRegistry

property database: Database

Working database, i.e., the flattened database.

Returns:

The flat database created in prepare().

Return type:

Database

Raises:

BiogemeError – If prepare() has not been called yet.

property number_of_observations: int

Number of observations in the original (panel) database.

Returns:

Number of observations.

Return type:

int

prepare(expressions)

Flatten the panel database and update expressions.

Parameters:

expressions (dict[str, Expression]) – Mapping of expression names to expressions. Each expression is informed of the maximum number of observations per individual via set_maximum_number_of_observations_per_individual.

Return type:

None

property sample_size: int

Number of rows in the working (flat) database.

Returns:

Number of rows.

Return type:

int

class biogeme.model_elements.database_adapter.ModelElementsAdapter(*args, **kwargs)

Bases: Protocol

Strategy interface for providing a working database and registry.

Any implementation must be able to prepare its internal state given the model expressions, expose the database on which expressions will be evaluated, and build an ExpressionRegistry bound to that database.

Methods

prepare(expressions)

Perform any one-time preparation needed before evaluation (e.g., flatten a panel DB, set expression metadata).

database

The Database against which expressions are to be evaluated.

build_registry(expressions)

Construct an ExpressionRegistry connected to the working database.

sample_size

Number of data rows in the working database.

number_of_observations

Number of original observations in the source database (this may differ from sample_size for flattened panel data).

param expressions:

Mapping of expression names to Expression instances. Implementations may use this to attach metadata.

build_registry(expressions)

Return type:

ExpressionRegistry

Parameters:

expressions (dict[str, Expression])

property database: Database

property number_of_observations: int

prepare(expressions)

Return type:

None

Parameters:

expressions (dict[str, Expression])

property sample_size: int

class biogeme.model_elements.database_adapter.RegularAdapter(database)

Bases: object

Adapter for a regular (non-panel or non-flattened) database.

This adapter is a thin wrapper around a Database instance and performs no transformation.

Note:

• sample_size equals number_of_observations.

• prepare() is a no-op.

Parameters:

database (Database | None)

build_registry(expressions)

Build an ExpressionRegistry bound to the working database.

Parameters:

expressions (dict[str, Expression]) – Mapping of expression names to expressions.

Returns:

Registry bound to :pyattr:`database`.

Return type:

ExpressionRegistry

property database: Database

Working database (the input database).

property number_of_observations: int

Number of observations in the source database.

prepare(expressions)

No-op preparation for regular databases.

Parameters:

expressions (dict[str, Expression]) – Mapping of expression names to expressions (unused).

Return type:

None

property sample_size: int

Number of rows in the working database.