coco_pipe.report.dim_reduction#

Section builders for dimensionality-reduction reports.

Attributes#

DEFAULT_REDUCTION_SECTIONS

Functions#

`add_reduction_overview`(self, reduction, *[, name])	Add a reduction-summary table to self.
`add_reduction_embedding`(self, X_emb, *[, labels, ...])	Add a scatter plot of the low-dimensional embedding to self.
`add_reduction_metrics`(self, reduction, *[, metric, name])	Add a quality-metrics table and bar chart to self.
`add_reduction_diagnostics`(self, X_orig, X_emb, *[, name])	Add a Shepard diagram comparing original and embedded distances to self.
`add_reduction_interpretation`(self, interpretation, *)	Add a component-interpretation plot to self.
`add_reduction_coranking`(self, coranking_matrix, *[, ...])	Add a co-ranking-matrix heatmap to self.
`add_reduction_components`(self, components, *[, ...])	Add a component-loadings heatmap to self.
`add_reduction_trajectory`(self, X, *[, times, labels, name])	Add a temporal trajectory plot to self.
`add_reduction_trajectory_separation`(self, separation, *)	Add a trajectory-separation line chart to self.
`make_reduction_report`(reductions, *[, embeddings, ...])	Build a dimensionality-reduction report for one or more reduction objects.
`add_reduction`(self, reducer[, name, X_emb, labels, ...])	Add one scored and optionally interpreted reduction result to self.
`add_comparison`(self, metrics_df[, name])	Add a comparison section for multiple reduction methods to self.

Module Contents#

coco_pipe.report.dim_reduction.DEFAULT_REDUCTION_SECTIONS: list[str] = ['overview', 'embedding', 'metrics', 'diagnostics', 'coranking', 'interpretation', 'components',...#

coco_pipe.report.dim_reduction.add_reduction_overview(self, 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)

coco_pipe.report.dim_reduction.add_reduction_embedding(self, 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

Examples

>>> report.add_reduction_embedding(X_2d, labels=y)

coco_pipe.report.dim_reduction.add_reduction_metrics(self, 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

Examples

>>> report.add_reduction_metrics(pca_result)

coco_pipe.report.dim_reduction.add_reduction_diagnostics(self, 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

Examples

>>> report.add_reduction_diagnostics(X_orig, X_2d)

coco_pipe.report.dim_reduction.add_reduction_interpretation(self, 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

Examples

>>> report.add_reduction_interpretation(result.get_summary()["interpretation"])

coco_pipe.report.dim_reduction.add_reduction_coranking(self, 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

Examples

>>> report.add_reduction_coranking(diagnostics["coranking_matrix_"])

coco_pipe.report.dim_reduction.add_reduction_components(self, 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

Examples

>>> report.add_reduction_components(pca.components_, feature_names=ch_names)

coco_pipe.report.dim_reduction.add_reduction_trajectory(self, 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

Examples

>>> report.add_reduction_trajectory(X_3d, times=times, labels=y)

coco_pipe.report.dim_reduction.add_reduction_trajectory_separation(self, 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

Examples

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

coco_pipe.report.dim_reduction.make_reduction_report(reductions, *, embeddings=None, labels=None, metadata=None, times=None, sections='default', interactive=False, theme='paper', title='Dimensionality Reduction Report', config=None, asset_urls=None, qc_result=None, output_path=None)#

Build a dimensionality-reduction report for one or more reduction objects.

Parameters:

reductions (list) – Scored reduction objects implementing get_summary().
embeddings (list, optional) – Explicit embedding arrays aligned with reductions. Required for embedding, trajectory, and Shepard-diagram sections.
labels (array-like, optional) – Class labels aligned with each embedding’s sample axis.
metadata (dict, optional) – Column-oriented metadata for point colouring in embedding plots.
times (array-like, optional) – Time axis aligned with 3-D trajectory embeddings.
sections (list of str or "default") – Ordered list of section keys (see DEFAULT_REDUCTION_SECTIONS).
interactive (bool) – Reserved for future use. Currently ignored; pass False.
theme ("paper" | "notebook" | "poster") – Matplotlib theme preset.
title (str) – Report title.
config (dict, optional) – Extra configuration metadata stored in the report header.
asset_urls (dict, optional) – Override JavaScript asset URLs used by the report shell.
qc_result (QCResult, optional) – Structured QC drop log rendered before analysis sections.
output_path (str, optional) – If given, save the rendered HTML to this path.

Returns:

Fully populated report. Sections whose data is absent are skipped silently.

Return type:

Report

Raises:

ValueError – If embeddings is provided but its length differs from reductions.

See also

coco_pipe.report.api.from_reductions: Thin public wrapper.
make_decoding_report: Equivalent factory for decoding results.

Examples

>>> report = make_reduction_report([pca, tsne], embeddings=[X_pca, X_tsne])
>>> report.save("reduction_report.html")

coco_pipe.report.dim_reduction.add_reduction(self, 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

coco_pipe.report.dim_reduction.add_comparison(self, 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.