biogeme.results_processing.latex_output module

Generates a LaTeX output

Michel Bierlaire Mon Sep 30 17:50:30 2024

biogeme.results_processing.latex_output.add_trailing_zero(formatted_number)

If the formatted number does not contain a period, we add at the end a period and a zero.

Parameters:

formatted_number (str) – number already formatted

Return type:

str

Returns:

process strings

biogeme.results_processing.latex_output.compare_parameters(estimation_results, p_thresholds=None, renumbering_parameters=None, renaming_parameters=None)

Parameters:

• estimation_results (dict[str, EstimationResults]) – dict mapping model names with estimation results

• p_thresholds (list[tuple[float, str]] | None) – list of tuple establishing the coding convention for the p-value threshold. Assume that the

• renumbering_parameters (dict[int, int] | None)

• renaming_parameters (dict[str, str] | None)

Return type:

str

list is composed of pairs (t_i, sign_i), and that the p-value of a parameter is p. Among all i such that p <= t_i, select index k associated with the minimum t_k. Then the p-value is coded using sign_k. :type renumbering_parameters: dict[int, int] | None :param renumbering_parameters: a dict that suggests new numbers for parameters :type renaming_parameters: dict[str, str] | None :param renaming_parameters: a dict that suggests new names for some or all parameters.

Return type:

str

Returns:

the LaTeX code of a tabular object compile the estimation results.

Parameters:

• estimation_results (dict[str, EstimationResults])

• p_thresholds (list[tuple[float, str]] | None)

• renumbering_parameters (dict[int, int] | None)

• renaming_parameters (dict[str, str] | None)

biogeme.results_processing.latex_output.draw_confidence_ellipse(ellipse, first_reporting_name, second_reporting_name)

Provides a Tikz picture of the confidence ellipsis for two parameters :type ellipse: Ellipse :param ellipse: ellipse to be drawn :type first_reporting_name: str :param first_reporting_name: name to use in the reporting for the first parameter :type second_reporting_name: str :param second_reporting_name: name to use in the reporting for the second parameter

Return type:

str

Parameters:

• ellipse (Ellipse)

• first_reporting_name (str)

• second_reporting_name (str)

biogeme.results_processing.latex_output.format_real_number(value)

Format a real number to be included in the LaTeX table

Return type:

str

Parameters:

value (float)

biogeme.results_processing.latex_output.format_with_period(value)

Formats a number using the ‘.3g’ format while ensuring that a decimal point is always present.

Parameters:

value – The number to format (int or float).

Returns:

A string representation of the number in ‘.3g’ format, always containing a period.

Example: >>> format_with_period(1) ‘1.0’ >>> format_with_period(1.23) ‘1.23’ >>> format_with_period(1234) ‘1230’ >>> format_with_period(1000000) ‘1e+06’ >>> format_with_period(0.00456) ‘0.00456’

biogeme.results_processing.latex_output.generate_latex_file(estimation_results, filename, include_begin_document=False, overwrite=False, variance_covariance_type=None, group_of_parameters=None)

Generate and save a LaTeX document that summarizes the model estimation results.

This function calls generate_latex_file_content to build the full LaTeX document, and writes it to a file. If the file already exists and overwrite is False, a FileExistsError is raised.

Parameters:

• estimation_results (EstimationResults) – Estimation results to be documented.

• include_begin_document – if True, the LaTeX file can be directly compiled. If False, it must be included in another document.

• filename (str) – Path to the LaTeX file to be created.

• overwrite – If True, overwrite the file if it already exists. Defaults to False.

• variance_covariance_type (EstimateVarianceCovariance | None) – select which type of variance-covariance matrix is used to generate the statistics. If None, the bootstrap one is used if available. If not available, the robust one.

• group_of_parameters (dict[str, list[str]] | None) – dictionary mapping subsection names to lists of parameter names. If None, all estimated parameters are reported in one table. If provided, one table is generated for each group, and another table is generated for parameters that do not appear in any group.

Return type:

None

biogeme.results_processing.latex_output.generate_latex_file_content(estimation_results, filename, variance_covariance_type, include_begin_document=False, group_of_parameters=None)

Generate the full content of a LaTeX document summarizing the estimation results, and prepare it for export to a file.

This function assembles a complete LaTeX document including the document header, general statistics, and the estimated parameter table. It is intended to be used to produce a full report from Biogeme estimation results.

Parameters:

• estimation_results (EstimationResults) – The estimation results object containing the model outputs.

• filename (str) – The name of the LaTeX file, used only for documentation within the file.

• include_begin_document – if True, the LaTeX file can be directly compiled. If False, it must be included in another document.

• variance_covariance_type (EstimateVarianceCovariance) – select which type of variance-covariance matrix is used to generate the statistics.

• group_of_parameters (dict[str, list[str]] | None) – dictionary mapping subsection names to lists of parameter names. If None, all estimated parameters are reported in one table. If provided, one table is generated for each group, and another table is generated for parameters that do not appear in any group.

Return type:

str

Returns:

None. The LaTeX content is generated as a string but not written to a file.

biogeme.results_processing.latex_output.get_latex_estimated_parameters(estimation_results, group_of_parameters=None, variance_covariance_type=None, renumbering_parameters=None, renaming_parameters=None)

Get the estimated parameters coded in LaTeX.

The function returns one LaTeX table for each group of parameters. If no group is provided, a single table containing all estimated parameters is returned. If groups are provided, one table is generated for each group, and an additional table is generated for the parameters that do not belong to any group. A parameter may appear in several groups.

Parameters:

• estimation_results (EstimationResults) – estimation results.

• group_of_parameters (dict[str, list[str]]) – dictionary mapping the name of each group to the corresponding list of parameters. If None, all parameters are reported in a single table.

• variance_covariance_type (EstimateVarianceCovariance | None) – type of variance-covariance estimate used to compute standard errors, t-statistics, and p-values. If None, the default variance-covariance matrix of estimation_results is used.

• renumbering_parameters (dict[int, int] | None) – dictionary mapping original parameter numbers to the numbers to be reported in the tables.

• renaming_parameters (dict[str, str] | None) – dictionary mapping original parameter names to the names to be reported in the tables. Parameters not appearing in the dictionary keep their original names.

Return type:

dict[str, str]

Returns:

dictionary mapping each group name to the corresponding LaTeX code. The key is an empty string when no grouping is requested.

biogeme.results_processing.latex_output.get_latex_general_statistics(estimation_results)

Get the general statistics coded in LaTeX

Return type:

str

Returns:

LaTeX code

Parameters:

estimation_results (EstimationResults)

biogeme.results_processing.latex_output.get_latex_one_parameter(estimation_results, parameter_index, variance_covariance_type, parameter_number=None, parameter_name=None)

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

Parameters:

• estimation_results (EstimationResults) – estimation results.

• parameter_index (int) – index of the parameter

• variance_covariance_type (EstimateVarianceCovariance) – type of variance-covariance estimate to be used.

• parameter_number – number of the parameter to report. If None, it is the index.

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

Return type:

str

Returns:

LaTeX code for the row

biogeme.results_processing.latex_output.get_latex_preamble(estimation_results, file_name)

Generates the first part of the LaTeX file, with the preamble information.

Parameters:

• estimation_results (EstimationResults) – estimation results

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

Return type:

str

Returns:

HTML code

biogeme.results_processing.latex_output.get_sign_for_p_value(p_value, p_thresholds)

Parameters:

• p_value (float) – p-value to be treated

• p_thresholds (list[tuple[float, str]]) – list of tuple establishing the coding convention for the p-value threshold. Assume that the

Return type:

str

list is composed of pairs (t_i, sign_i), and that the p-value of a parameter is p. Among all i such that p <= t_i, select index k associated with the minimum t_k. Then the p-value is coded using sign_k.

Return type:

str

Returns:

sign to be used

Parameters:

• p_value (float)

• p_thresholds (list[tuple[float, str]])

biogeme.results_processing.latex_output.rename_and_renumber(names, renumbering_parameters=None, renaming_parameters=None)

Rename and renumber parameters according to instructions from the user

Parameters:

• names (list[str]) – list of existing names

• renumbering_parameters (dict[int, int] | None) – dict mapping old numbers to new numbers.

• renaming_parameters (dict[str, str] | None) – dict mapping old names to new names.

Return type:

dict[int, tuple[int, str]]

Returns:

dict mapping the original parameter index with the new number and the new name.