biogeme.results_processing.estimation_results module

Stores and process the estimation results

Michel Bierlaire Mon Sep 30 15:39:24 2024

class biogeme.results_processing.estimation_results.EstimationResults(raw_estimation_results)[source]

Bases: object

Extension of the raw estimation results.

Parameters:

raw_estimation_results (RawEstimationResults)

property akaike_information_criterion: float

Calculates the AIC

Returns:

AIC

property algorithm_has_converged: bool

Reports if the algorithm has indeed converged

Returns:

True if the algorithm has converged.

Return type:

bool

property are_derivatives_available: bool
property bayesian_information_criterion: float

Calculates the BIC

Returns:

BIC

property bhhh_variance_covariance_matrix: ndarray

Calculates the variance-covariance matrix as the (pseudo) inverse of the BHHH matrix. We use the pseudo inverse in case the matrix is singular

property bootstrap_variance_covariance_matrix: ndarray

Calculates the bootstrap variance-covariance matrix

calculate_test(i, j, matrix)[source]

Calculates a t-test comparing two coefficients

Args:

i: index of first coefficient

$beta_i $.

j: index of second coefficient

$beta_i $.

matrix: estimate of the variance-covariance matrix

$m $.

Returns:

t test ..math:

Parameters:

  • i (int)

  • j (int)

  • matrix (ndarray)

Return type:

float

[frac{beta_i-beta_j}

{sqrt{m_{ii}+m_{jj} - 2 m_{ij} }}

] :rtype: float

property condition_number: float

Calculates the condition number of the hessian matrix

dump_yaml_file(filename)[source]

Dump the raw estimation results in a Yaml file

Parameters:

filename (str) – name of the file

Return type:

None

eigen_structure()[source]

Calculate the eigen structure of the hessian matrix

Return type:

tuple[ndarray, ndarray]

property final_loglikelihood: float | None

Final log likelihood after estimation

classmethod from_pickle_file(filename)[source]

Ctor. with data from the file

Return type:

EstimationResults

Parameters:

filename (str)

classmethod from_yaml_file(filename)[source]

Ctor. with data from the file

Return type:

EstimationResults

Parameters:

filename (str)

get_beta_values(my_betas=None)[source]

Retrieve the values of the estimated parameters, by names.

Parameters:

my_betas (list[str] | None) – names of the requested parameters. If None, all available parameters will be reported. Default: None.

Return type:

dict[str, float]

Returns:

dict containing the values, where the keys are the names.

get_betas_for_sensitivity_analysis(my_betas=None, size=100, use_bootstrap=True, variance_covariance_type=EstimateVarianceCovariance.ROBUST)[source]

Generate draws from the distribution of the estimates, for sensitivity analysis.

Parameters:

  • my_betas (list[str] | None) – names of the parameters for which draws are requested.

  • size (int) – number of draws. If use_bootstrap is True, the value is ignored and a warning is issued. Default: 100.

  • use_bootstrap (bool) – if True, the bootstrap estimates are directly used. The advantage is that it does not rely on the assumption that the estimates follow a normal distribution.

  • variance_covariance_type (EstimateVarianceCovariance) – type of variance covariance matrix to use.

Raises:

BiogemeError – if use_bootstrap is True and the bootstrap results are not available

Return type:

list[dict[str, float]]

Returns:

list of dict. Each dict has a many entries as parameters. The list has as many entries as draws.

get_confidence_ellipse(first_parameter, second_parameter, variance_covariance_type=None, confidence_level=0.95)[source]

Provides a Tikz picture of the confidence ellipsis for two parameters :type first_parameter: str :param first_parameter: name of the first parameter :type second_parameter: str :param second_parameter: name of the second parameter :type variance_covariance_type: EstimateVarianceCovariance | None :param variance_covariance_type: type of variance-covariance estimate to be used. :type confidence_level: :param confidence_level: level of confidence for the confidence ellipse :rtype: Ellipse :return: LaTeX code to draw the ellipsis

Parameters:
Return type:

Ellipse

get_default_variance_covariance_matrix()[source]

Selects the default variance covariance matrix

Return type:

EstimateVarianceCovariance

get_estimated_parameters()[source]

For backward compatibility

Return type:

DataFrame

get_general_statistics()[source]

Format the results in a dict

Return type:

dict[str, str]

Returns:

dict with the results. The keys describe each content.

get_parameter_index(parameter_name)[source]

Retrieve the index of a parameter

Parameters:

parameter_name (str) – name of the parameter

Return type:

int

Returns:

index of the parameter

get_parameter_p_value(parameter_name, estimate_var_covar=None, target=0.0)[source]

Calculates the p-value of the parameter estimate

Parameters:

  • parameter_name (str) – name of the parameter

  • estimate_var_covar (EstimateVarianceCovariance | None) – estimator for the variance-covariance matrix

  • target (float) – value for the null hypothesis

Return type:

float

Returns:

p-value

get_parameter_p_value_from_index(parameter_index, estimate_var_covar=None, target=0.0)[source]

Calculates the p-value of the parameter estimate

Parameters:

  • parameter_index (int) – index of the parameter

  • estimate_var_covar (EstimateVarianceCovariance | None) – estimator for the variance-covariance matrix

  • target (float) – value for the null hypothesis

Return type:

float

Returns:

p-value

get_parameter_std_err(parameter_name, estimate_var_covar=None)[source]
Return type:

float

Parameters:
get_parameter_std_err_from_index(parameter_index, estimate_var_covar=None)[source]
Return type:

float

Parameters:
get_parameter_t_test(parameter_name, estimate_var_covar=None, target=0.0)[source]

Calculates the t-test of the parameter estimate

Parameters:

  • parameter_name (str) – name of the parameter

  • estimate_var_covar (EstimateVarianceCovariance | None) – estimator for the variance-covariance matrix

  • target (float) – value for the null hypothesis

Return type:

float

Returns:

value of the t-test

get_parameter_t_test_from_index(parameter_index, estimate_var_covar=None, target=0.0)[source]

Calculates the t-test of the parameter estimate

Parameters:

  • parameter_index (int) – index of the parameter

  • estimate_var_covar (EstimateVarianceCovariance | None) – estimator for the variance-covariance matrix

  • target (float) – value for the null hypothesis

Return type:

float

Returns:

value of the t-test

get_parameter_value(parameter_name)[source]

Retrieve the estimated value of a parameter

Parameters:

parameter_name (str) – name of the parameter

Return type:

float

get_parameter_value_from_index(parameter_index)[source]

Retrieve the estimated value of a parameter

Parameters:

parameter_index (int) – index of the parameter

Return type:

float

get_sub_variance_covariance_matrix(parameters, variance_covariance_type=EstimateVarianceCovariance.ROBUST)[source]

Returns a sub-matrix of the variance-covariance matrix corresponding to a list of parameters

Parameters:

  • parameters (list[str]) – list of parameters to involve in the sub-matrix

  • variance_covariance_type (EstimateVarianceCovariance) – identifies the estimate of the variance-covariance matrix.

Return type:

ndarray

Returns:

a numpy array containing the submatrix.

get_variance_covariance_matrix(variance_covariance_type)[source]

Returns the variance-covariance matrix of a given type

Return type:

ndarray

Parameters:

variance_covariance_type (EstimateVarianceCovariance | None)

property gradient_norm: float

Norm of the final gradient

is_any_bound_active(threshold=1e-06)[source]
Parameters:

threshold (float) – distance below which the bound is considered to be active.

Return type:

bool

Returns:

True is any bound constraint is active

is_bound_active(parameter_name, threshold=1e-06)[source]

Check if one of the two bound is ‘numerically’ active. Being numerically active means that the distance between the value of the parameter and one of its bounds is below the threshold.

Parameters:

  • parameter_name (str) – name of the parameter

  • threshold (float) – distance below which the bound is considered to be active.

Return type:

bool

Returns:

True is one of the two bounds is numerically active.

Raises:

  • BiogemeError – if threshold is negative.

  • BiogemeError – if no result is available

  • ValueError – if the parameter does not exist

property is_hessian_available: bool
property largest_eigenvalue: float

Calculates the largest eigen value of the hessian matrix.

property largest_eigenvector: ndarray

Calculates the eigenvector corresponding to the largest eigen value of the hessian matrix.

property likelihood_ratio_init: float

Likelihood ratio test against the initial model

property likelihood_ratio_null: float

Likelihood ratio test against the null model

likelihood_ratio_test(other_model, significance_level=0.05)[source]

This function performs a likelihood ratio test between a restricted and an unrestricted model. The “self” model can be either the restricted or the unrestricted.

Parameters:

  • other_model (EstimationResults) – other model to perform the test.

  • significance_level (float) – level of significance of the test. Default: 0.05

Return type:

LRTuple

Returns:

a tuple containing:

  • a message with the outcome of the test

  • the statistic, that is minus two times the difference between the loglikelihood of the two models

  • the threshold of the chi square distribution.

property monte_carlo: bool

Verifies if the model involves Monte-Carlo simulation

property number_of_free_parameters: int

This is the number of estimated parameters, minus those that are at their bounds

property number_of_parameters: int

Number of estimated parameters

print_general_statistics()[source]
property rao_cramer_variance_covariance_matrix: ndarray

Calculates the variance-covariance matrix as the (pseudo) inverse of the hessian. We use the pseudo inverse in case the matrix is singular

property rho_bar_square_init: float

Corrected McFadden rho square normalized to the initial model

property rho_bar_square_null: float

Corrected McFadden rho square normalized to the null model

property rho_square_init: float

McFadden rho square normalized to the initial model

property rho_square_null: float

McFadden rho square normalized to the null model

property robust_variance_covariance_matrix: ndarray

Calculates the “sandwich” estimate of the variance-covariance matrix

short_summary()[source]

Provides a short summary of the estimation results

Return type:

str

property smallest_eigenvalue: float

Calculates the smallest eigen value of the hessian matrix.

property smallest_eigenvector: ndarray

Calculates the eigenvector corresponding to the smallest eigen value of the hessian matrix.

property variance_covariance_missing: bool

Check if the variance covariance matrix is missing

Returns:

True if missing.

Return type:

bool

write_f12(overwrite=False)[source]

Writes the estimation results to a file in the F12 format (ALOGIT).

Parameters:

overwrite – If True, the existing file will be overwritten. Default is False.

Return type:

str

Returns:

name of the file

write_latex(variance_covariance_type=None, include_begin_document=False)[source]

Write the results in a LaTeX file.

Return type:

str

Parameters:

variance_covariance_type (EstimateVarianceCovariance | None)

biogeme.results_processing.estimation_results.calc_p_value(t)[source]

Calculates the p value of a parameter from its t-statistic.

The formula is

\[2(1-\Phi(|t|))\]

where \(\Phi(\cdot)\) is the CDF of a normal distribution.

Parameters:

t (float) – t-statistics

Returns:

p-value

Return type:

float

biogeme.results_processing.estimation_results.calculates_correlation_matrix(covariance)[source]

Calculates the correlation matrix.

Return type:

ndarray

Parameters:

covariance (ndarray)