models/MNL.py

---

MNL(ds, variables, utility, av=None, **kwargs)

Bases: BaseModel

Defines a Multinomial Logit model

Parameters:

Name	Type	Description	Default
ds	Data	the database object	required
variables	dict	dictionary containing Param objects or a dictionary of python variables	required
utility	Union[list[TensorVariable], TensorVariable]	the vector of utility functions	required
av	List[TensorVariable]	list of availability conditions. If None, all availability is set to 1	None
**kwargs	dict	Optional keyword arguments for modifying the model configuration settings. See configuration in the user guide for details on possible options	{}

Attributes:

Name	Type	Description
x	List[TensorVariable]	symbolic variable objects for independent variables
y	TensorVariable	symbolic variable object for the choice variable
xy	List[TensorVariable]	concatenated list of x and y
betas	List[Beta]	model beta variables
cost	TensorVariable	symbolic cost tensor variable function
p_y_given_x	TensorVariable	probability tensor variable function
ll	TensorVariable	loglikelihood tensor variable function
pred	TensorVariable	prediction tensor variable function

n_betas property

Return the number of estimated betas in the Multinomial Logit model.

Returns:

Name	Type	Description
int		The number of estimated betas.

n_params property

Returns the number of parameters in the Multinomial Logit model.

Returns:

Name	Type	Description
int		The number of parameters in the Multinomial Logit model.

build_cost_fn()

Constructs Aesara functions for calculating the cost and prediction errors of the Multinomial Logit model.

Inputs: - None

Outputs: - None

Example Usage:

# Create an instance of the MNL class
model = MNL(ds, variables, utility, av=None)

# Call the build_cost_fn method
model.build_cost_fn()

build_cost_updates_fn(updates)

Build or rebuild the cost function with updates to the model.

This method creates a class function MNL.cost_updates_fn(*inputs, output, lr) that takes a list of input variable arrays, an output array, and a learning rate as arguments.

Parameters:

Name	Type	Description	Default
updates	List[Tuple[TensorSharedVariable, TensorVariable]]	A list of tuples containing the target shared variable and the new value of the variable.	required

build_gh_fn()

Constructs Aesara functions for computing the Hessian matrix and the gradient vector.

Returns:

Name	Type	Description
hessian_fn	Aesara function	A function that computes the Hessian matrix.
gradient_vector_fn	Aesara function	A function that computes the gradient vector.

Note

The hessians and gradient vector are evaluation at the maximum log likelihood estimates instead of the negative loglikelihood, therefore the cost is multiplied by negative one.

elasticities(ds, wrt_choice)

Calculate the disaggregated point/cross elasticities of the choice variable y with respect to the independent variables x in a Multinomial Logit model.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the training data.	required
wrt_choice	int	Alternative to evaluate the variables on.	required

Returns:

Name	Type	Description
dict		Disaggregated point elasticities of the independent variables x.

Example

To calculate the elasticity of the choosing alternative 1 w.r.t. (represented by wrt_choice) w.r.t. to variable x.

disag_elas = self.elasticities(ds, wrt_choice=1)

output:

{
    'variable_1': array([...]),
    'variable_2': array([...]),
    ...
}

The return values in the dictionary are the disaggregated elasticities. To calculate the aggregated elasticities, use np.mean().

Note

This function returns the elasticities for all variables. To obtain the point or cross elasticities, simply select the appropriate dictionary key from the output (wrt_choice w.r.t. x).

get_betas()

Returns the values of the betas in the model as a dictionary.

Returns:

Name	Type	Description
dict		A dictionary containing the beta values, where the keys represent the beta names and the values represent their corresponding values.

predict(ds)

Predicts the output of the most likely alternative given the validation dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	A pycmtensor dataset object containing the validation data.	required

Returns:

Type	Description
	numpy.ndarray: The predicted choices or the vector of probabilities.

Example

# Create an instance of the MNL class
model = MNL(ds, variables, utility, av=None)

# Predict the choices using the predict method
predictions = self.predict(ds)
print(predictions)

output:

{'pred_choice': array([...])}

# Predict the probabilities using the predict method
prob = self.predict(ds)
print(prob)

output:

{   0: array([...]),
    1: array([...]),
    ...
}

The expected output for predictions is a dictionary with the key 'pred_choice' and an array of predicted choices as the value. The expected output for probabilities is a dictionary with the keys representing the alternative indices and the values being arrays of probabilities.

reset_values()

Resets the values of all parameters by calling the reset_values method of the parent class.

This method resets the values of all parameters to their initial values.

Example Usage:

# Create an instance of the MNL class
model = MNL(ds, variables, utility, av=None)

# Call the reset_values method to reset the parameter values
model.reset_values()

Inputs: - None

Flow: 1. The reset_values method is called. 2. The method calls the reset_values method of the parent class BaseModel to reset the values of all parameters.

Outputs: - None