Presenter

Presenter Module

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

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.

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

Each writer class (ExcelWriter, JSONWriter, LatexWriter) is designed to handle specific output formats, ensuring the presentation of inputs, outputs, and internal variables in a structured manner. All writers inherit from an abstract base class Writer which implements the following static methods:

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

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

• def write_par_to_dict(input_name: str, parameter: Any, par_dict: Dict, reservoir_name: str, precision: int = 3) -> Dict

and enforces implementation of the write method.

Functions:

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

• landcover_pie: Creates a pie chart of land cover composition using matplotlib.

• parse_landcover_composition: Parses a vector representing land cover composition into a standardized format.

• write_par_to_dict: Writes a parameter to a dictionary of parameter name-value pairs.

• rollout: Creates variable names and values from a sequence or dictionary.

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

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: ConfigParser, 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 file.

Type:

configparser.ConfigParser

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: ConfigParser

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.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: ConfigParser, 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 file.

Type:

configparser.ConfigParser

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: ConfigParser

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: ConfigParser, 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 file.

Type:

configparser.ConfigParser

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: ConfigParser

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 containing 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.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.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.