biogeme.bayesian_estimation.html_output module

Generates an HTML output for Bayesian results

Michel Bierlaire Mon Oct 20 2025, 19:27:28

exception biogeme.bayesian_estimation.html_output.EmptyListOfParameters[source]

Bases: BiogemeError

class biogeme.bayesian_estimation.html_output.FigureSize(*values)[source]

Bases: Enum

Discrete size scale for diagnostic figures and embedded images.

LARGE = 'large'
MEDIUM = 'medium'
NONE = 'none'
SMALL = 'small'
VERY_LARGE = 'very_large'
biogeme.bayesian_estimation.html_output.format_real_number(value)[source]

Format a real number for inclusion in an HTML table.

Parameters:

value (float) – Number to format.

Return type:

str

Returns:

A short string representation (currently using .3g formatting).

biogeme.bayesian_estimation.html_output.generate_html_file(estimation_results, filename, overwrite=False, figure_size=FigureSize.MEDIUM)[source]

Generate an HTML file with the estimation results

Parameters:

  • estimation_results (BayesianResults) – estimation results

  • filename (str) – name of the file

  • overwrite – if True and the file exists, it is overwritten

  • figure_size (FigureSize) – FigureSize for diagnostics (default: MEDIUM)

Return type:

None

biogeme.bayesian_estimation.html_output.generate_html_simulated_data(estimation_results)[source]
Return type:

str

Parameters:

estimation_results (BayesianResults)

biogeme.bayesian_estimation.html_output.generate_one_row(description, value)[source]

Generate a single HTML table row with a description/value pair.

Parameters:

  • description (str) – Label shown in the left column.

  • value (str) – Value shown in the right column.

Return type:

str

Returns:

HTML code for one <tr> row.

biogeme.bayesian_estimation.html_output.get_html_arviz_diagnostics(estimation_results, html_filename, var_names=None, figure_size=FigureSize.MEDIUM)[source]

Generate ArviZ diagnostic figures and return an HTML snippet embedding them.

The figures (trace, rank, energy, autocorrelation) are saved next to the HTML file in a sibling folder named <html_basename>_figs.

Parameters:

  • estimation_results (BayesianResults) – Bayesian estimation results holding the InferenceData.

  • html_filename (str) – Target HTML filename (used to locate the figures directory).

  • var_names (list[str] | None) – Optional list of variables to include in the diagnostics.

  • figure_size (FigureSize) – Size level controlling figure sizes and embedded image width.

Return type:

str

Returns:

An HTML snippet containing <img> tags (or an empty string if disabled).

biogeme.bayesian_estimation.html_output.get_html_estimated_parameters(estimation_results, estimated_parameters=True, renaming_parameters=None, sort_by_name=False)[source]

Get the estimated parameters coded in HTML

Parameters:

  • estimation_results (BayesianResults) – estimation results.

  • estimated_parameters (bool) – if True, only the estimated parameters are generated. If False, only the other variables are generated.

  • renaming_parameters (dict[str, str] | None) – a dict that suggests new names for some or all parameters.

  • sort_by_name (bool) – if True, parameters are sorted alphabetically by name.

Return type:

str

Returns:

HTML code

Prepare the footer for the HTML file, containing comments and the version of Biogeme.

Return type:

str

biogeme.bayesian_estimation.html_output.get_html_general_statistics(estimation_results)[source]

Get the general statistics coded in HTML

Return type:

str

Returns:

HTML code

Parameters:

estimation_results (BayesianResults)

biogeme.bayesian_estimation.html_output.get_html_header(estimation_results)[source]

Prepare the header for the HTML file, containing comments and the version of Biogeme.

Return type:

str

Returns:

string containing the header.

Parameters:

estimation_results (BayesianResults)

biogeme.bayesian_estimation.html_output.get_html_identification_diagnostics(estimation_results)[source]

Generate an HTML section reporting identification diagnostics.

The goal is to help detect (i) non-identification / weak identification and (ii) cases where parameters appear to be primarily determined by the prior rather than by the likelihood.

The section is based on the posterior (and, if present in the InferenceData, the prior) draws.

Interpretation guide (heuristics):

  • Posterior covariance eigenvalues / condition number: a very small minimum eigenvalue or a very large condition number suggests directions in parameter space that are nearly flat (non-identified or weakly identified). This typically manifests as strong posterior correlations, slow mixing, divergent transitions, and sensitivity to priors.

  • Effective rank: an effective rank substantially smaller than the number of parameters indicates that the posterior variability is concentrated in a lower-dimensional subspace, which is consistent with linear (or nearly linear) dependencies among parameters.

  • Prior vs posterior dispersion (only if prior draws were saved): if a parameter’s posterior standard deviation is close to its prior standard deviation, the data may be providing little information about that parameter (“identified by the prior”). Conversely, a much smaller posterior standard deviation indicates that the likelihood is informative.

These diagnostics are not formal proofs of non-identification; they are practical signals to investigate the model specification (normalizations, redundant parameters, collinearity, and coding).

Parameters:

estimation_results (BayesianResults) – Bayesian estimation results.

Return type:

str

Returns:

HTML code for the identification diagnostics section, or an empty string if unavailable.

biogeme.bayesian_estimation.html_output.get_html_one_parameter(estimation_results, parameter_number, parameter_name)[source]

Generate the HTML code for one row of the table of the estimated parameters.

Parameters:

  • estimation_results (BayesianResults) – estimation results.

  • parameter_number (int) – index of the parameter

  • parameter_name (str) – name of the parameter to report. If None, taken from estimation results.

Return type:

str

Returns:

HTML code for the row

biogeme.bayesian_estimation.html_output.get_html_preamble(estimation_results, file_name)[source]

Generates the first part of the HTML, with the preamble information.

Parameters:

  • estimation_results (BayesianResults) – estimation results

  • file_name (str) – name of the HTML file (used only for reporting)

Return type:

str

Returns:

HTML code