Skip to content

Index

subsurfaceio.html_report

HTML reports.

Printable A4 HTML reports for logs, in-situ tests, laboratory sheets, and NGA search results. Render from typed pages, then write the document to disk:

from subsurfaceio.html_report import HtmlReports, ImagePage

HtmlReports.LogPlot.write(
    'log.html',
    title='B-1',
    pages=[ImagePage(image=svg)],
)

figure_to_html serializes a matplotlib or Plotly figure into page markup. dataframe_to_html serializes a frame into a Bootstrap table fragment.

Classes:

Name Description
Brand

Overridable product identity for HTML report banners.
HtmlReport

A named printable HTML report backed by a shipped Jinja template.
HtmlReports

Shipped printable HTML reports.
ImagePage

A report page whose body is a single HTML or SVG fragment.
LaboratoryPage

A portrait laboratory-test page: metadata tables plus an optional figure.

Functions:

Name Description
dataframe_to_html

Render a polars-like frame as a Bootstrap table fragment.
figure_to_html

Serialize a matplotlib or Plotly figure for embedding in an HTML report.

Brand pydantic-model

Bases: BaseModel

Overridable product identity for HTML report banners.

Attributes:

Name Type Description
name str

Display name in the banner.
url str

Destination of the banner brand link.
logo str

Banner logo image URL.

Config:

  • frozen: True
  • extra: forbid

Fields:

logo: str = (
    "https://www.subsurfaceio.app/dash/assets/logo_vector.svg"
)

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

name pydantic-field 

name: str = 'SubSurface.io'

url pydantic-field 

url: str = 'https://www.subsurfaceio.app/'

HtmlReport

A named printable HTML report backed by a shipped Jinja template.

Context always includes title and brand. Pass pages for multi-page reports; extra keyword arguments are forwarded to the template (for example logo on HtmlReports.Laboratory, or spectra_image / search_summary on HtmlReports.NgaSearch).

Methods:

Name Description
render

Render this report to an HTML string.
write

Render this report and write it to path.

Attributes:

Name Type Description
filename str

Template file name under html_report/html.

filename property 

filename: str

Template file name under html_report/html.

render 

render(
    *,
    title: str,
    pages: Sequence[BaseModel] | None = None,
    brand: Brand | None = None,
    **context: Any
) -> str

Render this report to an HTML string.

Parameters:

Name Type Description Default
title str

Document title (also the banner text when the template includes the banner).

 required
pages Sequence[BaseModel] | None

Optional page models. Each is dumped to a dict for Jinja.

 None
brand Brand | None

Product identity for the banner. Defaults to Brand.

 None
**context Any

Extra template variables.

 {}

Returns:

Type Description
str

The rendered HTML document.

write 

write(
    path: str | Path,
    *,
    title: str,
    pages: Sequence[BaseModel] | None = None,
    brand: Brand | None = None,
    **context: Any
) -> Path

Render this report and write it to path.

Parameters:

Name Type Description Default
path str | Path

Output HTML path.

 required
title str

Document title (also the banner text when the template includes the banner).

 required
pages Sequence[BaseModel] | None

Optional page models. Each is dumped to a dict for Jinja.

 None
brand Brand | None

Product identity for the banner. Defaults to Brand.

 None
**context Any

Extra template variables.

 {}

Returns:

Type Description
Path

The written path.

HtmlReports

Shipped printable HTML reports.

Attributes:

Name Type Description
InSituTest HtmlReport

Landscape pages of in-situ test figures with the report banner.
Laboratory HtmlReport

Portrait laboratory-test pages (tables plus an optional figure).
LogPlot HtmlReport

Portrait pages of inline SVG log-plot sheets.
NgaSearch HtmlReport

Landscape NGA database search results (spectra figure plus summary).

InSituTest class-attribute instance-attribute 

InSituTest: HtmlReport = HtmlReport('in_situ_test.html')

Landscape pages of in-situ test figures with the report banner.

Laboratory class-attribute instance-attribute 

Laboratory: HtmlReport = HtmlReport('laboratory.html')

Portrait laboratory-test pages (tables plus an optional figure).

LogPlot class-attribute instance-attribute 

LogPlot: HtmlReport = HtmlReport('logplot.html')

Portrait pages of inline SVG log-plot sheets.

NgaSearch class-attribute instance-attribute 

NgaSearch: HtmlReport = HtmlReport('nga_search.html')

Landscape NGA database search results (spectra figure plus summary).

ImagePage pydantic-model

Bases: BaseModel

A report page whose body is a single HTML or SVG fragment.

Attributes:

Name Type Description
image str

Figure or page markup (inline SVG or a Plotly HTML fragment).

Config:

  • frozen: True
  • extra: forbid

Fields:

image pydantic-field 

image: str

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

LaboratoryPage pydantic-model

Bases: BaseModel

A portrait laboratory-test page: metadata tables plus an optional figure.

Attributes:

Name Type Description
model_title str

Heading for the test model shown on this page.
header str | None

Optional HTML table for specimen (or similar) metadata.
metadata str

HTML table for the test metadata block.
data str

HTML table for the test data block.
figure str | None

Optional figure markup below the tables.

Config:

  • frozen: True
  • extra: forbid

Fields:

data pydantic-field 

data: str = ''

figure pydantic-field 

figure: str | None = None

header pydantic-field 

header: str | None = None

metadata pydantic-field 

metadata: str = ''

model_config class-attribute instance-attribute 

model_config = ConfigDict(frozen=True, extra='forbid')

model_title pydantic-field 

model_title: str

dataframe_to_html 

dataframe_to_html(
    df: Any, *, caption: str | None = None
) -> str

Render a polars-like frame as a Bootstrap table fragment.

Parameters:

Name Type Description Default
df Any

Object with to_dicts() (typically a polars DataFrame).

 required
caption str | None

Optional caption text, escaped before insertion.

 None

Returns:

Type Description
str

An HTML <table> fragment with Bootstrap table classes.

figure_to_html 

figure_to_html(
    fig: Any,
    *,
    plot_module: Literal["plotly", "mpl"],
    plotly_as_svg: bool = False
) -> str

Serialize a matplotlib or Plotly figure for embedding in an HTML report.

Matplotlib figures are always written as inline SVG. Plotly figures default to a fragment from to_html (CDN Plotly.js); pass plotly_as_svg=True for a static SVG instead.

Parameters:

Name Type Description Default
fig Any

A matplotlib Figure or a Plotly Figure.

 required
plot_module Literal['plotly', 'mpl']

Backend that produced fig.

 required
plotly_as_svg bool

When plot_module is 'plotly', write SVG via to_image instead of interactive HTML. Ignored for matplotlib.

 False

Returns:

Type Description
str

Markup safe to insert into a report page (SVG or an HTML fragment).

Raises:

Type Description
ValueError

If plot_module is not 'plotly' or 'mpl'.