biogeme.models.ordered module

Implements various models.

author:

Michel Bierlaire

date:

Fri Mar 29 17:13:14 2019

biogeme.models.ordered.build_ordered_thresholds(list_of_discrete_values, first_threshold_parameter)

Constructs the ordered list of thresholds for the ordered model.

Given a list of discrete values, constructs the list of thresholds [tau_1_2, tau_2_3, …, tau_{J-1_J}] such that tau_1_2 = first_tau, and tau_{j_j+1} = tau_{j-1_j} + diff_j for each intermediate j, where diff_j is a Beta parameter.

Parameters:

• list_of_discrete_values (list[int]) – list of discrete values (must be at least length 2)

• first_threshold_parameter (Beta) – Beta parameter for the first threshold

Return type:

list[Expression]

Returns:

list of Expression thresholds (length len(list_of_discrete_values) - 1)

biogeme.models.ordered.ordered_likelihood(continuous_value, scale_parameter, list_of_discrete_values, reference_threshold_parameter, cdf)

Ordered model that maps a continuous quantity with a list of discrete intervals (often logit or probit).

This function builds the ordered thresholds and computes the category probabilities.

Parameters:

• continuous_value (Expression) – continuous value to mapping

• scale_parameter (Expression) – scale parameter of the continuous value

• list_of_discrete_values (list[int]) – list of discrete values

• reference_threshold_parameter (Beta) – parameter for the first threshold (Beta)

• cdf (Callable[[Expression], Expression]) – function calculating the CDF of the random variable

Return type:

dict[int, Expression]

Returns:

dict mapping discrete values to probabilities

biogeme.models.ordered.ordered_likelihood_from_thresholds(continuous_value, scale_parameter, list_of_discrete_values, threshold_parameters, cdf)

Computes category probabilities for the ordered model, given thresholds.

Parameters:

• continuous_value (Expression) – continuous value to map

• scale_parameter (Expression) – scale parameter of the continuous value

• list_of_discrete_values (list[int]) – list of discrete values (length J)

• threshold_parameters (list[Expression]) – list of threshold Expressions (length J-1)

• cdf (Callable[[Expression], Expression]) – CDF function

Return type:

dict[int, Expression]

Returns:

dict mapping discrete values to probabilities

biogeme.models.ordered.ordered_logit(continuous_value, scale_parameter, list_of_discrete_values, reference_threshold_parameter)

Ordered logit model that maps a continuous quantity with a list of discrete intervals.

This function builds the ordered thresholds and computes the category probabilities using the logistic CDF.

Return type:

dict[int, Expression]

Parameters:

• continuous_value (Expression)

• scale_parameter (Expression | float)

• list_of_discrete_values (list[int])

• reference_threshold_parameter (Beta)

biogeme.models.ordered.ordered_logit_from_thresholds(continuous_value, scale_parameter, list_of_discrete_values, threshold_parameters)

Ordered logit with explicit thresholds.

Computes category probabilities given a list of thresholds. The number of thresholds must be one less than the number of categories.

Parameters:

• continuous_value (Expression) – continuous value to map.

• scale_parameter (Expression) – scale parameter of the continuous value

• list_of_discrete_values (list[int]) – ordered list of discrete categories (length ≥ 2).

• threshold_parameters (list[Expression]) – list of threshold expressions (length = len(list_of_discrete_values) - 1).

Return type:

dict[int, Expression]

Returns:

dict mapping each category to its probability.

Raises:

BiogemeError – if lengths are incompatible.

biogeme.models.ordered.ordered_probit(continuous_value, scale_parameter, list_of_discrete_values, reference_threshold_parameter)

Ordered probit model that maps a continuous quantity with a list of discrete intervals.

This function builds the ordered thresholds and computes the category probabilities using the normal CDF.

Return type:

dict[int, Expression]

Parameters:

• continuous_value (Expression)

• scale_parameter (Expression | float)

• list_of_discrete_values (list[int])

• reference_threshold_parameter (Beta)

biogeme.models.ordered.ordered_probit_from_thresholds(continuous_value, scale_parameter, list_of_discrete_values, threshold_parameters)

Ordered probit with explicit thresholds.

Computes category probabilities given a list of thresholds. The number of thresholds must be one less than the number of categories.

Parameters:

• continuous_value (Expression) – continuous value to map.

• scale_parameter (Expression) – scale parameter of the continuous value

• list_of_discrete_values (list[int]) – ordered list of discrete categories (length ≥ 2).

• threshold_parameters (list[Expression]) – list of threshold expressions (length = len(list_of_discrete_values) - 1).

Return type:

dict[int, Expression]

Returns:

dict mapping each category to its probability.

Raises:

BiogemeError – if lengths are incompatible.