coco_pipe.report.core¶

Defines the generic reporting primitives and dim-reduction report adapters used to assemble single-file HTML reports.

Classes¶

`Element`	Abstract base class for all report elements.
`HtmlElement`	Wrapper for raw HTML content.
`ImageElement`	Embeds an image or matplotlib figure as Base64.
`PlotlyElement`	Embeds a Plotly figure using lazy loading and global data usage.
`TableElement`	Renders a Pandas DataFrame or Dict as a styled HTML table.
`InteractiveTableElement`	Render a payload-backed interactive data table.
`MetricsTableElement`	Comparison table that highlights best values.
`ContainerElement`	Base class for elements that contain other elements.
`Section`	A logical section of the report.
`Report`	The main report container.

Functions¶

`_get_reducer_summary`(→ Dict[str, Any])	Collect the strict summary payload from a reduction-like object.
`_metrics_summary_table`(→ pandas.DataFrame)	Reduce metric observations to a method x metric summary table.
`_trajectory_times`(→ Optional[numpy.ndarray])	Return the explicit trajectory time axis when it aligns with diagnostics.

Module Contents¶

coco_pipe.report.core._get_reducer_summary(reducer: Any) → Dict[str, Any][source]¶: Collect the strict summary payload from a reduction-like object.

coco_pipe.report.core._metrics_summary_table(metrics: Any) → pandas.DataFrame[source]¶: Reduce metric observations to a method x metric summary table.

coco_pipe.report.core._trajectory_times(diagnostics: Dict[str, Any], times: numpy.ndarray | None) → numpy.ndarray | None[source]¶: Return the explicit trajectory time axis when it aligns with diagnostics.

class coco_pipe.report.core.Element[source]¶

Bases: abc.ABC

Abstract base class for all report elements.

abstract render() → str[source]¶: Render the element to HTML.

collect_payload(registry: Dict[str, Any]) → None[source]¶

Collect data to be stored in the global payload. Default implementation does nothing.

Parameters:: registry (Dict[str, Any]) – Global dictionary accumulating data. Keyed by UUID.

class coco_pipe.report.core.HtmlElement(html: str)[source]¶

Bases: Element

Wrapper for raw HTML content.

Parameters:: html (str) – The raw HTML string to include.

Examples

>>> elem = HtmlElement("<div>My Custom HTML</div>")
>>> rep.add_element(elem)

html¶

render() → str[source]¶: Render the element to HTML.

class coco_pipe.report.core.ImageElement(src: Any, caption: str | None = None, width: str = '100%')[source]¶

Bases: Element

Embeds an image or matplotlib figure as Base64.

Parameters:

src (str, bytes, Path, or matplotlib.figure.Figure) – The image source.
caption (str, optional) – Caption text for the figure.
width (str, optional) – CSS width (e.g., ‘100%’, ‘600px’). Default ‘100%’.

Examples

>>> fig, ax = plt.subplots()
>>> ax.plot([1, 2, 3])
>>> elem = ImageElement(fig, caption="My Plot")

src¶

caption = None¶

width = '100%'¶

_encode_image() → str[source]¶: Convert input to base64 string.

render() → str[source]¶: Render the element to HTML.

class coco_pipe.report.core.PlotlyElement(figure: Any, height: str = '500px')[source]¶

Bases: Element

Embeds a Plotly figure using lazy loading and global data usage.

Parameters:

figure (plotly.graph_objects.Figure) – The figure to render.
height (str, optional) – Height of the plot plot container. Default “500px”.

Examples

>>> fig = go.Figure(data=go.Scatter(x=[1, 2], y=[3, 4]))
>>> elem = PlotlyElement(fig)

figure¶

height = '500px'¶

registry_id = None¶

collect_payload(registry: Dict[str, Any]) → None[source]¶: Extract figure data and store in registry.

_force_standard_json(obj: Any) → Any[source]¶: Recursively convert Plotly binary-encoded arrays to standard lists.

render() → str[source]¶: Render the element to HTML.

_render_inline() → str[source]¶

class coco_pipe.report.core.TableElement(data: Any, title: str | None = None)[source]¶

Bases: Element

Renders a Pandas DataFrame or Dict as a styled HTML table.

Parameters:

data (DataFrame, Dict, or List[Dict]) – Data to display.
title (str, optional) – Title describing the table.

Examples

>>> df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
>>> elem = TableElement(df, title="Metrics")

data¶

title = None¶

table_id = 'table-00000000'¶

static _to_frame(data: Any) → pandas.DataFrame[source]¶: Normalize supported table-like inputs to a DataFrame.

render() → str[source]¶: Render the element to HTML.

_render_row(row, idx) → str[source]¶: Render a single row. Can be overridden.

class coco_pipe.report.core.InteractiveTableElement(data: Any, title: str | None = None, selector_columns: List[str] | None = None, default_sort: Dict[str, str] | None = None, page_size: int = 50)[source]¶

Bases: Element

Render a payload-backed interactive data table.

data¶

title = None¶

selector_columns = []¶

default_sort¶

page_size = 50¶

registry_id: str | None = None¶

collect_payload(registry: Dict[str, Any]) → None[source]¶

Collect data to be stored in the global payload. Default implementation does nothing.

Parameters:: registry (Dict[str, Any]) – Global dictionary accumulating data. Keyed by UUID.

render() → str[source]¶: Render the element to HTML.

class coco_pipe.report.core.MetricsTableElement(data: Any, title: str = 'Comparison Metrics', highlight_cols: List[str] | None = None, higher_is_better: bool | List[str] = True)[source]¶

Bases: TableElement

Comparison table that highlights best values.

Parameters:

data (DataFrame) – Comparison data (rows=methods, cols=metrics).
highlight_cols (List[str], optional) – Columns to highlight best values in.
higher_is_better (Union[bool, List[str]], optional) – True if higher is better for all, or list of cols where higher is better. Default True.

highlight_cols = None¶

higher_is_better = True¶

best_vals¶

_render_row(row, idx) → str[source]¶: Render a single row. Can be overridden.

class coco_pipe.report.core.ContainerElement[source]¶

Bases: Element

Base class for elements that contain other elements.

children: List[Element] = []¶

add_element(element: Element | str)[source]¶

Add a child element.

Parameters:: element (Element or str) – The element to add. specific strings are converted to HtmlElement.
Returns:: Fluent interface.
Return type:: self

add_markdown(text: str) → ContainerElement[source]¶

Add a markdown block.

Note: Requires ‘markdown’ package. If not present, falls back to raw text in <pre>.

render_children() → str[source]¶: Render all child elements concatenated.

collect_payload(registry: Dict[str, Any]) → None[source]¶: Recursively collect payload from children.

render() → str[source]¶: Render the element to HTML.

class coco_pipe.report.core.Section(title: str, icon: str | None = None, tags: List[str] | None = None, status: str = 'OK', code: str | None = None)[source]¶

Bases: ContainerElement

A logical section of the report.

Parameters:

title (str) – The section title.
icon (str, optional) – SVG icon or emoji to display next to the title.
tags (List[str], optional) – Tags for filtering.
status (str, optional) – Status string (“OK”, “WARN”, “FAIL”). Default “OK”.
code (str, optional) – Source code snippet to reproduce this section.

Examples

>>> sec = Section("Results", icon="📈", status="OK")
>>> sec.add_element(plotly_element)
>>> rep.add_section(sec)

title¶

icon = None¶

tags¶

status = 'OK'¶

code = None¶

findings: List[Dict] = []¶

id¶

add_finding(result: coco_pipe.report.quality.CheckResult) → None[source]¶: Add a quality finding and automatically update status.

render() → str[source]¶: Render the element to HTML.

class coco_pipe.report.core.Report(title: str = 'CoCo Analysis Report', config: Dict | coco_pipe.report.config.ReportConfig | None = None)[source]¶

Bases: ContainerElement

The main report container.

Parameters:

title (str) – The report title.
config (Union[Dict, ReportConfig], optional) – Configuration dictionary or ReportConfig object used for the run.

timestamp¶

title = None¶

metadata¶

add_section(section: Section) → Report[source]¶: Syntactic sugar for adding a Section.

add_figure(fig: Any, caption: str | None = None) → Report[source]¶: Add a figure (Matplotlib) or Image.

add_container(container: Any, name: str = 'Data Overview', show_coords: bool = True, show_dist: bool = True) → Report[source]¶

Add a summary section for a DataContainer. Automatically runs quality checks (Missingness, Constants).

Parameters:

container (DataContainer) – The data container to summarize.
name (str) – Title for the section.
show_coords (bool) – If True, shows the table of coordinates.
show_dist (bool) – If True, shows the data/class distribution plot.

Add one scored and optionally interpreted reduction result to the report.

Parameters:

reducer (Any) – Reduction object implementing get_summary().
name (str, optional) – Section title. Defaults to the reduction method name.
X_emb (np.ndarray, optional) – Explicit embedding to visualize. When omitted, the section renders scalar summaries, diagnostics, and interpretation outputs only.
labels (np.ndarray, optional) – Optional labels aligned with X_emb for embedding or trajectory plots.
metadata (dict, optional) – Optional column-oriented metadata aligned with the sample axis of a 2D embedding.
times (np.ndarray, optional) – Optional explicit time axis aligned with the time dimension of a 3D trajectory tensor.

Returns:

The report instance for fluent chaining.

Return type:

Report

Raises:

ValueError – If the supplied embedding or aligned plotting metadata are invalid.
TypeError – If reducer does not implement the strict summary contract.