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, ...]) –
- 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 settuple_of_nests (
tuple
[OneNestForCrossNestedLogit
,...
]) – the list of nests
- 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 alternativej (
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 settuple_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:
- Parameters:
the_tuple (tuple[Expression | float, dict[int, Expression]]) –
-
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:
- 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
]