biogeme.nests module

Implements objects in charge of the management of nests for the nested and the cross-nested logit model.

author:

Michel Bierlaire

date:

Thu Oct 5 14:45:58 2023

class biogeme.nests.Nests(choice_set, tuple_of_nests)[source]

Bases: object

Generic interface for the nests.

Parameters:
check_names()[source]

Checks that all the nests have a name

Return type:

bool

check_union()[source]

Check if the union of the nests is the choice set

Return type:

tuple[bool, str]

Returns:

a boolean with the result of the check, as a message if check fails.

class biogeme.nests.NestsForCrossNestedLogit(choice_set, tuple_of_nests)[source]

Bases: Nests

This class handles nests for the cross-nested logit model

Parameters:
all_alphas_fixed()[source]

Check if all the alphas are fixed

Return type:

bool

check_validity()[source]

Verifies if the cross-nested logit specification is valid

Return type:

tuple[bool, str]

Returns:

a boolean with the result of the check, and a message if check fails.

correlation(parameters=None, alternatives_names=None)[source]
Calculate the correlation matrix of the error terms of all

alternatives of cross-nested logit model.

Parameters:

  • parameters (dict[str, float] | None) – values of the parameters.

  • alternatives_names (dict[int, str] | None) – names of the alternative, for better reporting. If not provided, the number are used.

Return type:

DataFrame

Returns:

correlation matrix

covariance(i, j, parameters=None)[source]

Calculate the covariance between the error terms of two alternatives of a cross-nested logit model. It is assumed that the homogeneity parameter mu of the model has been normalized to one.

Parameters:

  • parameters (dict[str, float] | None) – values of the parameters.

  • i (int) – first alternative

  • j (int) – second alternative

Return type:

float

Returns:

value of the correlation

Raises:

BiogemeError – if the requested number is non-positive or a float

get_alpha_dict(alternative_id)[source]

Generates a dict mapping each nest with the alpha parameter, for a given alternative

Parameters:

alternative_id (int) – identifier of the alternative

Return type:

dict[str, Expression]

Returns:

a dict mapping the name of a nest and the alpha expression

get_alpha_values(alternative_id)[source]

Generates a dict mapping each nest with the value of the alpha parameters, for a given alternative

Parameters:

alternative_id (int) – identifier of the alternative

Return type:

dict[str, float]

Returns:

a dict mapping the name of a nest and the value of the alpha expression

class biogeme.nests.NestsForNestedLogit(choice_set, tuple_of_nests)[source]

Bases: Nests

This class handles nests for the nested logit model

Parameters:
check_intersection()[source]

Check if the intersection of nests is empty

Return type:

tuple[bool, str]

Returns:

a boolean with the result of the check, and a message if check fails.

check_partition()[source]

Check if the nests correspond to a partition

Return type:

tuple[bool, str]

Returns:

a boolean with the result of the check, and a message if check fails.

correlation(parameters=None, alternatives_names=None, mu=1.0)[source]
Calculate the correlation matrix of the error terms of all

alternatives of a nested logit model.

Parameters:

  • parameters (dict[str, float] | None) – values of the parameters.

  • alternatives_names (dict[int, str] | None) – dictionary associating a name with each alternative.

  • mu (float) – value of the scale parameter mu.

Return type:

DataFrame

Returns:

correlation matrix

class biogeme.nests.OneNestForCrossNestedLogit(nest_param, dict_of_alpha, name=None)[source]

Bases: object

Tuple capturing the information for one nest of the cross-nested logit

Parameters:

  • nest_param (Expression | float | int | bool)

  • dict_of_alpha (dict[int, Expression | float | int | bool])

  • name (str | None)

all_alpha_fixed()[source]

Check if the alpha parameters have a numeric value.

Return type:

bool

dict_of_alpha: dict[int, Expression | float | int | bool]
classmethod from_tuple(the_tuple)[source]

Ctor to initialize the nest using the old syntax of Biogeme with a tuple

Return type:

OneNestForCrossNestedLogit

Parameters:

the_tuple (tuple[Expression | float | int | bool, dict[int, Expression]])

name: str | None = None
nest_param: Expression | float | int | bool
class biogeme.nests.OneNestForNestedLogit(nest_param, list_of_alternatives, name=None)[source]

Bases: object

Class capturing the information for one nest of the nested logit model

Parameters:

  • nest_param (Expression | float | int | bool)

  • list_of_alternatives (list[int])

  • name (str | None)

classmethod from_tuple(the_tuple)[source]

Ctor to initialize the nest using the old syntax of Biogeme with a tuple

Return type:

OneNestForNestedLogit

Parameters:

the_tuple (tuple[Expression | float | int | bool, list[int]])

intersection(other_nest)[source]

Returns the intersection of two nests. Designed to verify the validity of the specification

Return type:

set[int]

Parameters:

other_nest (OneNestForNestedLogit)

list_of_alternatives: list[int]
name: str | None = None
nest_param: Expression | float | int | bool
biogeme.nests.get_nest(a_nest)[source]

Convert a nest definition to an OneNestForNestedLogot, if needed.

Parameters:

a_nest (OneNestForNestedLogit | tuple[Expression | float | int | bool, list[int]])