Report writing

Created on Mon Apr 8 14:58:26 2024

@author: ibhan

The modelreport module facilitates the generation, management, and display of data visualizations and tables derived from ModelFlow models. It is designed to support a wide range of output formats including LaTeX documents, HTML, and interactive IPyWidgets, making it highly versatile for different reporting and analysis needs in Jupyter notebook environments.

This module provides a structured and extendible approach to organizing and rendering data analysis results, enabling users to easily convert complex model outputs into digestible visual representations and tables. It is especially useful for automating the reporting process in data analysis, financial modeling, and research projects, leveraging Python’s capabilities for data processing and visualization along with advanced document presentation features.

Key Features:

Dynamic generation of LaTeX and HTML content for integrating data visualizations and tables into reports and presentations.
Compatibility with IPyWidgets for creating interactive, widget-based displays that enhance the interactivity of Jupyter notebooks.
Seamless integration with matplotlib for figure generation and pandas for table formatting, providing a comprehensive toolkit for data display.
Customizable display options and specifications through dataclasses, allowing for tailored presentation styles and formats.

Classes:

Options: Configures display options for managing how data and figures are presented, including naming conventions, formatting preferences, and title settings.
Line: Defines line configurations for table displays, supporting various data representation and difference calculations to suit different analysis needs.
DisplaySpec: Groups display options and line configurations, facilitating the management of complex display setups in a structured manner.
DisplayDef: Base class for display definitions, capable of compiling various display components into cohesive specifications for rendering.
LatexRepo: Handles the generation of LaTeX content, compilation into PDFs, and embedding within Jupyter notebooks, supporting both static and dynamic content creation.
DisplayVarTableDef: Specializes in displaying variable tables, automating the creation and formatting of tables from ModelFlow model outputs.
DisplayFigWrapDef: Focuses on wrapping and adjusting matplotlib figures for inclusion in various display formats, ensuring figures are presentation-ready.
SplitTextResult: Parses a string containing text with embedded <html>, <latex>, and <markdown> tags and separates the content accordingly.
DatatypeAccessor: Manages configurations for different datatypes, allowing for easy access and parsing of configuration tables provided in Markdown format.

The modeldisplay module bridges the gap between analytical modeling and result presentation, offering a streamlined workflow for transforming ModelFlow model outputs into high-quality visual and tabular displays suitable for a wide range of purposes.

modelreport.track_fields()[source]

A decorator to track which fields in a dataclass have been explicitly set during initialization.

This decorator modifies the __init__ method of a dataclass to keep track of which fields have been explicitly set by the user when an instance is created. The explicitly set fields are stored in a set called __explicitly_set__.

Returns:: A decorator function that modifies the dataclass to track explicitly set fields.
Return type:: wrap (function)

class modelreport.DatatypeAccessor(datatype, **kwargs)[source]

Bases: object

Initializes the ConfigAccessor with a datatype and a configuration table in Markdown format.

Parameters:

datatype – A string keyword to fetch configuration for.
config_table – A string representing the configuration in Markdown table format.

parse_config_table(config_table)[source]

Parses a Markdown table into a dictionary of configurations.

Parameters:: config_table – Markdown table as a string.
Returns:: Dictionary with datatype keys and property dictionaries as values.

class modelreport.DisplayDef(mmodel: Any = None, spec: modelreport.DisplaySpec = <factory>, name: str = '')[source]

Bases: object

mmodel: Any = None

spec: DisplaySpec

name: str = ''

set_name(name)[source]

property get_report_smpl

property save_spec

get_rowdes(df, line, row=True)[source]

pdf(pdfopen=False, show=True, width='100%', height='400px', typesetter='xelatex -interaction=batchmode -no-shell-escape')[source]

Generates a PDF file from the LaTeX content and optionally displays it.

This method creates a directory for LaTeX files, writes the LaTeX content to a .tex file, and uses a specified typesetter to compile it into a PDF. The resulting PDF can be displayed in an IFrame or opened in the default PDF viewer.

Requires that miktex or another appropiate latex framework is installed.

Inspect the latex source by specifying: typesetter=’texworks’

The files are located in the folder called latex/{name}

The .tex file is called {name.tex}

the .pdf file is called {name.pdf}

Parameters:

pdfopen (bool) – If True, opens the generated PDF file in the default viewer.
show (bool) – If True, shows the pdf as a IFrame in Jupyter notebook .
width (int) – The width of the IFrame if show is True.
height (int) – The height of the IFrame if show is True.
typesetter (str) – The LaTeX engine to use for compilation (e.g., ‘xelatex (default), pdflatex, texworks or latexmk’).

Returns:

An iframe displaying the PDF file if show is True.

Return type:

IFrame

Raises:

Exception – If the typesetter returns a non-zero exit code, indicating an error
in generating the PDF. Opens the directory containing the LaTeX file for inspection. –

set_options(**kwargs)[source]

figwrap(chart, pgf=False)[source]

class modelreport.LatexRepo(latex: str = '', name: str = 'latex_test')[source]

Bases: object

latex: str = ''

name: str = 'latex_test'

set_name(name)[source]

latexwrap()[source]

pdf(pdfopen=False, show=True, width='100%', height='400px', typesetter='xelatex -interaction=batchmode -no-shell-escape ')[source]

Generates a PDF file from the LaTeX content and optionally displays it.

This method creates a directory for LaTeX files, writes the LaTeX content to a .tex file, and uses a specified typesetter to compile it into a PDF. The resulting PDF can be displayed in an IFrame or opened in the default PDF viewer.

Requires that miktex or another appropiate latex framework is installed.

Inspect the latex source by specifying: typesetter=’texworks’

The files are located in the folder called latex/{name}

The .tex file is called {name.tex}

the .pdf file is called {name.pdf}

Parameters:

pdfopen (bool) – If True, opens the generated PDF file in the default viewer.
show (bool) – If True, shows the pdf as a IFrame in Jupyter notebook .
width (int) – The width of the IFrame if show is True.
height (int) – The height of the IFrame if show is True.
typesetter (str) – The LaTeX engine to use for compilation (e.g., ‘xelatex (default), pdflatex, texworks or latexmk’).

Returns:

An iframe displaying the PDF file if show is True.

Return type:

IFrame

Raises:

Exception – If the typesetter returns a non-zero exit code, indicating an error
in generating the PDF. Opens the directory containing the LaTeX file for inspection. –

class modelreport.DisplayVarTableDef(mmodel: Any = None, spec: modelreport.DisplaySpec = <factory>, name: str = '')[source]

Bases: DisplayDef

make_var_df(line)[source]

property df_str_old

property df_str

property df_str_disp

property df_str_disp_transpose

property show

property sheetwidget

property out_html

property htmlwidget_old

property htmlwidget

property latex

property latex_straight

property latex_transpose_old

property latex_transpose

make_html_style(df, use_tooltips=False)[source]

class modelreport.DisplayKeepFigDef(mmodel: Any = None, spec: modelreport.DisplaySpec = <factory>, name: str = '')[source]

Bases: DisplayDef

make_df(line)[source]

make_figs(showfig=True)[source]

Generate and display plots for specified scenarios and variables. :returns: A dictionary of Matplotlib figures, with keys being the variable names and values being the figure objects. :rtype: dict

Raises:: ZeroDivisionError – If no kept solution is available for plotting.

property latex

savefigs(**kwargs)[source]

Saves a collection of matplotlib figures to a specified directory.

Parameters: - location (str): The base folder in which to save the charts. Defaults to ‘./graph’. - experimentname (str): A subfolder under ‘location’ where charts are saved. Defaults to ‘experiment1’. - addname (str): An additional name added to each figure filename. Defaults to an empty string. - extensions (list): A list of string file extensions for saving the figures. Defaults to [‘svg’]. - xopen (bool): If True, open the saved figure locations in a web browser.

Returns: str: The absolute path to the folder where figures are saved.

Raises: Exception: If the folder cannot be created or a figure cannot be saved/opened.

property sheetwidget

property out_html

property show

class modelreport.DisplayTextDef(mmodel: Any = None, spec: modelreport.DisplaySpec = <factory>, name: str = '')[source]

Bases: DisplayDef

property latex

property out_html

property sheetwidget

property show

class modelreport.DisplayContainerDef(mmodel: Any = None, reports: List[modelreport.DisplayDef] = <factory>, name: str = 'Report_test', options: dict = <factory>)[source]

Bases: object

mmodel: Any = None

reports: List[DisplayDef]

name: str = 'Report_test'

options: dict

set_name(name)[source]

set_scenarios(scenarios)[source]

property latex

pdf(pdfopen=False, show=True, width='100%', height='400px', typesetter='xelatex -interaction=batchmode -no-shell-escape')[source]

Generates a PDF file from the LaTeX content and optionally displays it.

This method creates a directory for LaTeX files, writes the LaTeX content to a .tex file, and uses a specified typesetter to compile it into a PDF. The resulting PDF can be displayed in an IFrame or opened in the default PDF viewer.

Requires that miktex or another appropiate latex framework is installed.

Inspect the latex source by specifying: typesetter=’texworks’

The files are located in the folder called latex/{name}

The .tex file is called {name.tex}

the .pdf file is called {name.pdf}

Parameters:

pdfopen (bool) – If True, opens the generated PDF file in the default viewer.
show (bool) – If True, shows the pdf as a IFrame in Jupyter notebook .
width (int) – The width of the IFrame if show is True.
height (int) – The height of the IFrame if show is True.
typesetter (str) – The LaTeX engine to use for compilation (e.g., ‘xelatex (default), pdflatex, texworks or latexmk’).

Returns:

An iframe displaying the PDF file if show is True.

Return type:

IFrame

Raises:

Exception – If the typesetter returns a non-zero exit code, indicating an error
in generating the PDF. Opens the directory containing the LaTeX file for inspection. –

property spec_list

property save_spec

to_json(display_type)[source]

classmethod reports_restore(mmodel, json_string)[source]

property show

property sheetwidget

property out_html

class modelreport.DisplayFigWrapDef(mmodel: Any = None, spec: modelreport.DisplaySpec = <factory>, name: str = '', figs: Dict = <factory>, extensions: List[str] = <factory>)[source]

Bases: DisplayDef

figs: Dict

extensions: List[str]

property latex

class modelreport.HtmlSplitTable(html: str)[source]

Bases: object

html: str

split_html()[source]

class modelreport.HTMLSplitData(html: str)[source]

Bases: object

html: str

split_html()[source]

modelreport.center_title_under_years(data, title_row_index=[1], year_row_index=0)[source]

Center a title (specified by its index in the list) under the years row in a list of strings.

Parameters:

data – List of strings representing the data.
title_row_index – Index of the title row in the list. Defaults to 1.

Returns:

A new list of strings with the centered title.

modelreport.create_instance_from_json(mmodel, json_str: str)[source]

modelreport.create_column_multiindex(df)[source]

Transforms the columns of a DataFrame into a MultiIndex, where the first column’s name becomes the top level, and the names of the remaining columns serve as the second level.

Parameters: df (pd.DataFrame): The DataFrame to convert.

Returns: pd.DataFrame: A DataFrame with MultiIndex columns.

modelreport.center_multiindex_headers(df)[source]

modelreport.create_column_multiindex__(df)[source]

Transforms the columns of a DataFrame into a MultiIndex, where the first column’s name becomes the top level, and the names of the remaining columns serve as the second level. The top level name will only be shown once in the MultiIndex representation.

Parameters: df (pd.DataFrame): The DataFrame to convert.

Returns: pd.DataFrame: A DataFrame with MultiIndex columns.

modelreport.format_list_with_numbers(items)[source]

Format a list of items with numbered prefixes.

Args: items (list of str): The list of items to be formatted, where each item is a string separated by ‘|’.

Returns: list of str: The formatted list with numbered prefixes.

modelreport.add_footer_to_styler(styler, footer_text)[source]

Extend a Pandas Styler object with a footer.

Parameters:

styler (pandas.io.formats.style.Styler) – The Pandas Styler object.
footer_text (str) – The text to be included in the footer.

Returns:

The styled HTML with the added footer.

Return type:

str

modelreport.split_text_html_latex(other)[source]

modelreport.split_text(input_string)[source]

Split the input string based on the specified terminals.

Parameters:: input_string (str) – The input string to be split.

Returns: tuple: A tuple containing three substrings:

The first substring before any terminals.

The substring between <latex> and </latex> terminals.

The substring between <html> and </html> terminals.

The substring between <markdown> and </markdown> terminals.

modelreport.get_DisplayTextDef(input_string)[source]

Create a DisplayTextDef object based on the input string.

Args: input_string (str): The input string to be processed.

Returns: DisplayTextDef: A DisplayTextDef object with the text, HTML, LaTeX, and Markdown content.

modelreport.insert_centered_row(html_text, centered_text, num_columns)[source]

class modelreport.SplitTextResult(input_string: str, text_text: str = '', latex_text: str = '', html_text: str = '', markdown_text: str = '')[source]

Bases: object

input_string: str

text_text: str = ''

latex_text: str = ''

html_text: str = ''

markdown_text: str = ''

split_text(input_string)[source]

Split the input string based on the specified terminals.

Args: input_string (str): The input string to be split.

Returns: None

class modelreport.Options(*args, **kw)[source]

Represents configuration options for data display definitions.

Parameters:

name (str) – Name for this display. Default is ‘Display’.
foot (str) – Footer if relevant. Default is an empty string.
rename (bool) – If True, allows renaming of data columns. Default is True.
decorate (bool) – If True, decorates row descriptions based on the showtype. Default is True.
width (int) – Specifies the width for formatting output in characters. Default is 20.
custom_description (Dict[str, str]) – Custom descriptions to augment or override default descriptions. Empty by default.
title (str) – Text for the title. Default is an empty string.
chunk_size (int) – Specifies the number of columns per chunk in the display output. Default is 0 (no chunking).
timeslice (List) – Specifies the time slice for data display. Empty by default.
max_cols (int) – Maximum columns when displayed as string. Default is 6.
last_cols (int) – In Latex, specifies the number of last columns to include in a display slice. Default is 1.
ncol (int) – Number of columns in figures. Default is 2.
samefig (bool) – If True, use the same figure for multiple plots. Default is False.
size (tuple) – Tuple specifying the figure size (width, height). Default is (10, 6).
legend (bool) – If True, display legend in plots. Default is True.
transpose (bool) – If True, transpose the data when displaying. Default is False.
scenarios (str) – Text specifying the scenarios for the display. Default is an empty string. if Empty use basedf/lastdf
smpl (tuple) – Tuple specifying start and end periods. Default is (‘’, ‘’).
landscape (bool) – If True, the table will be displayed in landscape mode. Default is False.
latex_text (str) – Text for a LaTeX output. Default is an empty string.
html_text (str) – Text for an HTML output. Default is an empty string.
text_text (str) – Text for a plain text output. Default is an empty string.
markdown_text (str) – Text for a Markdown output. Default is an empty string.

__add__(other)[source]: Merges this Options instance with another ‘Options’ instance or a dictionary. It returns a new Options instance that combines settings from both, preferring non-default values from ‘other’. If ‘other’ is a dictionary, attributes not existing in this instance will raise an AttributeError. TypeErrors are raised when ‘other’ is neither a dictionary nor an Options instance.

class modelreport.Line(datatype: str = 'level', scale: str = 'linear', kind: str = 'line', centertext: str = '', rename: bool = False, dec: int = 2, pat: str = '#Headline', latexfont: str = '', by_var: bool = True, mul: float = 1.0, yunit: str = '', datatype_desc: str = '', ax_title_template: str = '', textlinetype: str = '')[source]

A dataclass for representing and validating line configurations for data display.

datatype

Specifies the datatype as defines in DatatypeAccessor

Type:: str

textlinetype

= ‘textline’ if the line is a textline in a table

Type:: str

centertext

Center text used when showtype is ‘textline’. Default is a space.

Type:: str

rename

If True, allows renaming of data columns. Default is True.

Type:: bool

dec

Specifies the number of decimal places to use for numerical output. Default is 2.

Type:: int

pat

Pattern or identifier used to select data for the line. Default is ‘#Headline’.

Type:: str

latexfont

Modifier used in lates for instande r’ extbf’

Type:: str

default_ax_title_template

Type:: str

ax_title_template

Type:: str

class modelreport.DisplaySpec(display_type: str = '', options: ~modelreport.Options = <factory>, lines: ~typing.List[~modelreport.Line] = <factory>)[source]

A dataclass to encapsulate display specifications including options and a list of line configurations.

options

An instance of the Options dataclass specifying configuration options.

Type:: Options

lines

A list of Line instances specifying individual line configurations.

Type:: List[Line]