biogeme.latent_variables.ordered_mimic module

High-level wrapper for hybrid choice models (latent variables + Likert measurement).

This module provides OrderedMimic, a convenience wrapper to assemble a hybrid choice model consisting of:

  • one or more latent variables (structural equations + normalization + indicator sets),

  • a set of Likert indicators (measurement intercepts, measurement scales, loadings),

  • a set of Likert types (categories and ordered thresholds).

It then builds the joint ordered-probit measurement likelihood using the JAX-compatible builders in measurement_equations.

Defaults depend on the estimation mode:

  • Maximum likelihood (EstimationMode.MAXIMUM_LIKELIHOOD): uses draw_type='NORMAL_MLHS_ANTI' and a log-sigma parameterization for positive scale parameters.

  • Bayesian (EstimationMode.BAYESIAN): uses draw_type='Normal' and a strictly positive sigma parameterization enforced through bounds.

Users can override these defaults by providing draw_type and/or sigma_factory at construction time, and can override draw_type again when calling OrderedMimic.measurement_equations() or OrderedMimic.log_measurement_equations().

Michel Bierlaire Sun Dec 14 2025

class biogeme.latent_variables.ordered_mimic.EstimationMode(*values)[source]

Bases: str, Enum

Estimation mode controlling default draw types and positivity constraints.

BAYESIAN = 'bayesian'
MAXIMUM_LIKELIHOOD = 'maximum_likelihood'
class biogeme.latent_variables.ordered_mimic.OrderedMimic(estimation_mode, likert_indicators, likert_types, draw_type=None, sigma_factory=None)[source]

Bases: object

High-level wrapper for hybrid choice models with ordered-probit measurement.

The class registers Likert indicators and Likert types, injects default factories when missing, and allows registering latent variables. It then builds the joint ordered-probit measurement likelihood (or its log) for all registered indicators.

Defaults depend on estimation_mode:

  • Maximum likelihood: draw_type='NORMAL_MLHS_ANTI' and a log-sigma parameterization for scale parameters.

  • Bayesian: draw_type='Normal' and a strictly positive sigma parameterization (positivity enforced via bounds).

Parameters:

  • estimation_mode (EstimationMode) – Estimation mode controlling defaults (maximum likelihood vs Bayesian).

  • likert_indicators (list[LikertIndicator]) – List of Likert indicator specifications used by the measurement model.

  • likert_types (list[LikertType]) – List of Likert type specifications defining categories and thresholds.

  • draw_type (str | None) – Draw type used by latent-variable error terms. If None, a default is selected based on estimation_mode.

  • sigma_factory (SigmaFactory | None) – Factory used to generate strictly positive scale parameters. If None, a default is selected based on estimation_mode.

add_latent_variable(lv)[source]

Register a latent variable.

The latent variable must be constructed outside of this class. This method injects model defaults for draw_type_jax and sigma_factory when they are not already set.

Parameters:

lv (LatentVariable) – A fully specified LatentVariable instance.

Return type:

LatentVariable

Returns:

The registered LatentVariable (same object).

Raises:

  • ValueError – If the model sigma_factory is undefined.

  • ValueError – If a latent variable with the same name is already registered.

draw_type: str | None = None
estimation_mode: EstimationMode
get_latent_variable(name)[source]

Return a registered latent variable by name.

Parameters:

name (str) – Latent variable name.

Return type:

LatentVariable

Returns:

The corresponding LatentVariable.

Raises:

KeyError – If the latent variable is not registered.

get_likert_indicator(name)[source]

Return a registered Likert indicator by name.

Parameters:

name (str) – Indicator name.

Return type:

LikertIndicator

Returns:

The corresponding LikertIndicator.

Raises:

KeyError – If the indicator is not registered.

get_likert_type(name)[source]

Return a registered Likert type by name.

Parameters:

name (str) – Type label.

Return type:

LikertType

Returns:

The corresponding LikertType.

Raises:

KeyError – If the type is not registered.

property latent_variables: list[LatentVariable]

Return the registered latent variables.

likert_indicators: list[LikertIndicator]
likert_types: list[LikertType]
log_measurement_equations(*, draw_type=None)[source]

Build the joint ordered-probit measurement log-likelihood (sum of logs).

This returns a single Biogeme expression corresponding to the sum of log ordered-probit likelihood terms for all registered indicators.

If the model is configured for a non-Bayesian estimation mode, a warning is emitted because the log-likelihood is typically used for Bayesian estimation.

Parameters:

draw_type (str | None) – If provided, overrides the instance draw type.

Return type:

Expression

Returns:

A Biogeme expression for the log measurement likelihood.

Raises:

  • ValueError – If no latent variables have been registered.

  • ValueError – If no Likert indicators have been registered.

measurement_equations(*, draw_type=None)[source]

Build the joint ordered-probit measurement likelihood (product form).

This returns a single Biogeme expression corresponding to the product of ordered-probit likelihood terms for all registered indicators.

If the model is configured for a non-maximum-likelihood estimation mode, a warning is emitted because the likelihood (product) is typically used for maximum-likelihood estimation.

Parameters:

draw_type (str | None) – If provided, overrides the instance draw type.

Return type:

Expression

Returns:

A Biogeme expression for the measurement likelihood.

Raises:

  • ValueError – If no latent variables have been registered.

  • ValueError – If no Likert indicators have been registered.

sigma_factory: SigmaFactory | None = None