gcubed.reporting

def round_to_significant_figures(x: Any, significant_figures: int = 3) -> Any:

Overview

Round a number to a specified number of significant figures.

Arguments

  • x: The number to be rounded.

  • significant_figures: The number of significant figures to round to. Defaults to 3.

Returns

  • The rounded number as a decimal if the number is a decimal and the original value otherwise. NaN values are returned as NaN. Inf values are returned as Inf.
def generate_html_report( configuration: gcubed.model_configuration.ModelConfiguration, title: str, subtitle: str, documentation_path: pathlib.Path, projections: pandas.core.frame.DataFrame, chartpack_path: pathlib.Path, template_path: pathlib.Path, output_path: pathlib.Path = None, significant_figures: int = 3) -> str:

Overview

Generate the results of an experiment as an HTML file that can be shared with others.

Arguments

  • title: The title of the results - typically used to identify the experiment being run and the simulation layer shown.

  • subtitle: The subtitle of the results - typically used to identify what information is being shown, levels vs deviations and which simulation layers are shown or compared.

  • documentation_path: The path to the Markdown documentation file that contains the boilerplate documentation that you want to include in the heading of the report. This can be the README.md that is included in the simulation experiment folder.

  • projections: The projections data.

  • chartpack_path: The path to the chart pack file.

  • template_path: The path to the template file.

  • output_path: The path where the results will be saved. If None, the results will not be saved. Defaults to None.

  • significant_figures: The number of significant figures to round the projections to. Defaults to 3.

Returns

  • The rendered HTML content so that it can, for example, be displayed directly in a web browser if that is desired.

Exceptions

Assert exceptions are raised if:

  • The configuration must be provided.

  • The title must be provided.

  • The subtitle must be provided.

  • The chart pack path must be provided.

  • The projections must be provided.

  • The template file must exist.

  • The chart pack file must exist.

  • The projections must be a DataFrame.

  • The projections must not be empty.

  • The projections must have a column for the earliest start year.

  • The projections must have a column for the latest end year.

  • Some variables in the chart pack are not in the projections.

def generate_all_simulation_results( chartpack_path: pathlib.Path, documentation_path: pathlib.Path, template_path: pathlib.Path, results_directory_path: pathlib.Path, all_projections: List[gcubed.projections.projections.Projections], derivations: gcubed.projections.derivations.Derivations = None, show_final_results: bool = True):

Overview

Generate the results of a simulation experiment given a list of projections from the experiment.

Projections and deviations from both baseline and the previous simulation layer are saved to the projections_data directory in CSV format. The HTML reports are saved to the html_reports directory.

Arguments

  • chartpack_path: The path to the chart pack file.

  • documentation_path: The path to the Markdown documentation file that contains the boilerplate documentation that you want to include in the heading of the report. This can be the README.md that is included in the simulation experiment folder.

  • template_path: The path to the HTML chart template file that defines the look and functionality of the HTML reports.

  • results_directory_path: The path to the directory where the results will be saved.

  • all_projections: A list of projections from the simulation experiment.

  • derivations: The derivations object that will produce derived variables and their deviations between projections.' Defaults to None.

  • show_final_results: A boolean flag to indicate whether the final results should be shown in a web browser. Defaults to True.

def show_results_page(rendered_html: str):

Overview

Show the results page in a web browser.

def experiment_results_folder( configuration: gcubed.model_configuration.ModelConfiguration, root_results_directory_path: pathlib.Path, experiment_script_name: str) -> str:

Overview

Create a sub-folder of the root results folder to contain the results of an experiment.

Arguments

  • configuration: The configuration object for the model.

  • root_results_directory_path: The path to the root results directory.

  • experiment_script_name: The name of the script used to run the experiment.

Returns

  • The path to the folder where the results of the experiment will be saved.

Exceptions

  • The experiment script name must end with '.py'.

  • The experiment results folder must be created before the function ends.