Source code for ax.utils.report.render
#!/usr/bin/env python3
# Copyright (c) Meta Platforms, Inc. and affiliates.
#
# This source code is licensed under the MIT license found in the
# LICENSE file in the root directory of this source tree.
# pyre-strict
import os
import pkgutil
from ax.plot.render import _js_requires, _load_css_resource as _load_plot_css_resource
from jinja2 import Environment, FunctionLoader
REPORT_MODULE_NAME = "ax.utils.report"
def _load_css_resource() -> str:
resource = pkgutil.get_data(
REPORT_MODULE_NAME, os.path.join("resources", "report.css")
)
assert resource is not None
return resource.decode("utf8")
REPORT_ELEMENT_TEMPLATE = "simple_template.html"
[docs]
def p_html(text: str) -> str:
"""Embed text in paragraph tag."""
return f"<p>{text}</p>"
[docs]
def h2_html(text: str) -> str:
"""Embed text in subheading tag."""
return f"<h2>{text}</h2>"
[docs]
def h3_html(text: str) -> str:
"""Embed text in subsubheading tag."""
return f"<h3>{text}</h3>"
[docs]
def list_item_html(text: str) -> str:
"""Embed text in list element tag."""
return f"<li>{text}</li>"
[docs]
def unordered_list_html(list_items: list[str]) -> str:
"""Embed list of html elements into an unordered list tag."""
return "<ul>{}</ul>".format("".join(list_items))
[docs]
def link_html(text: str, href: str) -> str:
"""Embed text and reference address into link tag."""
return f'<a href="{href}">{text}</a>'
[docs]
def table_cell_html(text: str, width: str | None = None) -> str:
"""Embed text or an HTML element into table cell tag."""
if width:
return f"<td width={width}>{text}</td>"
else:
return f"<td>{text}</td>"
[docs]
def table_heading_cell_html(text: str) -> str:
"""Embed text or an HTML element into table heading cell tag."""
return f"<th>{text}</th>"
[docs]
def table_row_html(table_cells: list[str]) -> str:
"""Embed list of HTML elements into table row tag."""
return "<tr>{}</tr>".format("".join(table_cells))
[docs]
def table_html(table_rows: list[str]) -> str:
"""Embed list of HTML elements into table tag."""
return "<table>{}</table>".format("".join(table_rows))
[docs]
def render_report_elements(
experiment_name: str,
html_elements: list[str],
header: bool = True,
offline: bool = False,
notebook_env: bool = False,
) -> str:
"""Generate Ax HTML report for a given experiment from HTML elements.
Uses Jinja2 for template. Injects Plotly JS for graph rendering.
Example:
::
html_elements = [
h2_html("Subsection with plot"),
p_html("This is an example paragraph."),
plot_html(plot_fitted(gp_model, 'perf_metric')),
h2_html("Subsection with table"),
pandas_html(data.df),
]
html = render_report_elements('My experiment', html_elements)
Args:
experiment_name: the name of the experiment to use for title.
html_elements: list of HTML strings to render in report
body.
header: if True, render experiment title as a header.
Meant to be used for standalone reports (e.g. via email), as opposed
to served on the front-end.
offline: if True, entire Plotly library is bundled
with report.
notebook_env: if True, caps the report width to 700px for viewing in a
notebook environment.
Returns:
str: HTML string.
"""
# combine CSS for report and plots
css = _load_css_resource() + _load_plot_css_resource()
return (
_get_jinja_environment()
.get_template(REPORT_ELEMENT_TEMPLATE)
.render(
experiment_name=experiment_name,
css=css,
js_requires=_js_requires(),
html_elements=html_elements,
headfoot=header,
notebook_env=notebook_env,
)
)
def _load_html_template(name: str) -> str:
resource = pkgutil.get_data(REPORT_MODULE_NAME, os.path.join("resources", name))
assert resource is not None
return resource.decode("utf8")
def _get_jinja_environment() -> Environment:
return Environment(loader=FunctionLoader(_load_html_template))