Biogeme: Python Library  2.5
Functions
Specific choice models

Functions

def cnl.cnl_avail (V, availability, nests, choice)
 Implements the cross-nested logit model as a MEV model. More...
 
def cnl.logcnl_avail (V, availability, nests, choice)
 Implements the log of the cross-nested logit model as a MEV model. More...
 
def cnl.cnlmu (V, availability, nests, choice, bmu)
 Implements the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved. More...
 
def cnl.logcnlmu (V, availability, nests, choice, bmu)
 Implements the log of the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved. More...
 
def logit.logit_av_scale (V, availability, choice, group, scale)
 Compute the logit choice probability with utilities scaled according to the group. More...
 
def logit.logit (V, choice)
 Compute the logit choice probability, where all alternatives are available. More...
 
def logit.logit_scale (V, choice, group, scale)
 Compute the logit choice probability with utilities scaled according to the group. More...
 
def mev.mev (V, Gi, av, choice)
 Choice probability for a MEV model. More...
 
def mev.logmev (V, Gi, av, choice)
 Log of the choice probability for a MEV model. More...
 
def mev.mev_selectionBias (V, Gi, av, correction, choice)
 Choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008). More...
 
def mev.logmev_selectionBias (V, Gi, av, correction, choice)
 Log of choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008). More...
 
def nested.getMevForNested (V, availability, nests)
 Implements the MEV generating function for the nested logit model. More...
 
def nested.nested (V, availability, nests, choice)
 Implements the nested logit model as a MEV model. More...
 
def nested.lognested (V, availability, nests, choice)
 Implements the log of a nested logit model as a MEV model. More...
 
def nested.nestedMevMu (V, availability, nests, choice, mu)
 Implements the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes. More...
 
def nested.lognestedMevMu (V, availability, nests, choice, mu)
 Implements the log of the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes. More...
 

Detailed Description

Function Documentation

def cnl.cnl_avail (   V,
  availability,
  nests,
  choice 
)

Implements the cross-nested logit model as a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. Example with two nests and 6 alternatives:
    1 alphaA = {1: alpha1a,
    2  2: alpha2a,
    3  3: alpha3a,
    4  4: alpha4a,
    5  5: alpha5a,
    6  6: alpha6a}
    7 alphaB = {1: alpha1b,
    8  2: alpha2b,
    9  3: alpha3b,
    10  4: alpha4b,
    11  5: alpha5b,
    12  6: alpha6b}
    13 nesta = MUA , alphaA
    14 nestb = MUB , alphaB
    15 nests = nesta, nestb
Returns
Choice probability for the cross-nested logit model.

Definition at line 47 of file cnl.py.

def cnl.cnlmu (   V,
  availability,
  nests,
  choice,
  bmu 
)

Implements the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. Example with two nests and 6 alternatives:
    1 alphaA = {1: alpha1a,
    2  2: alpha2a,
    3  3: alpha3a,
    4  4: alpha4a,
    5  5: alpha5a,
    6  6: alpha6a}
    7 alphaB = {1: alpha1b,
    8  2: alpha2b,
    9  3: alpha3b,
    10  4: alpha4b,
    11  5: alpha5b,
    12  6: alpha6b}
    13 nesta = MUA , alphaA
    14 nestb = MUB , alphaB
    15 nests = nesta, nestb
bmuHomogeneity parameter $\mu$.
Returns
Choice probability for the cross-nested logit model.

Definition at line 163 of file cnl.py.

def nested.getMevForNested (   V,
  availability,
  nests 
)

Implements the MEV generating function for the nested logit model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A list containing the list of identifiers of the alternatives belonging to the nest. Example:
    1 nesta = MUA , [1,2,3]
    2 nestb = MUB , [4,5,6]
    3 nests = nesta, nestb
Returns
A dictionary mapping each alternative id with the function

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{1}{\mu_m}-1} \]

where $m$ is the (only) nest containing alternative $i$, and $G$ is the MEV generating function.

Definition at line 42 of file nested.py.

def cnl.logcnl_avail (   V,
  availability,
  nests,
  choice 
)

Implements the log of the cross-nested logit model as a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. Example with two nests and 6 alternatives:
    1 alphaA = {1: alpha1a,
    2  2: alpha2a,
    3  3: alpha3a,
    4  4: alpha4a,
    5  5: alpha5a,
    6  6: alpha6a}
    7 alphaB = {1: alpha1b,
    8  2: alpha2b,
    9  3: alpha3b,
    10  4: alpha4b,
    11  5: alpha5b,
    12  6: alpha6b}
    13 nesta = MUA , alphaA
    14 nestb = MUB , alphaB
    15 nests = nesta, nestb
Returns
Choice probability for the cross-nested logit model.

Definition at line 105 of file cnl.py.

def cnl.logcnlmu (   V,
  availability,
  nests,
  choice,
  bmu 
)

Implements the log of the cross-nested logit model as a MEV model with the homogeneity parameters is explicitly involved.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A dictionary mapping the alternative ids with the cross-nested parameters for the corresponding nest. Example with two nests and 6 alternatives:
    1 alphaA = {1: alpha1a,
    2  2: alpha2a,
    3  3: alpha3a,
    4  4: alpha4a,
    5  5: alpha5a,
    6  6: alpha6a}
    7 alphaB = {1: alpha1b,
    8  2: alpha2b,
    9  3: alpha3b,
    10  4: alpha4b,
    11  5: alpha5b,
    12  6: alpha6b}
    13 nesta = MUA , alphaA
    14 nestb = MUB , alphaB
    15 nests = nesta, nestb
bmuHomogeneity parameter $\mu$.
Returns
Log of choice probability for the cross-nested logit model.

Definition at line 220 of file cnl.py.

def logit.logit (   V,
  choice 
)

Compute the logit choice probability, where all alternatives are available.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
choiceexpression producing the id of the chosen alternative.
Returns
Choice probability for chosen alternative $i$ and individual in group $g$:

\[ \frac{e^{V_i}}{\sum_j e^{V_j}}\]

Definition at line 32 of file logit.py.

def logit.logit_av_scale (   V,
  availability,
  choice,
  group,
  scale 
)

Compute the logit choice probability with utilities scaled according to the group.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
choiceexpression producing the id of the chosen alternative.
groupid of the group, or market segment.
scaleA dictionary mapping each group id with the expression providing the corresponding scale.
Returns
Choice probability for chosen alternative $i$ and individual in group $g$:

\[ \frac{e^{\mu_g V_i}}{\sum_j a_j e^{\mu_g V_j}}\]

where $a_j$ is 1 if alternative $j$ is available, 0 otherwise, and $\mu_g$ is the scale parameter associated with group $g$.

Definition at line 15 of file logit.py.

def logit.logit_scale (   V,
  choice,
  group,
  scale 
)

Compute the logit choice probability with utilities scaled according to the group.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
choiceexpression producing the id of the chosen alternative.
groupid of the group, or market segment.
scaleA dictionary mapping each group id with the expression providing the corresponding scale.
Returns
Choice probability for chosen alternative $i$ and individual in group $g$:

\[ \frac{e^{\mu_g V_i}}{\sum_j e^{\mu_g V_j}}\]

where $\mu_g$ is the scale parameter associated with group $g$.

Definition at line 48 of file logit.py.

def mev.logmev (   V,
  Gi,
  av,
  choice 
)

Log of the choice probability for a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
GiA dictionary mapping each alternative id with the function

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) \]

where $G$ is the MEV generating function. If an alternative $i$ is not available, then $G_i = 0$.
avA dictionary mapping each alternative id with its availability condition.
choiceExpression producing the id of the chosen alternative.
Returns
Log of the choice probability of the MEV model, given by

\[ V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) - \log\left(\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}\right) \]

1 def logmev(V,Gi,av,choice) :
2  H = {}
3  for i,v in V.items() :
4  H[i] = Elem({0:0, 1: v + log(Gi[i])},Gi[i]!=0)
5  P = bioLogLogit(H,av,choice)
6  return P

Definition at line 75 of file mev.py.

def mev.logmev_selectionBias (   V,
  Gi,
  av,
  correction,
  choice 
)

Log of choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008).

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
GiA dictionary mapping each alternative id with the function

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) \]

where $G$ is the MEV generating function.
avA dictionary mapping each alternative id with its availability condition.
correctionA dictionary mapping each alternative id with the expression of the correction. Typically, it is a value, or a parameter to be estimated.
choiceExpression producing the id of the chosen alternative.
Returns
Log of choice probability of the MEV model, given by

\[ V_i + \ln G_i(e^{V_1},\ldots,e^{V_J}) - \log\left(\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}\right) \]

1 def logmev_selectionBias(V,Gi,av,correction,choice) :
2  H = {}
3  for i,v in V.items() :
4  H[i] = v + log(Gi[i]) + correction[i]
5  P = bioLogLogit(H,av,choice)
6  return P

Definition at line 169 of file mev.py.

def nested.lognested (   V,
  availability,
  nests,
  choice 
)

Implements the log of a nested logit model as a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A list containing the list of identifiers of the alternatives belonging to the nest. Example:
    1 nesta = MUA , [1,2,3]
    2 nestb = MUB , [4,5,6]
    3 nests = nesta, nestb
choiceexpression producing the id of the chosen alternative.
Returns
Log of choice probability for the nested logit model, based on the derivatives of the MEV generating function produced by the function nested::getMevForNested

Definition at line 126 of file nested.py.

def nested.lognestedMevMu (   V,
  availability,
  nests,
  choice,
  mu 
)

Implements the log of the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A list containing the list of identifiers of the alternatives belonging to the nest. Example:
    1 nesta = MUA , [1,2,3]
    2 nestb = MUB , [4,5,6]
    3 nests = nesta, nestb
choiceexpression producing the id of the chosen alternative.
muexpression producing the value of the top-level scale parameter.
Returns
The nested logit choice probability based on the following derivatives of the MEV generating function:

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = \mu e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}-1} \]

where $m$ is the (only) nest containing alternative $i$, and $G$ is the MEV generating function.

Definition at line 224 of file nested.py.

def mev.mev (   V,
  Gi,
  av,
  choice 
)

Choice probability for a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
GiA dictionary mapping each alternative id with the function

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) \]

where $G$ is the MEV generating function. If an alternative $i$ is not available, then $G_i = 0$.
avA dictionary mapping each alternative id with its availability condition.
choiceExpression producing the id of the chosen alternative.
Returns
Choice probability of the MEV model, given by

\[ \frac{e^{V_i + \ln G_i(e^{V_1},\ldots,e^{V_J})}}{\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}} \]

1 def mev(V,Gi,av,choice) :
2  H = {}
3  for i,v in V.items() :
4  H[i] = Elem({0:0, 1: v + log(Gi[i])},Gi[i]!=0)
5  P = bioLogit(H,av,choice)
6  return P

Definition at line 37 of file mev.py.

def mev.mev_selectionBias (   V,
  Gi,
  av,
  correction,
  choice 
)

Choice probability for a MEV model, including the correction for endogenous sampling as proposed by Bierlaire, Bolduc and McFadden (2008).

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
GiA dictionary mapping each alternative id with the function

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) \]

where $G$ is the MEV generating function.
avA dictionary mapping each alternative id with its availability condition.
correctionA dictionary mapping each alternative id with the expression of the correction. Typically, it is a value, or a parameter to be estimated.
choiceExpression producing the id of the chosen alternative.
Returns
Choice probability of the MEV model, given by

\[ \frac{e^{V_i + \ln G_i(e^{V_1},\ldots,e^{V_J})}}{\sum_j e^{V_j + \ln G_j(e^{V_1},\ldots,e^{V_J})}} \]

1 def mev_selectionBias(V,Gi,av,correction,choice) :
2  H = {}
3  for i,v in V.items() :
4  H[i] = v + log(Gi[i]) + correction[i]
5  P = bioLogit(H,av,choice)
6  return P

Definition at line 121 of file mev.py.

def nested.nested (   V,
  availability,
  nests,
  choice 
)

Implements the nested logit model as a MEV model.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A list containing the list of identifiers of the alternatives belonging to the nest. Example:
    1 nesta = MUA , [1,2,3]
    2 nestb = MUB , [4,5,6]
    3 nests = nesta, nestb
choiceexpression producing the id of the chosen alternative.
Returns
Choice probability for the nested logit model, based on the derivatives of the MEV generating function produced by the function nested::getMevForNested

Definition at line 90 of file nested.py.

def nested.nestedMevMu (   V,
  availability,
  nests,
  choice,
  mu 
)

Implements the nested logit model as a MEV model, where mu is also a parameter, if the user wants to test different normalization schemes.

Parameters
VA dictionary mapping each alternative id with the expression of the utility function.
availabilityA dictionary mapping each alternative id with its availability condition.
nestsA tuple containing as many items as nests. Each item is also a tuple containing two items:
  • An expression representing the nest parameter.
  • A list containing the list of identifiers of the alternatives belonging to the nest. Example:
    1 nesta = MUA , [1,2,3]
    2 nestb = MUB , [4,5,6]
    3 nests = nesta, nestb
choiceexpression producing the id of the chosen alternative.
muexpression producing the value of the top-level scale parameter.
Returns
The nested logit choice probability based on the following derivatives of the MEV generating function:

\[ \frac{\partial G}{\partial y_i}(e^{V_1},\ldots,e^{V_J}) = \mu e^{(\mu_m-1)V_i} \left(\sum_{i=1}^{J_m} e^{\mu_m V_i}\right)^{\frac{\mu}{\mu_m}-1} \]

where $m$ is the (only) nest containing alternative $i$, and $G$ is the MEV generating function.

Definition at line 170 of file nested.py.

Copyright 2016 Michel Bierlaire