Presenter

Presenter Module

This module provides functionality for presenting Greenhouse Gas (GHG) emissions computation results in various output formats such as Excel, JSON, LaTeX, and HTML.

Classes:

ExcelWriter:

Formats and writes data to an Excel file.

JSONWriter:

Formats and writes data to a JSON file.

LatexWriter:

Formats and writes data to a LaTeX file using PyLaTeX.

HTMLWriter:

Formats and writes data to an HTML file.

Presenter:

Reads and processes GHG emission calculation results and outputs them using various writers.

Functions:

enforce_unity_sum(vector: List[float], epsilon: float = 0.001) -> List[float]:

Ensures the sum of values in a vector is approximately 1.0 within a given epsilon tolerance.

landcover_pie(axis: plt.Axes, values: List[float], labels: List[str], colors: List[Any],

title: Optional[str] = None, show_legend: bool = False) -> None:

Creates a pie chart of land cover composition using matplotlib.

parse_landcover_composition(vector: List[float]) -> List[float]:

Parses a vector representing land cover composition into a standardized format.

write_par_to_dict(input_name: str, parameter: Any, par_dict: Dict, reservoir_name: str,

precision: int = 3) -> Dict:

Writes a parameter to a dictionary of parameter name-value pairs.

rollout(var_name: str, var_vector: Union[Sequence, Dict]) -> Iterator[Tuple[str, Any]]:

Creates variable names and values from a sequence or dictionary.

round_parameter(number: Union[float, list], number_decimals: int) -> Union[float, list]:

Rounds a number or each element in a list to the specified number of decimals.

Notes

• Each writer class (ExcelWriter, JSONWriter, LatexWriter, HTMLWriter) is designed to handle specific output formats, ensuring the presentation of inputs, outputs, and internal variables in a structured manner.

• All writer classes inherit from the abstract base class Writer, which enforces the implementation of the write method and provides utility methods such as round_parameter, rollout, and write_par_to_dict.

Usage:

[To be added later]

class reemission.presenter.ExcelWriter(inputs: Inputs, outputs: Dict, intern_vars: Dict, output_file_path: str, output_config: Dict, input_config: Dict, intern_vars_config: Dict, parameter_config: Dict, config_ini: Dict, author: str, title: str)

Formats and writes data to an Excel file.

inputs

Inputs object containing input data.

Type:

Inputs

outputs

Outputs dictionary.

Type:

Dict

intern_vars

Internal variables dictionary.

Type:

Dict

output_file_path

Path where the output Excel file will be saved.

Type:

str

output_config

Configuration file with formatting settings for outputs.

Type:

Dict

input_config

Configuration file with formatting settings for inputs.

Type:

Dict

intern_vars_config

Configuration dictionary with formatting settings for internal variables.

Type:

Dict

parameter_config

Configuration file with formatting settings for parameters.

Type:

Dict

config_ini

Global parameter configuration dict (usually from .ini file).

Type:

Dict

author

Author of the Excel document.

Type:

str

title

Title of the Excel document.

Type:

str

output_df

DataFrame containing model outputs.

Type:

pd.DataFrame

input_df

DataFrame containing model inputs.

Type:

pd.DataFrame

intern_vars_df

DataFrame containing internal variables.

Type:

pd.DataFrame

__post_init__()

Initialize output DataFrames which will be output as Excel sheets.

add_inputs(reservoir_name: str) → None

Create an inputs DataFrame for a given reservoir and append it to the main input DataFrame.

Parameters:

reservoir_name (str) – Name of the reservoir for which inputs are to be added.

add_internals(reservoir_name: str) → None

Add internal variables selected for presentation for a given reservoir.

Parameters:

reservoir_name (str) – Name of the reservoir.

add_outputs(reservoir_name: str) → None

Add outputs selected for presentation for a given reservoir.

Parameters:

reservoir_name (str) – Name of the reservoir for which outputs are to be added.

author: str

config_ini: Dict

dict_data_to_df(id: str, data: Dict, config: Dict, index_name: str = 'Name') → DataFrame

Parse data in a dictionary format into pandas DataFrame format.

Parameters:

• id (str) – Identifier for the data (e.g., reservoir name).

• data (Dict) – Dictionary containing data to be parsed into DataFrame.

• config (Dict) – Configuration dictionary specifying which parameters to include.

• index_name (str, optional) – Name of the index column in the DataFrame. Defaults to ‘Name’.

Returns:

DataFrame containing parsed data.

Return type:

pd.DataFrame

input_config: Dict

input_df: DataFrame

inputs: Inputs

intern_vars: Dict

intern_vars_config: Dict

intern_vars_df: DataFrame

output_config: Dict

output_df: DataFrame

output_file_path: str

outputs: Dict

parameter_config: Dict

title: str

write() → None

Write input/output data (all reservoirs) to an Excel file.

class reemission.presenter.HTMLWriter(inputs: Inputs, outputs: Dict, intern_vars: Dict, output_file_path: str, output_config: Dict, input_config: Dict, intern_vars_config: Dict, parameter_config: Dict, config_ini: Dict, author: str, title: str)

Format and write data to an HTML file.

__post_init__() → None

Initialize the HTML content with a basic structure.

add_inputs_table(output_name: str) → None

Add information with model inputs (for each reservoir) to the HTML content.

add_intern_vars_table(output_name: str) → None

Add internal variables table to the HTML content.

add_landcover_piecharts(output_name: str) → None

Add landcover piecharts to the HTML content.

add_outputs_table(output_name: str) → None

Add outputs table to the HTML content.

add_plot(fig, caption: str, dpi: int = 200) → None

Add a plot to the HTML content using PNG format for faster rendering.

add_plots(output_name: str) → None

Generate and add emission plots to the HTML content.

add_section(title: str) → None

Add a section to the HTML content.

add_subsection(title: str) → None

Add a subsection to the HTML content.

add_table(data: Dict, config: Dict, column_names: Tuple[str, str, str]) → None

Add a table to the HTML content.

author: str

config_ini: Dict

html_fragments: List[str]

input_config: Dict

inputs: Inputs

intern_vars: Dict

intern_vars_config: Dict

output_config: Dict

output_file_path: str

outputs: Dict

parameter_config: Dict

plot_emission_bars(axis: Axes, output_name: str) → None

Plot total emissions as a bar chart.

title: str

write() → None

Write the HTML content to the output file.

class reemission.presenter.JSONWriter(inputs: Inputs, outputs: Dict, intern_vars: Dict, output_file_path: str, output_config: Dict, input_config: Dict, intern_vars_config: Dict, parameter_config: Dict, config_ini: Dict, author: str, title: str)

Format and write data to a JSON file.

inputs

Inputs object with input data.

Type:

Inputs

outputs

Outputs dictionary.

Type:

Dict

intern_vars

Internal variables dictionary.

Type:

Dict

output_file_path

Path where the output file is to be saved/written to.

Type:

str

output_config

Configuration dictionary with formatting settings for outputs.

Type:

Dict

input_config

Configuration dictionary with formatting settings for inputs.

Type:

Dict

intern_vars_config

Configuration dictionary with formatting settings for internal variables.

Type:

Dict

parameter_config

Configuration file with formatting settings for parameters.

Type:

Dict

config_ini

Global parameter configuration dict (usually from .ini file).

Type:

Dict

author

Author of the document.

Type:

str

title

Title of the document.

Type:

str

json_dict

Output dictionary saved to the output JSON file. Automatically initialized.

Type:

Dict

__post_init__()

Initialize json_dict which will be output as JSON.

add_inputs(reservoir_name: str) → None

Add inputs selected for presentation for a given reservoir to json_dict.

Parameters:

reservoir_name (str) – Name of the reservoir.

add_internals(reservoir_name: str) → None

Add internal variables selected for presentation for a given reservoir to json_dict.

Parameters:

reservoir_name (str) – Name of the reservoir.

add_outputs(reservoir_name: str) → None

Add outputs selected for presentation for a given reservoir to json_dict.

Parameters:

reservoir_name (str) – Name of the reservoir.

author: str

config_ini: Dict

input_config: Dict

inputs: Inputs

intern_vars: Dict

intern_vars_config: Dict

json_dict: Dict

output_config: Dict

output_file_path: str

outputs: Dict

parameter_config: Dict

parse_dict_data(config: Dict, data: Dict, item_names: Tuple) → Dict

Parse data dictionary into a structured format based on configuration.

Parameters:

• config (Dict) – Configuration dictionary indicating which parameters to include.

• data (Dict) – Dictionary containing data to be parsed.

• item_names (Tuple) – Tuple of item names to include in the parsed output.

Returns:

Parsed dictionary data.

Return type:

Dict

title: str

write() → None

Write output data (all reservoirs) to a JSON file.

class reemission.presenter.LatexWriter(inputs: Inputs, outputs: Dict, intern_vars: Dict, output_file_path: str, output_config: Dict, input_config: Dict, intern_vars_config: Dict, parameter_config: Dict, config_ini: Dict, author: str, title: str)

Format and write data to a LaTeX file using PyLaTeX.

inputs

Inputs object with input data.

Type:

Inputs

outputs

Outputs dictionary.

Type:

Dict

intern_vars

Internal variables dictionary.

Type:

Dict

output_file_path

Path where the output file is to be saved/written to.

Type:

str

output_config

Configuration file with formatting settings.

Type:

Dict

input_config

Configuration file with formatting settings.

Type:

Dict

intern_vars_config

Configuration dictionary with formatting settings.

Type:

Dict

parameter_config

Configuration file with formatting settings.

Type:

Dict

config_ini

Global parameter configuration dict (usually from .ini file).

Type:

Dict

author

Author of the document.

Type:

str

title

Title of the document.

Type:

str

document

PyLaTeX Document object.

Type:

Document

__post_init__() → None

Initialize the PyLaTeX document with specified geometry.

add_header(header_title: str = 'GHG emission estimation results') → None

Adds a header to the LaTeX document source code.

Parameters:

header_title (str) – The title to be added in the header. Defaults to “GHG emission estimation results”.

Returns:

None

add_inputs_subsection(reservoir_name: str) → None

Writes inputs information to the LaTeX document source code.

Parameters:

reservoir_name (str) – The name of the reservoir.

Returns:

None

add_inputs_table(output_name: str, precision: int = 4) → None

Add information with model inputs (for each reservoir).

Parameters:

• output_name (str) – Name of the output/reservoir.

• precision (int) – Number of decimal points in the output input values.

add_intern_var_subsection(reservoir_name: str) → None

Writes internal variable information to the LaTeX document source code.

Parameters:

reservoir_name (str) – The name of the reservoir.

Returns:

None

add_intern_vars_table(output_name: str, precision: int = 4) → None

Adds internal variables table to the LaTeX document.

Parameters:

• output_name (str) – Name of the internal variable/reservoir.

• precision (int) – Number of decimal points in the output values.

add_landcover_charts(output_name: str, plot_fraction: float = 0.95, dpi: int = 300) → None

Add pie charts with landcover proportions for reservoir and catchment.

Parameters:

• output_name (str) – Name of the output/reservoir.

• plot_fraction (float) – Fraction of text width the plot takes on the page. Default is 0.95.

• dpi (int) – Resolution of the created figure within PDF. Default is 300.

add_outputs_subsection(reservoir_name: str) → None

Writes outputs information to the LaTeX document source code.

Parameters:

reservoir_name (str) – The name of the reservoir.

Returns:

None

add_outputs_table(output_name: str, precision: int = 4) → None

Adds outputs table to the LaTeX document.

Parameters:

• output_name (str) – Name of the output/reservoir.

• precision (int) – Number of decimal points in the output values.

add_parameters(precision: int = 4) → None

Add information about model parameters such as conversion factors and other useful details to the report.

Parameters:

precision (int) – Number of decimal points in output parameters. Default is 4.

add_parameters_section() → None

Writes model parameter information to the LaTeX document source code.

Parameters:

None

Returns:

None

add_plots(output_name: str, plot_fraction: float = 0.75, dpi: int = 300) → None

Generate and add emission plots to the document.

Parameters:

• output_name (str) – Name of the output/reservoir.

• plot_fraction (float) – Fraction of text width the plot takes on the page. Default is 0.75.

• dpi (int) – Resolution of the created figure within PDF. Default is 300.

add_title_section(title: str, author: str) → None

Writes the title section to the LaTeX document source code.

Parameters:

• title (str) – The title of the document.

• author (str) – The author of the document.

Returns:

None

author: str

config_ini: Dict

static geometry() → Dict

Create document geometry structure.

Returns:

Dictionary containing the document geometry options.

Return type:

Dict

input_config: Dict

inputs: Inputs

intern_vars: Dict

intern_vars_config: Dict

output_config: Dict

output_file_path: str

outputs: Dict

parameter_config: Dict

plot_emission_bars(axis: Axes, output_name: str) → None

Visualize total emissions (unit x surface area) for the calculated gases.

Parameters:

• axis (plt.Axes) – Matplotlib axes object.

• output_name (str) – Name of the output/reservoir.

plot_landcover_piecharts(axes: ndarray, output_name: str) → None

Plot pie charts of landcover compositions for reservoir and catchment.

Parameters:

• axes (np.ndarray) – Array of matplotlib axes objects.

• output_name (str) – Name of the output/reservoir.

plot_profile(axis: Axes, emission: str, output_name: str, annotate: bool = True) → None

Plot an emission profile using matplotlib.

Parameters:

• axis (plt.Axes) – Matplotlib axes object.

• emission (str) – Name of the gas/emission to plot.

• output_name (str) – Name of the output/reservoir.

• annotate (bool) – Flag setting whether emission values are added to plot. Default is True.

title: str

write() → None

Writes output data (all reservoirs) to .tex and .pdf files.

Parameters:

None

Returns:

None

class reemission.presenter.Presenter(inputs: Inputs, outputs: Dict, intern_vars: Dict, writers: List[Writer] | None = None, author: str = 'Anonymous', title: str = 'Results')

Reads and processes results of GHG emission calculations and outputs them in different formats.

inputs

An instance of Inputs class containing input data.

Type:

Inputs

outputs

Dictionary containing model outputs.

Type:

Dict

intern_vars

Dictionary of internal variables.

Type:

Dict

writers

Optional list of Writer objects for output.

Type:

Optional[List[Writer]]

author

Name of the author. Default is ‘Anonymous’.

Type:

str

title

Title of the document. Default is ‘Results’.

Type:

str

__post_init__()

Loads configuration files after instance initialization.

add_writer(writer: Type[Writer], output_file: str) → None

Adds a Writer object to the list of writers.

Parameters:

• writer (Type[Writer]) – Type of Writer to instantiate.

• output_file (str) – Path to the output file for the Writer.

Returns:

None

author: str = 'Anonymous'

classmethod fromfiles(input_file: str, output_file: str, interns_file: str, **kwargs)

Creates an instance of Presenter from JSON files.

Parameters:

• input_file (str) – Path to JSON file containing input data.

• output_file (str) – Path to JSON file containing model outputs.

• interns_file (str) – Path to JSON file containioutput_file_pathng internal variables.

• **kwargs – Additional keyword arguments for customization.

Returns:

An instance of Presenter initialized with data loaded from files.

Return type:

Presenter

inputs: Inputs

intern_vars: Dict

output() → None

Outputs GHG emission calculation results using writers.

outputs: Dict

title: str = 'Results'

writers: List[Writer] | None = None

class reemission.presenter.Writer

Abstract base class for all writers.

static rollout(var_name: str, var_vector: Sequence | Dict) → Iterator[Tuple[str, Any]]

Creates variable names and values from a sequence or dictionary.

Parameters:

• var_name (str) – Base name for the variables.

• var_vector (Union[Sequence, Dict]) – Sequence or dictionary containing variable values.

Yields:

Iterator[Tuple[str, Any]] – Iterator yielding tuples of variable names and values.

Example

a variable var = [3,4,5] becomes: (‘var_0’, 3), (‘var_1’, 4), (‘var_2’, 5).

static round_parameter(number: float | list, number_decimals: int) → float | list

Rounds a number or each element in a list to the specified number of decimals.

Parameters:

• number (Union[float, list]) – The number or list of numbers to round.

• number_decimals (int) – Number of decimal places to round to.

Returns:

Rounded number or list of rounded numbers.

Return type:

Union[float, list]

abstract write() → None

Writes outputs to the format of choice.

static write_par_to_dict(input_name: str, parameter: Any, par_dict: Dict, reservoir_name: str, precision: int = 3) → Dict

Writes a parameter to a dictionary of parameter name-value pairs.

Parameters:

• input_name (str) – Name of the input parameter.

• parameter (Any) – Parameter data. It can be a single value, sequence, or nested sequence.

• par_dict (Dict) – Dictionary of parameter names and values in the form {reservoir_name: {par_name: par_values}}.

• reservoir_name (str) – Name of the reservoir for which the parameter is to be added.

• precision (int, optional) – Number of decimal points for the parameter. Defaults to 3.

Returns:

Updated dictionary of parameter names and values.

Return type:

Dict

reemission.presenter.emission_bars(axis: Axes, gases: List[str], values: List[float], output_name: str) → None

Visualize total emissions (unit x surface area) for the calculated gases.

Parameters:

• axis (plt.Axes) – Matplotlib axes object.

• gases (List[str]) – List of gas names to be displayed on the y-axis.

• values (List[float]) – List of total annual emissions for each gas.

• output_name (str) – Name of the output/reservoir.

reemission.presenter.emission_profile(axis: Axes, years: List[int], emissions: List[float], title: str, y_label: str, annotate: bool = True) → None

Plots a profile of emissions over time.

Parameters:

• axis (plt.Axes) – Matplotlib axes object.

• years (List[int]) – List of years corresponding to the emissions.

• emissions (List[float]) – List of emissions corresponding to the years.

• title (str) – Title of the plot.

• y_label (str) – Label for the y-axis.

• annotate (bool) – Flag setting whether emission values are added to plot. Default is True.

Raises:

ValueError – If the lengths of years and emissions do not match, or if they contain non-numeric values.

reemission.presenter.enforce_unity_sum(vector: List[float], epsilon: float = 0.001) → List[float]

Ensures the sum of values in the vector is approximately 1.0 within a given epsilon tolerance.

Parameters:

• vector (List[float]) – The input vector of float values to be normalized.

• epsilon (float, optional) – Tolerance level around 1.0 within which the sum of the vector should lie. Defaults to 0.001.

Returns:

A normalized vector where the sum of values is approximately 1.0.

Return type:

List[float]

Note

• If the sum of values in the input vector is not within the range [1.0 - epsilon, 1.0 + epsilon], the vector is normalized by dividing each element by the current sum of the vector.

reemission.presenter.format_number(x) → str

Formats a number for display in a human-readable way. :param x: The number to format. It can be an int, float, or None. :type x: Any

Returns:

A string representation of the number formatted for readability.

Return type:

str

Note

• If x is None, it returns “—” (or “N/A”).

• If x is an integer, it returns the integer as a string.

• For floats, it formats them based on their magnitude:

  • Very large or very negative values are formatted with 1 decimal point.

  • Moderate values are formatted with up to 5 significant digits.

  • Very small values are formatted with 3 significant digits.

  • Extremely small values are formatted in engineering notation.

reemission.presenter.landcover_pie(axis: Axes, values: List[float], labels: List[str], colors: List[Any], title: str | None = None, show_legend: bool = False) → None

Creates a pie chart of land cover composition.

Parameters:

• axis (plt.Axes) – The matplotlib axis object where the pie chart will be drawn.

• values (List[float]) – List of float values representing the proportions of each land cover type.

• labels (List[str]) – List of strings representing labels for each land cover type.

• colors (List[Any]) – List of colors corresponding to each land cover type.

• title (str, optional) – Title of the pie chart. Defaults to None.

• show_legend (bool, optional) – Whether to display the legend. Defaults to False.

Returns:

None

Note

• The function creates a pie chart using matplotlib on the provided axis (axis).

• Only land cover types with non-zero values (values > 0) are included in the chart.

• The pie is exploded to highlight the land cover type with the highest proportion.

• Labels and percentages are formatted and positioned for readability.

reemission.presenter.parse_landcover_composition(vector: List[float]) → List[float]

Parses a vector representing land cover composition into a standardized format.

Parameters:

vector (List[float]) – A vector representing land cover composition. It should be either a 9-element vector or a 27-element vector.

Returns:

A 9-element vector representing the parsed land cover composition.

Return type:

List[float]

Raises:

ValueError – If the provided vector does not have a length of 9 or 27.

Note

• If the input vector length is 9, it is returned as-is.

• If the input vector length is 27, it is split into three equal parts, each part is summed element-wise, resulting in a 9-element vector.