coco_pipe.report.Report#

class coco_pipe.report.Report(title='CoCo Analysis Report', config=None, theme='paper', asset_urls=None)#

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.

  • asset_urls (dict or "inline", optional) –

    Controls how the Plotly / Tailwind / pako JS bundles are loaded:

    • None (default): load from CDN.

    • dict: override one or more URLs (e.g. point at self-hosted copies).

    • "inline": download (and cache on disk) the bundles, then inline them in <script> tags so the rendered HTML is fully self-contained and openable offline. See coco_pipe.report._assets.

  • theme (str)

add_section(section)#

Syntactic sugar for adding a Section.

Parameters:

section (Section)

Return type:

Report

add_figure(fig, caption=None)#

Add a figure (Matplotlib) or Image.

Parameters:

  • fig (Any)

  • caption (str | None)

Return type:

Report

add_container(container, name='Data Overview', show_coords=True, show_dist=True)#

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.

Return type:

Report

add_raw_preview(data, name='Raw Data Inspector')#

Add an interactive scroller for raw data. Automatically checks for flatlines and outliers.

Parameters:

  • data (DataContainer or np.ndarray) – The data to visualize.

  • name (str) – Section title.

Return type:

Report

render()#

Render the full HTML report.

Walks every element to collect heavy payload data (Plotly figures, interactive tables) into a single registry keyed by UUID, then compresses and base64-encodes the registry so it can be embedded inline in the page.

Payload format (the contract with base.html)#

Each element that wants to store payload assigns itself a UUID data-id and pushes its data into the registry:

registry[uuid] = {<element-specific JSON>}

The registry is then serialized as:

JSON.dumps(registry)
-> utf-8 bytes
-> gzip.compress()
-> base64.b64encode().decode("utf-8")

and emitted inside <script type="application/json" id="report-payload">...</script>. The browser script in base.html reverses this (atob -> pako.inflate -> JSON.parse) and exposes the result as REPORT_DATA. Each <div class="lazy-plot" data-id="..."></div> then looks up its payload in REPORT_DATA[dataId] on intersection.

Return type:

str

add_summary_card(metrics, colors=None)#

Add a row of KPI stat-cards above the first section.

Each key-value pair in metrics becomes one StatCardElement. The card row is inserted at the top of the report children list so it appears before any sections regardless of when this method is called.

Parameters:

  • metrics (dict) – Mapping of label → value to display. Float values are formatted with :.4g; all other types are converted to str.

  • colors (list of str, optional) – Tailwind color keys for each card in order. Cycles through ["blue", "green", "purple", "yellow", "red"] by default.

Returns:

The report instance for fluent chaining.

Return type:

Report

Examples

>>> report.add_summary_card({"Best Accuracy": 0.842, "Models": 3, "Folds": 5})
show(port=None)#

Render the report and open it in the default web browser.

A temporary HTML file is written to the system temp directory, then webbrowser.open is called. No server is started; the file is self-contained and can be opened directly.

Parameters:

port (int, optional) – Ignored. Kept for API compatibility with future server-based show() variants.

Return type:

None

Examples

>>> report.show()
save(filename)#

Render and save the report to a file.

Parameters:

filename (str or Path) – Path to save the HTML file.

Return type:

None

Notes

Emits a UserWarning when the report still depends on three external CDN scripts (Plotly, Tailwind, pako). A CDN-backed report renders as grey placeholders if opened without a network connection (e.g. file:// viewing, offline archives, restrictive corporate firewalls, air-gapped machines). Pass asset_urls="inline" to Report to bundle the JavaScript directly into the HTML.

add_comparison(metrics_df, name='Method Comparison')#

Add a comparison section for multiple reduction methods to self.

Parameters:

  • self (Report) – Target report.

  • metrics_df (DataFrame or MethodSelector-like) – Wide/tidy metric data or an object exposing to_frame().

  • name (str) – Section title.

Returns:

self with the new section appended.

Return type:

Report

Raises:

ValueError – If no comparison metrics are available after normalization.

See also

coco_pipe.viz.interactive.dim_reduction.plot_metrics, coco_pipe.dim_reduction.evaluation.core.MethodSelector

add_decoding_diagnostics(result, metric=None, model=None, name='Decoding Diagnostics')#
Parameters:
Return type:

Report

add_decoding_features(result, *, feature_metadata=None, name='Features')#
Parameters:

  • self (Report)

  • result (Any)

  • feature_metadata (DataFrame | None)

  • name (str)

Return type:

Report

add_decoding_neural_artifacts(result, model=None, name='Neural Artifacts')#
Parameters:
Return type:

Report

add_decoding_overview(result, *, name='Overview')#
Parameters:
Return type:

Report

add_decoding_performance(result, *, metric=None, name='Performance')#
Parameters:
Return type:

Report

add_decoding_statistical_assessment(result, metric=None, model=None, name='Statistical Assessment')#
Parameters:
Return type:

Report

add_decoding_summary(result, name='Decoding Summary')#
Parameters:
Return type:

Report

add_decoding_temporal(result, metric=None, model=None, name='Temporal Decoding')#
Parameters:
Return type:

Report

add_decoding_topomaps(result, *, feature_metadata=None, info=None, coords=None, name='Sensor Maps')#
Parameters:

  • self (Report)

  • result (Any)

  • feature_metadata (DataFrame | None)

  • info (Any)

  • coords (Any)

  • name (str)

Return type:

Report

add_element(element)#

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)#

Add a markdown block.

Parameters:

text (str)

Return type:

ContainerElement

add_reduction(reducer, name=None, *, X_emb=None, labels=None, metadata=None, times=None)#

Add one scored and optionally interpreted reduction result to self.

Parameters:

  • self (Report) – Target report.

  • 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:

self with the new section appended.

Return type:

Report

Raises:

ValueError – If X_emb is provided with an unsupported number of dimensions.

See also

coco_pipe.dim_reduction.core.DimReduction.get_summary, coco_pipe.viz.interactive.dim_reduction.plot_embedding, coco_pipe.viz.interactive.dim_reduction.plot_trajectory

add_reduction_components(components, *, feature_names=None, name='Component Loadings')#

Add a component-loadings heatmap to self.

Parameters:

  • self (Report) – Target report.

  • components (array-like) – Component matrix of shape (n_dims, n_features).

  • feature_names (list of str, optional) – Column labels for the feature axis.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if components is None.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_component_loadings

Examples

>>> report.add_reduction_components(pca.components_, feature_names=ch_names)
add_reduction_coranking(coranking_matrix, *, max_k=None, name='Co-Ranking Matrix')#

Add a co-ranking-matrix heatmap to self.

Parameters:

  • self (Report) – Target report.

  • coranking_matrix (array-like) – Square co-ranking matrix of shape (n_samples - 1, n_samples - 1).

  • max_k (int, optional) – Maximum neighbourhood size to display.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if coranking_matrix is None.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_coranking_matrix

Examples

>>> report.add_reduction_coranking(diagnostics["coranking_matrix_"])
add_reduction_diagnostics(X_orig, X_emb, *, name='Diagnostics')#

Add a Shepard diagram comparing original and embedded distances to self.

Parameters:

  • self (Report) – Target report.

  • X_orig (array-like) – Original high-dimensional data of shape (n_samples, n_features).

  • X_emb (array-like) – Low-dimensional embedding of shape (n_samples, n_dims).

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if either array is None.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_shepard_diagram

Examples

>>> report.add_reduction_diagnostics(X_orig, X_2d)
add_reduction_embedding(X_emb, *, labels=None, metadata=None, name='Embedding')#

Add a scatter plot of the low-dimensional embedding to self.

Parameters:

  • self (Report) – Target report.

  • X_emb (array-like) – 2-D or 3-D embedding array of shape (n_samples, n_dims).

  • labels (array-like, optional) – Class labels aligned with X_emb rows.

  • metadata (dict, optional) – Column-oriented metadata for point colouring.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if X_emb is None.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_embedding

Examples

>>> report.add_reduction_embedding(X_2d, labels=y)
add_reduction_interpretation(interpretation, *, analysis='loadings', name='Interpretation')#

Add a component-interpretation plot to self.

Parameters:

  • self (Report) – Target report.

  • interpretation (dict or list) – Interpretation records returned by the reduction object.

  • analysis (str) – Which analysis to visualise (e.g. "loadings").

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if interpretation is falsy.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_feature_importance

Examples

>>> report.add_reduction_interpretation(result.get_summary()["interpretation"])
add_reduction_metrics(reduction, *, metric=None, name='Quality Metrics')#

Add a quality-metrics table and bar chart to self.

Parameters:

  • self (Report) – Target report.

  • reduction (Any) – Scored reduction object; checked for get_scores() and get_summary()["metric_records"].

  • metric (str, optional) – Highlight a specific metric in the bar chart.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if no scores are available.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_metrics

Examples

>>> report.add_reduction_metrics(pca_result)
add_reduction_overview(reduction, *, name='Overview')#

Add a reduction-summary table to self.

Parameters:

  • self (Report) – Target report.

  • reduction (Any) – Scored reduction object exposing get_summary() -> dict.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if the summary is empty.

Return type:

Report

See also

make_reduction_report

Factory that calls this and all other adders.

Examples

>>> report = Report(title="My Report")
>>> report.add_reduction_overview(pca_result)
add_reduction_trajectory(X, *, times=None, labels=None, name='Trajectory')#

Add a temporal trajectory plot to self.

Parameters:

  • self (Report) – Target report.

  • X (array-like) – 3-D embedding of shape (n_times, n_samples, n_dims).

  • times (array-like, optional) – Time axis values aligned with X[0].

  • labels (array-like, optional) – Class labels aligned with the sample axis.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if X is None.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_trajectory

Examples

>>> report.add_reduction_trajectory(X_3d, times=times, labels=y)
add_reduction_trajectory_separation(separation, *, times=None, top_n=None, name='Trajectory Separation')#

Add a trajectory-separation line chart to self.

Parameters:

  • self (Report) – Target report.

  • separation (dict) – Separation scores keyed by class-pair label.

  • times (array-like, optional) – Time axis values.

  • top_n (int, optional) – Limit the chart to the top-N most-separated pairs.

  • name (str) – Section title.

Returns:

self with the new section appended, or unchanged if separation is empty.

Return type:

Report

See also

coco_pipe.viz.dim_reduction.plot_trajectory_separation

Examples

>>> report.add_reduction_trajectory_separation(sep, times=times, top_n=5)
collect_payload(registry)#

Recursively collect payload from children.

Parameters:

registry (dict[str, Any])

Return type:

None

render_children()#

Render all child elements concatenated.

Return type:

str