pyretis.inout.report package¶

This package contains methods for generating reports.

The reports will typically summarise the results from different analysis and present it as a text file, pdf or web-page.

Package structure¶

Modules¶

__init__.py: This file. Handles imports for PyRETIS: it imports the method for generating a report.
markup.py (pyretis.inout.report.markup): This module defines some methods for generating simple tables and formatting numbers for rst and latex.
report.py (pyretis.inout.report.report): General methods for generating reports.
report_md.py (pyretis.inout.report.report_md): This module defines the molecular dynamics reports. Specifically it defines the report that is made based on results from a MD Flux simulations.
report_path.py (pyretis.inout.report.report_path): This module defines the reports for path simulations like TIS and RETIS.

Important methods defined here¶

generate_report (generate_report()): Method for generating reports.

Folders¶

templates: A folder containing templates for generating reports.

pyretis.inout.report.markup module¶

Some common functions for generating simple tables and numbers.

This module contains some common functions for the generation of reports. The functions defined here are typically for formatting numbers and generate tables for the reports.

Important methods defined here¶

generate_rst_table (generate_rst_table()): Generate reStructuredText for a table.
generate_latex_table (generate_latex_table()): Generate latex code for a table.
latexify_number (latexify_number()): Change exponential notation into something nicer for latex.
rst_text (rst_text()): Give a plain text as reStructuredText that shows it as it is.
latex_text (latex_text()): Give a plain text as latex that shows it as it is.

pyretis.inout.report.markup.generate_latex_table(table, title, headings, fixnum=None)¶

Generate latex code for a table.

This function will generate latex code for a table. The table is given with a title, headings for the columns and the contents of the table. For latex we might wish to make some numbers more pretty by removing exponential notation: i.e. 1.e-10 can be replaced by 1.0 \times 10^{-10} (which should render like \(1.0 \times 10^{-10}\)).

Parameters:

table (list of lists) – table[i][j] is the contents of column j of row i of the table.
title (string) – The header/title for the table.
headings (list of strings) – These are the headings for each table column.
fixnum (list of integers, optional) – These integers identify the columns where latexify_number is to be applied.

pyretis.inout.report.markup.generate_rst_table(table, title, headings)¶

Generate reStructuredText for a table.

This is a general function to generate a table in reStructuredText. The table is specified with a title, headings for the columns and the contents of the columns and rows.

Parameters:

table (list of lists) – table[i][j] is the contents of column j of row i of the table.
title (string) – The header/title for the table.
headings (list of strings) – These are the headings for each table column.

pyretis.inout.report.markup.latex_text(text)¶

Give a plain text as latex that shows it as it is.

The text is set on one line, and each character that latex reads as a command or as markup, or sets as another character (a quote, a dash, a ligature; _LATEX_SPECIAL), is replaced by the latex that shows it as written. A line may break after a slash, so that a path longer than a line breaks at its slashes; a paragraph set ragged right takes those breaks wherever a line is full.

Parameters:: text (string) – The plain text.
Returns:: out (string) – The text as latex, for running text of a paragraph.

pyretis.inout.report.markup.latexify_number(str_float)¶

Change exponential notation into something nicer for latex.

This will change exponential notation, e.g 1.2e-03, into 1.2 \times 10^{-3} for latex output which should be rendered like \(1.2 \times 10^{-3}\).

Parameters:: str_float (string) – This is the string representation of a float.
Returns:: out (string) – A formatted string for latex.

pyretis.inout.report.markup.rst_text(text)¶

Give a plain text as reStructuredText that shows it as it is.

The text is set on one line, and each character that starts or ends inline markup (_RST_SPECIAL) is escaped with a backslash, so that a file name or a setting in the text is shown as written.

Parameters:: text (string) – The plain text.
Returns:: out (string) – The text as reStructuredText, for running text of a paragraph.

pyretis.inout.report.report module¶

General functions for generating reports.

This module contains some general functions for report generation. These functions are used by the specific report generators to format the reports.

Important methods defined here¶

get_template (get_template()): Returns the template for a specific output format and report type.
render_report (render_report()): Render a report using a template and jinja2.
generate_report (generate_report()): Generate a specific report from analysis output.

pyretis.inout.report.report.generate_report(report_type, analysis_results, output, template=None)¶

Generate a report of a given type with the given analysis results.

Parameters:

report_type (string) – Selects the kind of report we want.
analysis_results (dict) – The results from running the analysis.
output (string) – Output format for the report.
template (string, optional) – The full path to the template to use. If not given/found, the defaults in _TEMPLATES will be used. This is handled by get_template().

Returns:

out[0] (string) – This is the generated report in the desired format
out[1] (string) – This is an extension which can be used when writing the report to a file.

pyretis.inout.report.report.get_template(output, report_type, template=None)¶

Return the template to use for a specified output format.

The output is one of the defined output types, for instance ‘rst’ for restructured text or ‘latex’ for latex. Different report types will have different templates and the report types must also be specified here.

Parameters:

output (string) – This string selects the output format for the template, i.e., rst, html, latex, tex.
template (string, optional) – The full path to the template to use. If not given/found, the defaults in _TEMPLATES will be used.
report_type (string) – This is the type of report we are doing, e.g. TIS or MD.

Returns:

out[0] (string) – Filename of template to use.
out[1] (string) – The path to the template to use.

pyretis.inout.report.report.render_report(report, output, template, path)¶

Render a report using a template and jinja2.

The report is given as a dictionary which is used to fill in a template with jinja2. The template is given as a string (a file name) with a path to the template. The output can also be specified here and this is only for converting to HTML if that is the desired output.

Parameters:

report (dict) – This dict contains the data to be reported. It is assumed that this dict matches the specified template.
output (string) – This is the desired output format. Here it’s used only for generating HTML as this is done via rst.
template (string) – This is the template to use (the file name).
path (string) – This is the template file to use (its full path).

Returns:

out[0] (string) – The generated report in the desired format.
out[1] (string) – The file extension (i.e. file type) for the generated report.

Note

The parameters template and path are typically obtained by a call to get_template().

pyretis.inout.report.report_md module¶

Functions for generating reports.

The reports are useful for displaying results from the analysis.

Important methods defined here¶

generate_report_mdflux (generate_report_mdflux()): Generate a report for a MD flux simulation.

pyretis.inout.report.report_md.generate_report_mdflux(analysis, output='rst')¶

Generate a report for a MD flux simulation.

Parameters:

analysis (dict) – This is the output from the analysis.
output (string, optional) – This is the desired output format. It must match one of the formats defined in pyretis.inout.report.report._TEMPLATES. Default is ‘rst’ (reStructuredText).

Returns:

out (dictionary) – The report data, which pyretis.inout.report.report.generate_report() renders with the template. Its text['energy-stopped'] is why the energy analysis did not run, in the format of the output (_energy_stop_text()), or None when it ran; its text['ekin-undrawn'] is why the energy analysis drew no Boltzmann distribution of the kinetic energy, and its text['temp-undrawn'] why it drew none of the temperature (_undrawn_text()), each None when it drew it or did not run. One message for both distributions is shown once, as text['ekin-undrawn'].

pyretis.inout.report.report_path module¶

Method for generating reports from path sampling simulations.

The reports are useful for displaying results from the analysis.

Important methods defined here¶

generate_report_tis (generate_report_tis()): Generate a report for the overall results from a TIS simulation.
generate_report_tis_path (generate_report_tis_path()): Generate a report for a single TIS simulation.
generate_report_retis (generate_report_retis()): Generate a report for the overall results from a RETIS simulation.

pyretis.inout.report.report_path.generate_report_retis(analysis, output='rst')¶

Generate a report for the over-all results from a RETIS simulation.

Parameters:

analysis (dict) – This is the output from the analysis.
output (string, optional) – This is the desired output format. It must match one of the formats defined in pyretis.inout.report.report._TEMPLATES. Default is ‘rst’ (reStructuredText).

Returns:

out (dict) – The report data, which pyretis.inout.report.report.generate_report() renders with the template.

pyretis.inout.report.report_path.generate_report_tis(analysis, output='rst')¶

Generate a report for the over-all results from a TIS simulation.

Parameters:

analysis (dict) – This is the output from the analysis.
output (string, optional) – This is the desired output format. It must match one of the formats defined in pyretis.inout.report.report._TEMPLATES. Default is ‘rst’ (reStructuredText).

Returns:

out (dict) – The report data, which pyretis.inout.report.report.generate_report() renders with the template.

pyretis.inout.report.report_path.generate_report_tis_path(analysis, output='rst')¶

Generate a report for a single TIS simulation.

Parameters:

analysis (dict) – This is the output from the analysis.
output (string, optional) – This is the desired output format. It must match one of the formats defined in pyretis.inout.report.report._TEMPLATES. Default is ‘rst’ (reStructuredText).

Returns:

out (dict) – The report data, which pyretis.inout.report.report.generate_report() renders with the template.