biogeme.bayesian_estimation.bayesian_results_summary module

class biogeme.bayesian_estimation.bayesian_results_summary.BayesianResultsSummary(model_name, data_name, chains, draws, hdi_prob, calculate_likelihood, calculate_waic, calculate_loo, beta_names, parameters, array_metadata, posterior_predictive_loglike=None, expected_log_likelihood=None, best_draw_log_likelihood=None, waic=None, waic_se=None, p_waic=None, loo=None, loo_se=None, p_loo=None, sampler=None, target_accept=None, run_time=None, number_of_observations=None, user_notes=None, stored_variables_report=None, identification_diagnostics_summary=None, diagnostic_figure_references=None)

Bases: object

Compact summary of Bayesian estimation results.

This object is designed to be saved as YAML and reloaded later without requiring the original posterior draws. It supports summary-level inspection of the estimation results, but not computations that depend on posterior samples.

Parameters:

• model_name (str) – Name of the estimated model.

• data_name (str) – Name of the dataset.

• chains (int) – Number of MCMC chains.

• draws (int) – Number of draws per chain.

• hdi_prob (float) – Credible mass used for highest-density intervals.

• calculate_likelihood (bool) – Whether likelihood-based quantities were computed.

• calculate_waic (bool) – Whether WAIC was computed.

• calculate_loo (bool) – Whether LOO was computed.

• beta_names (list[str]) – Names of the model parameters of primary interest.

• parameters (dict[str, EstimatedBetaSummary]) – Mapping from scalar posterior variable name to summary.

• array_metadata (dict[str, dict]) – Metadata for posterior variables with extra dimensions beyond chain and draw.

• posterior_predictive_loglike (float | None) – Posterior-predictive log density.

• expected_log_likelihood (float | None) – Posterior expectation of the total log-likelihood.

• best_draw_log_likelihood (float | None) – Best total log-likelihood across posterior draws.

• waic (float | None) – WAIC criterion.

• waic_se (float | None) – Standard error of WAIC.

• p_waic (float | None) – Effective number of parameters for WAIC.

• loo (float | None) – LOO criterion.

• loo_se (float | None) – Standard error of LOO.

• p_loo (float | None) – Effective number of parameters for LOO.

• sampler (str | None) – Name of the sampler.

• target_accept (float | None) – Target acceptance rate.

• run_time (str | float | None) – Total run time as a string or numeric value.

• number_of_observations (int | None) – Sample size.

• user_notes (list[str] | None) – Optional user-defined notes to include in reports.

• stored_variables_report (list[dict[str, Any]] | None) – Optional report of variables stored in the underlying inference data.

• model_name – Name of the estimated model.

• data_name – Name of the dataset.

• chains – Number of MCMC chains.

• draws – Number of draws per chain.

• hdi_prob – Credible mass used for highest-density intervals.

• calculate_likelihood – Whether likelihood-based quantities were computed.

• calculate_waic – Whether WAIC was computed.

• calculate_loo – Whether LOO was computed.

• beta_names – Names of the model parameters of primary interest.

• parameters – Mapping from scalar posterior variable name to summary.

• array_metadata – Metadata for posterior variables with extra dimensions beyond chain and draw.

• posterior_predictive_loglike – Posterior-predictive log density.

• expected_log_likelihood – Posterior expectation of the total log-likelihood.

• best_draw_log_likelihood – Best total log-likelihood across posterior draws.

• waic – WAIC criterion.

• waic_se – Standard error of WAIC.

• p_waic – Effective number of parameters for WAIC.

• loo – LOO criterion.

• loo_se – Standard error of LOO.

• p_loo – Effective number of parameters for LOO.

• sampler – Name of the sampler.

• target_accept – Target acceptance rate.

• run_time – Total run time as a string or numeric value.

• number_of_observations – Sample size.

• stored_variables_report – Optional report of variables stored in the underlying inference data.

• identification_diagnostics_summary (dict[str, Any] | None) – Optional precomputed summary of identification diagnostics derived from the posterior draws.

• diagnostic_figure_references (dict[str, str] | None) – Optional mapping from diagnostic figure names to paths or filenames of pre-rendered figures.

array_metadata: dict[str, dict]

arviz_summary()

Unavailable for YAML summaries.

Raises:

BiogemeError – Always, because posterior draws are not available.

Return type:

DataFrame

best_draw_log_likelihood: float | None = None

beta_names: list[str]

calculate_likelihood: bool

calculate_loo: bool

calculate_waic: bool

chains: int

data_name: str

diagnostic_figure_references: dict[str, str] | None = None

draws: int

dump_yaml(path)

Write the summary to a YAML file.

Parameters:

path (str) – Output YAML filename.

Return type:

None

expected_log_likelihood: float | None = None

classmethod from_dict(data)

Rebuild a summary object from a plain dictionary.

Parameters:

data (dict[str, Any]) – Dictionary representation.

Return type:

BayesianResultsSummary

Returns:

Reconstructed summary object.

classmethod from_yaml_file(filename)

Load a summary from a YAML file.

Parameters:

filename (str) – Path to the YAML file.

Return type:

BayesianResultsSummary

Returns:

Reconstructed summary object.

generate_general_information()

Generate a summary dictionary for display.

Return type:

dict[str, Any]

Returns:

Dictionary of general result information.

get_beta_values(my_betas=None)

Retrieve posterior means for selected parameters.

Parameters:

my_betas (list[str] | None) – Names of the requested parameters. If None, all model parameters are returned.

Return type:

dict[str, float]

Returns:

Mapping from parameter name to posterior mean.

Raises:

BiogemeError – If an unknown parameter name is requested.

get_betas_for_sensitivity_analysis(my_betas=None, size=100)

Unavailable for YAML summaries.

Parameters:

• my_betas (list[str] | None) – Names of the requested parameters.

• size (int) – Number of requested draws.

Raises:

BiogemeError – Always, because posterior draws are not available.

Return type:

list[dict[str, float]]

get_diagnostic_figure_references()

Return the stored diagnostic figure references.

Return type:

dict[str, str]

Returns:

Mapping from diagnostic figure names to stored figure paths.

get_identification_diagnostics_summary()

Return the stored identification diagnostics summary.

Return type:

dict[str, Any] | None

Returns:

Precomputed identification diagnostics summary, if available.

get_user_notes()

Return the stored user notes.

Return type:

list[str]

Returns:

User notes, or an empty list if none are available.

has_posterior_draws: bool = False

hdi_prob: float

identification_diagnostics(*args, **kwargs)

Unavailable for YAML summaries.

Raises:

BiogemeError – Always, because posterior draws are not available.

Return type:

Any

Parameters:

• args (Any)

• kwargs (Any)

identification_diagnostics_summary: dict[str, Any] | None = None

list_array_variables()

Return metadata for posterior variables with extra dimensions.

Return type:

dict[str, dict]

Returns:

Metadata keyed by variable name.

loo: float | None = None

loo_se: float | None = None

model_name: str

number_of_observations: int | None = None

other_variables()

Return scalar posterior summaries that are not listed as main parameters.

Return type:

dict[str, EstimatedBetaSummary]

Returns:

Mapping from variable name to summary.

p_loo: float | None = None

p_waic: float | None = None

parameter_estimates()

Return only the explicitly declared model parameters.

Return type:

dict[str, EstimatedBetaSummary]

Returns:

Mapping from parameter name to summary.

parameters: dict[str, EstimatedBetaSummary]

property posterior_draws: int

Total number of posterior draws.

Returns:

Number of chains times number of draws per chain.

posterior_mean_by_observation(var_name)

Unavailable for YAML summaries.

Parameters:

var_name (str) – Name of the requested variable.

Raises:

BiogemeError – Always, because posterior draws are not available.

Return type:

DataFrame

posterior_predictive_loglike: float | None = None

report_stored_variables()

Return the stored-variable report as a DataFrame.

Return type:

DataFrame

Returns:

DataFrame describing stored variables.

run_time: str | float | None = None

sampler: str | None = None

short_summary()

Return a plain-text summary table.

Return type:

str

Returns:

Text summary.

stored_variables_report: list[dict[str, Any]] | None = None

summarize_array_variable(*args, **kwargs)

Unavailable for YAML summaries.

Raises:

BiogemeError – Always, because posterior draws are not available.

Return type:

Any

Parameters:

• args (Any)

• kwargs (Any)

target_accept: float | None = None

to_dict()

Serialize the summary to a plain dictionary suitable for YAML.

Return type:

dict[str, Any]

Returns:

Dictionary representation.

user_notes: list[str] | None = None

waic: float | None = None

waic_se: float | None = None

class biogeme.bayesian_estimation.bayesian_results_summary.EstimatedBetaSummary(name, mean, median, mode, std_err, z_value, p_value, hdi_low, hdi_high, rhat, effective_sample_size_bulk, effective_sample_size_tail)

Bases: object

Posterior summary for one scalar parameter.

Parameters:

• name (str) – Name of the parameter.

• mean (float) – Posterior mean.

• median (float) – Posterior median.

• mode (float) – Posterior mode.

• std_err (float) – Posterior standard deviation.

• z_value (float | None) – Mean divided by posterior standard deviation.

• p_value (float | None) – Two-sided posterior tail probability relative to zero.

• hdi_low (float | None) – Lower bound of the highest-density interval.

• hdi_high (float | None) – Upper bound of the highest-density interval.

• rhat (float) – Rank-normalized R-hat diagnostic.

• effective_sample_size_bulk (float) – Bulk effective sample size.

• effective_sample_size_tail (float) – Tail effective sample size.

documentation: ClassVar[dict[str, str]] = {'ESS (bulk)': 'Effective sample size for the central part of the posterior; values above ~400 are generally considered sufficient.', 'ESS (tail)': 'Effective sample size for the posterior tails; values above ~100 ensure reliable estimates of extreme quantiles.', 'HDI low / HDI high': 'Lower and upper bounds of the Highest Density Interval containing the most probable parameter values.', 'Median': 'Posterior median (50% quantile) of the parameter.', 'Mode': 'Posterior mode (most frequent value) of the parameter.', 'Name': 'Identifier of the model parameter being estimated.', 'R-hat (Gelman–Rubin)': 'Convergence diagnostic; values very close to 1 (typically ≤ 1.01) indicate well-mixed chains.', 'Std err.': 'Posterior standard deviation, measuring uncertainty around the mean.', 'Value': 'Posterior mean (expected value) of the parameter.', 'p-value': 'Two-sided Bayesian tail probability that the parameter differs in sign from zero.', 'z-value': 'Standardized estimate (mean divided by std. dev.), indicating signal-to-noise ratio.'}

effective_sample_size_bulk: float

effective_sample_size_tail: float

classmethod from_dict(data)

Build an instance from a plain dictionary.

Parameters:

data (dict[str, Any]) – Dictionary representation.

Return type:

EstimatedBetaSummary

Returns:

Reconstructed summary object.

hdi_high: float | None

hdi_low: float | None

mean: float

median: float

mode: float

name: str

p_value: float | None

rhat: float

std_err: float

to_dict()

Serialize the summary to a plain dictionary.

Return type:

dict[str, Any]

Returns:

Dictionary representation.

z_value: float | None