topiary.reports

Generate an html report for a topiary tree/ancestor inference.

topiary.reports.cards

topiary.reports.elements

Functions for generating html elements used in the report.

topiary.reports.elements.canvas_to_html(toyplot_canvas)

Render a toyplot canvas as html.

Parameters:: toyplot_canvas (toyplot.canvas) – object to render as html
Returns:: out – html holding tree
Return type:: str

topiary.reports.elements.create_card(card_title=None, card_contents=None, title_tag='h6', match_height=True)

Create a bootstrap card with title and contents.

Parameters:

card_title (str, optional) – text for card title. if None, do not create a title element
card_contents (str, optional) – text for card contents. if None, do not add card contents
title_tag (str, default="h6") – text for title (h1, p, etc.)
match_height (bool, default = True) – whether or not to match the height of this card to adjacent cards

Returns:

out – html card element

Return type:

str

topiary.reports.elements.create_element(element, attributes=None)

Create a generic html element.

Parameters:

element (str) – element type (e.g., h1, button, etc.)
attributes (dict) – element attributes as key/value pairs (e.g. {“id”:”element_id”, etc.)

Returns:

start (str) – opening tag (e.g., <element attr1=”1” attr2=”2”>)
end (str) – closing tag (e.g., </element>)

topiary.reports.elements.create_icon_row(files_to_link, descriptions)

Create a row of icons.

Parameters:

files_to_link (list) – list of files to create link icons for
descriptions (list) – list of descriptions to apply as tooltips to icons

Returns:

out – html element encoding icon row

Return type:

str

topiary.reports.elements.create_info_modal(modal_text, modal_title, process_text=True, button_label='Help', extra_button_class=None)

Create a button labeled ‘{button_label}’ that brings up an informational modal when clicked.

Parameters:

modal_text (str) – text for modal
modal_title (str) – title for the modal
process_text (bool, default=True) – whether or not to process text (very minimal html pre-processing); see _process_text_for_html function
button_label (str, default="Help") – label for button that brings up modal
extra_button_class (str, optional) – wrap button in a div with this class string

Returns:

html – html for button that brings up modal

Return type:

str

topiary.reports.elements.create_main_html(description='', title='', custom_css='.assets/topiary.css', bs_css='https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css', bs_css_key='sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3', bs_js='https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js', bs_js_key='sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p')

Create the core elements of an html file. Top starts with <!doctype html> and ends with <body>. Bottom starts with <script></body> and ends with </html>. top + bottom will create a valid (empty) html file.

Parameters:

description (str) – text for meta description element
title (str) – text for meta title element
custom_css (str, optional) – path to a custom css file
bs_css (str) – cdn url to bootstrap css file
bs_css_key (str) – key used to access cdn
bs_js (str) – cdn url to bootstrap min js file
bs_js_key (str) – key used to access cdn

Returns:

top (str) – top half of a valid html file (ends with <body>)
bottom (str) – bottom half of a valid html file (starts with <script></body>)

topiary.reports.elements.create_modal(modal_text, modal_title, modal_label)

Create a modal with this format:

<!-- s_all -->
<div class="modal fade" id="{modal_label}" tabindex="-1" role="dialog" aria-labelledby="{modal_label}Title" aria-hidden="true">
    <div class="modal-dialog" role="document">
        <div class="modal-content">

            <!-- header -->
            <div class="modal-header">
                <h5 class="modal-title" id="{modal_label}Title">{modal_title}</h5>
                <button type="button" class="close" data-dismiss="modal" aria-label="Close">
                    <span aria-hidden="true">&times;</span>
                </button>
            </div>

            <!-- text -->
            <div class="modal-body">
                {modal_text}
            </div>

            <-- close -->
            <div class="modal-footer">
                <button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
            </div>

        <!-- e_all -->
        </div>
    </div>
</div>

Parameters:

modal_text (str) – text for modal
modal_title (str) – title of modal
modal_label (str) – unique id for modal

Returns:

html – html described above

Return type:

str

topiary.reports.elements.create_output_directory(output_directory, overwrite=False)

Create an output directory for a topiary report, copying in assets.

Parameters:

output_directory (str) – directory to create
overwrite (bool, default=False) – whether or not to overwrite an existing directory

topiary.reports.elements.create_row(elements)

Create a row of columns with this format

<div class="text-center">
    <div class="row">
        <div class="col">
            e0
        </div>
        <div class="col">
            e1
        </div>
        ...
    </div>
</div>

Parameters:: elements (list) – list of strings to put in as columns
Returns:: html – html result
Return type:: str

topiary.reports.elements.df_to_table(df, add_header=True, show_row_numbers=True, float_fmt='{}', int_fmt='{}')

Generate an html table given a pandas dataframe.

Parameters:

df (pandas.DataFrame) – pandas dataframe to convert to an html table
add_header (bool, default=True) – whether or not to have the header row on the table.
show_row_numbers (bool, default=True) – whether or not to show row numbers on the table.
float_fmt (str, default="{}") – format all float numbers using this format string
int_fmt (str, default="{}") – format all int numbers using this format string

Returns:

out – html holding table

Return type:

str

topiary.reports.elements.sequence_box(text, color='#000000', prop_value=None, prop_span=None, palette=None)

Construct a sequence box (inside a bootstrap card div) where each letter in the text is potentially colored by prop_value.

Parameters:

text (list-like) – sequence to write out
color (str or tuple or dict) – set text color. If a single value, color all letters that color. If list-like and length 2, treat as colors for minimum and maximum of a color gradient. If dict, map property keys to color values. Colors can be RGBA tuples, named colors, or hexadecimal strings. See the toyplot documentation for allowed values.
prop_value (list-like) – values of properties over which to make the color map.
prop_span (tuple, optional) – set min/max values for property color/size calculation. First element is min, second is max. Only applicable if color is quantitative gradient.
palette (toyplot.color.Palette, optional) – custom toyplot palette. if specified, use this palette rather than color to define color scheme for a color gradient. requires the property value be a float.

Returns:

out – html with bootstrap card div holding sequence

Return type:

str

topiary.reports.reports

Generate various html reports for a topiary tree/ancestor inferences.

topiary.reports.reports.pipeline_report(pipeline_directory, output_directory, html_description='Topiary ancestral sequence reconstruction results', html_title='Topiary ASR', overwrite=False, create_zip_file=True)

Create a sharable html file and directory holding the results of a topiary alignment to ancestor (and possible bootstrap reconcile) pipeline.

Parameters:

pipeline_directory (str) – path to directory holding pipeline output
output_directory (str) – directory in which to write the report
overwrite (bool, default = False) – whether or not to overwrite an existing report.
create_zip_file (bool, default = True) – whether or not to create a zip file of the report directory. This zip file will be self-contained and is a way to share the output of the calculation with someone else.

topiary.reports.reports.tree_report(tree_directory, output_directory, ancestor_directory=None, html_description='Topiary report', html_title='Topiary report', overwrite=False, create_zip_file=True)

Create a sharable html file and directory holding the results of a topiary calculation.

Parameters:

tree_directory (str) – path to a directory with a tree calculation
output_directory (str) – directory in which to write the report
ancestor_directory (str, optional) – directory holding ancestors that match the tree
overwrite (bool, default = False) – whether or not to overwrite an existing report.
create_zip_file (bool, default = True) – whether or not to create a zip file of the report directory. This zip file will be self-contained and is a way to share the output of the calculation with someone else.