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)

Bases: object

Generic interface for the nests.

Parameters:

• choice_set (list[int])

• tuple_of_nests (tuple[OneNestForNestedLogit | OneNestForCrossNestedLogit, ...])

check_names()

Checks that all the nests have a name

Return type:

bool

check_union()

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)

Bases: Nests

This class handles nests for the cross-nested logit model

Parameters:

• choice_set (list[int])

• tuple_of_nests (tuple[OneNestForCrossNestedLogit, ...] | OldNestsForCrossNestedLogit)

all_alphas_fixed()

Check if all the alphas are fixed

Return type:

bool

check_validity()

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)

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)

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)

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)

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)

Bases: Nests

This class handles nests for the nested logit model

Parameters:

• choice_set (list[int])

• tuple_of_nests (tuple[OneNestForNestedLogit, ...] | OldNestsForNestedLogit)

check_intersection()

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

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)

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)

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

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)

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)

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)

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)

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)

Convert a nest definition to an OneNestForNestedLogot, if needed.

Parameters:

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