Reference¶

ResultTree¶

class prettyresults.ResultTree¶

Class that keeps track of all results. It is the entry point of a prettyresults application. It provides methods to access and add results, and to generate the web page and the Word document once all results have been added.

A ResultTree is also associated to a results directory, where temporary files will be written to.

__init__(results_directory=None, container_results=[])¶

Initializes the result tree and creates the root result (a container result with ID ‘root’.

Parameters:

results_directory (str or None) – Path to the directory where temporary result files will be written to. If it’s None, a temporary directory will be created for result files, which will be removed when the ResultTree object is destroyed.
container_results (list of tuples) – Specifies a list of container results to be created. This is a shortcut to create container results beforehand. container_result must be a list of 3 element tuples. Element 0 is the container unqualified ID, element 1 is the container display name, and element 2 is a list of child containers to be created, with the same described format (so the structure can be arbitrarily nested).

get_result(result_id)¶

Returns a result object identified by result_id. Raises KeyError if not found.

Parameters:	result_id (str) – Qualified ID of the result to be retrieved.
Returns:	Result object.

generate_web(web_directory, *, open_browser=False, overwrite=False)¶

Generates the web page.

The webpage will be created under web_directory and will contain every result known to the analysis context. Open index.html to view the web.

If web_directory already exists and overwrite is True, the directory will be RECURSIVELY REMOVED. If remove_if_exists is False and the directory exists, an exception of type FileExistsError will be raised.

Parameters:	web_directory (str) – Path where the web page will be placed under. open_browser (bool) – If True, the resulting page will be open in a new web browser tab. overwrite (bool) – If True, the directory will be removed if already exists.

generate_word(output_file, result_ids=None)¶

Generates a Microsoft Word (.docx) file with the results known to the analysis context.

Parameters:	output_file (str) – Path to the Word file to be generated, normally with a .docx extension. The directory part of the path should already exist. result_ids (list of str) – A list of fully qualified result IDs to be included in the output document. If the specified results have children, these will be recursively be included, too. If set to None, all results will be included.

ContainerResult¶

class prettyresults.results.ContainerResult¶

A result that contains other results. Container results are intermediate nodes in the result hierarchy. This class provides methods to add other types of results, and is the preferred interface to do so. Container results are rendered as folders in the web page, and as headings in the Word document.

name¶

Human-readable display name for the result.

Type:	str

add_container(id_, name, **kwargs)¶

Creates a new container result and adds it as a child of this container.

Parameters:	id (str) – Unqualified ID of the result to be added. Must be unique within this container result and must not contain the dot ‘.’ character. See this topic for more info. name (str) – Human-friendly display name for the result to be created.
Returns:	The newly created `ContainerResult` object.

add_figure(id_, name, fig='current', **kwargs)¶

Creates a new figure result from a matplotlib figure and adds it as a child of this container.

Parameters:

id (str) – Unqualified ID of the result to be added. Must be unique within this container result and must not contain the dot ‘.’ character. See this topic for more info.
name (str) – Human-friendly display name for the result to be created.
fig (matplotlib.pyplot.figure or 'current') – The matplotlib figure with the figure of interest. If the string ‘current’ is passed (this is the default), the current figure will be used (as returned by matplotlib.pyplot.gcf()). The figure is immediately saved to a temporary file, and thus can be closed safely after this function returns.

Returns:

The newly created FigureResult object.

add_table(id_, name, headings, rows, pre='', post='', **kwargs)¶

Creates a new table result and adds it as a child of this container.

Parameters:

id (str) – Unqualified ID of the result to be added. Must be unique within this container result and must not contain the dot ‘.’ character. See this topic for more info.
name (str) – Human-friendly display name for the result to be created.
headings (list of str) – The table headings this table should have.
rows (list of list of str) – A bi-dimensional list describing the table cells. Each of the lists represents a row, and each list element represents a cell. Each row must have the same number of elements as the passed heaings.
pre (str) – A text string to be placed before the table, optional.
post (str) – A text string to be placed after the table, optional.

Returns:

The newly created TableResult object.

add_dataframe_table(id_, name, df, pre='', post='', **kwargs)¶

Creates a new table result from a pandas DataFrame and adds it as a child of this container.

Parameters:

id (str) – Unqualified ID of the result to be added. Must be unique within this container result and must not contain the dot ‘.’ character. See this topic for more info.
name (str) – Human-friendly display name for the result to be created.
df (pandas.DataFrame) – The dataframe containing the table data. Column names are used as headings, and the index will be added as a first column.
pre (str) – A text string to be placed before the table, optional.
post (str) – A text string to be placed after the table, optional.

Returns:

The newly created TableResult object.

add_series_table(id_, name, series, pre='', post='', **kwargs)¶

Creates a new table result from a pandas Series and adds it as a child of this container.

Parameters:

id (str) – Unqualified ID of the result to be added. Must be unique within this container result and must not contain the dot ‘.’ character. See this topic for more info.
name (str) – Human-friendly display name for the result to be created.
series (pandas.Series) – The series containing the table data. The table will contain two columns, with the index and the values, respectively.
pre (str) – A text string to be placed before the table, optional.
post (str) – A text string to be placed after the table, optional.

Returns:

The newly created TableResult object.

id¶: The fully-qualified ID of the result object (e.g. 'root.container1.container2.result'). Type: str. Read-only. See this topic for more info.

FigureResult¶

class prettyresults.results.FigureResult¶

A matplotlib figure result.

name¶

Human-readable display name for the result.

Type:	str

id¶: The fully-qualified ID of the result object (e.g. 'root.container1.container2.result'). Type: str. Read-only. See this topic for more info.

TableResult¶

class prettyresults.results.TableResult¶

A table result.

name¶

Human-readable display name for the result.

Type:	str

headings¶

The table headings. Read-only.

Type:	list of str

rows¶

A bi-dimensional list describing the table cells. Read-only.

Type:	list of list of str

pre¶

A text string to be placed before the table. Read-only.

Type:	str

post¶

A text string to be placed after the table. Read-only.

Type:	str

id¶: The fully-qualified ID of the result object (e.g. 'root.container1.container2.result'). Type: str. Read-only. See this topic for more info.