Nests

Objects for the defintion of nests

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:

choice_set (list[int]) –
tuple_of_nests (tuple[Any, ...]) –

__init__(choice_set, tuple_of_nests)[source]

Ctor

Parameters:

choice_set (list[int]) – the list of all alternatives in the choice set. We use a list instread of a set because thre order matters.
tuple_of_nests (tuple[Any, ...]) – the list of nests

check_names()[source]: Checks that all the nests have a name

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 is 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:

choice_set (list[int]) –
tuple_of_nests (tuple[OneNestForCrossNestedLogit, ...]) –

__init__(choice_set, tuple_of_nests)[source]

Ctor

Parameters:

choice_set (list[int]) – the list of all alternatives in the choice set
tuple_of_nests (tuple[OneNestForCrossNestedLogit, ...]) – the list of nests

all_alphas_fixed()[source]

Check if all the alphas are fixed

Return type:: bool

check_validity()[source]

Verifies if the cross-nested logit specifciation is valid

Return type:: tuple[bool, str]
Returns:: a boolean with the result of the check, and a message if check fails.

correlation(parameters={}, 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]) – values of the parameters.
alternatives_names (Optional[dict[int, str]]) – names of the alternative, for

Return type:

DataFrame

better reporting. If not provided, the number are used.

Return type:

DataFrame

Returns:

correlation matrix

Parameters:

parameters (dict[str, float]) –
alternatives_names (dict[int, str] | None) –

covariance(i, j, parameters={})[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]) – 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 alpha values, 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 alpha values
Raise:: BiogemeError is one alpha is a non numeric expression

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

Bases: Nests

This class handles nests for the nested logit model

Parameters:

choice_set (list[int]) –
tuple_of_nests (tuple[OneNestForNestedLogit, ...] | tuple[tuple[Expression, list[int]], ...]) –

__init__(choice_set, tuple_of_nests)[source]

Ctor

Parameters:

choice_set (list[int]) – the list of all alternatives in the choice set
tuple_of_nests (Union[tuple[OneNestForNestedLogit, ...], tuple[tuple[Expression, list[int]], ...]]) –
the list of nests. The old syntax can still be used: A tuple containing as many items as nests. Each item is also a tuple containing two items:
- an object of type biogeme.expressions.expr.Expression representing the nest parameter,
- a list containing the list of identifiers of the alternatives belonging to the nest.
Example:
```
nesta = MUA ,[1, 2, 3]
nestb = MUB ,[4, 5, 6]
nests = nesta, nestb
```
alone – the list of alternatives alone in one nest. If None, any alternative not present in a nest is supposed to be alone

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={}, 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]) – values of the parameters.
alternatives_names (Optional[dict[int, str]]) – 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) –
dict_of_alpha (dict[int, Expression]) –
name (str | None) –

__eq__(other): Return self==value.

__init__(nest_param, dict_of_alpha, name=None)

Parameters:

nest_param (Expression | float) –
dict_of_alpha (dict[int, Expression]) –
name (str | None) –

Return type:

None

dict_of_alpha: dict[int, Expression]

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, dict[int, Expression]]) –

is_alpha_fixed()[source]

Check if the alpha parameters have a numeric value.

Return type:: bool

name: Optional[str] = None

nest_param: Union[Expression, float]

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) –
list_of_alternatives (list[int]) –
name (str | None) –

__eq__(other): Return self==value.

__init__(nest_param, list_of_alternatives, name=None)

Parameters:

nest_param (Expression | float) –
list_of_alternatives (list[int]) –
name (str | None) –

Return type:

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, 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: Optional[str] = None

nest_param: Union[Expression, float]

biogeme.nests.get_alpha_expressions(the_dict)[source]

If the dictionary contains float, they are transformed into a numerical expression.

Return type:: dict[int, Expression]
Parameters:: the_dict (dict[int, Expression | float]) –

biogeme.nests.get_alpha_values(the_dict, parameters=None)[source]

If the dictionary contains float, they are transformed into a numerical expression.

Parameters:

the_dict (dict[int, Union[Expression, float]]) – dict of alphas.
parameters (Optional[dict[str, float]]) – value of the parameters.

Return type:

dict[int, float]