coco_pipe.report.dim_reduction ============================== .. py:module:: coco_pipe.report.dim_reduction .. autoapi-nested-parse:: Section builders for dimensionality-reduction reports. Attributes ---------- .. autoapisummary:: coco_pipe.report.dim_reduction.DEFAULT_REDUCTION_SECTIONS Functions --------- .. autoapisummary:: coco_pipe.report.dim_reduction.add_reduction_overview coco_pipe.report.dim_reduction.add_reduction_embedding coco_pipe.report.dim_reduction.add_reduction_metrics coco_pipe.report.dim_reduction.add_reduction_diagnostics coco_pipe.report.dim_reduction.add_reduction_interpretation coco_pipe.report.dim_reduction.add_reduction_coranking coco_pipe.report.dim_reduction.add_reduction_components coco_pipe.report.dim_reduction.add_reduction_trajectory coco_pipe.report.dim_reduction.add_reduction_trajectory_separation coco_pipe.report.dim_reduction.make_reduction_report coco_pipe.report.dim_reduction.add_reduction coco_pipe.report.dim_reduction.add_comparison Module Contents --------------- .. py:data:: DEFAULT_REDUCTION_SECTIONS :type: list[str] :value: ['overview', 'embedding', 'metrics', 'diagnostics', 'coranking', 'interpretation', 'components',... .. py:function:: add_reduction_overview(self, reduction, *, name = 'Overview') Add a reduction-summary table to *self*. :param self: Target report. :type self: Report :param reduction: Scored reduction object exposing ``get_summary() -> dict``. :type reduction: Any :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if the summary is empty. :rtype: Report .. seealso:: :py:obj:`make_reduction_report` Factory that calls this and all other adders. .. rubric:: Examples >>> report = Report(title="My Report") >>> report.add_reduction_overview(pca_result) .. py:function:: add_reduction_embedding(self, X_emb, *, labels = None, metadata = None, name = 'Embedding') Add a scatter plot of the low-dimensional embedding to *self*. :param self: Target report. :type self: Report :param X_emb: 2-D or 3-D embedding array of shape ``(n_samples, n_dims)``. :type X_emb: array-like :param labels: Class labels aligned with *X_emb* rows. :type labels: array-like, optional :param metadata: Column-oriented metadata for point colouring. :type metadata: dict, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *X_emb* is ``None``. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_embedding` .. rubric:: Examples >>> report.add_reduction_embedding(X_2d, labels=y) .. py:function:: add_reduction_metrics(self, reduction, *, metric = None, name = 'Quality Metrics') Add a quality-metrics table and bar chart to *self*. :param self: Target report. :type self: Report :param reduction: Scored reduction object; checked for ``get_scores()`` and ``get_summary()["metric_records"]``. :type reduction: Any :param metric: Highlight a specific metric in the bar chart. :type metric: str, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if no scores are available. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_metrics` .. rubric:: Examples >>> report.add_reduction_metrics(pca_result) .. py:function:: add_reduction_diagnostics(self, X_orig, X_emb, *, name = 'Diagnostics') Add a Shepard diagram comparing original and embedded distances to *self*. :param self: Target report. :type self: Report :param X_orig: Original high-dimensional data of shape ``(n_samples, n_features)``. :type X_orig: array-like :param X_emb: Low-dimensional embedding of shape ``(n_samples, n_dims)``. :type X_emb: array-like :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if either array is ``None``. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_shepard_diagram` .. rubric:: Examples >>> report.add_reduction_diagnostics(X_orig, X_2d) .. py:function:: add_reduction_interpretation(self, interpretation, *, analysis = 'loadings', name = 'Interpretation') Add a component-interpretation plot to *self*. :param self: Target report. :type self: Report :param interpretation: Interpretation records returned by the reduction object. :type interpretation: dict or list :param analysis: Which analysis to visualise (e.g. ``"loadings"``). :type analysis: str :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *interpretation* is falsy. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_feature_importance` .. rubric:: Examples >>> report.add_reduction_interpretation(result.get_summary()["interpretation"]) .. py:function:: add_reduction_coranking(self, coranking_matrix, *, max_k = None, name = 'Co-Ranking Matrix') Add a co-ranking-matrix heatmap to *self*. :param self: Target report. :type self: Report :param coranking_matrix: Square co-ranking matrix of shape ``(n_samples - 1, n_samples - 1)``. :type coranking_matrix: array-like :param max_k: Maximum neighbourhood size to display. :type max_k: int, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *coranking_matrix* is ``None``. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_coranking_matrix` .. rubric:: Examples >>> report.add_reduction_coranking(diagnostics["coranking_matrix_"]) .. py:function:: add_reduction_components(self, components, *, feature_names = None, name = 'Component Loadings') Add a component-loadings heatmap to *self*. :param self: Target report. :type self: Report :param components: Component matrix of shape ``(n_dims, n_features)``. :type components: array-like :param feature_names: Column labels for the feature axis. :type feature_names: list of str, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *components* is ``None``. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_component_loadings` .. rubric:: Examples >>> report.add_reduction_components(pca.components_, feature_names=ch_names) .. py:function:: add_reduction_trajectory(self, X, *, times = None, labels = None, name = 'Trajectory') Add a temporal trajectory plot to *self*. :param self: Target report. :type self: Report :param X: 3-D embedding of shape ``(n_times, n_samples, n_dims)``. :type X: array-like :param times: Time axis values aligned with ``X[0]``. :type times: array-like, optional :param labels: Class labels aligned with the sample axis. :type labels: array-like, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *X* is ``None``. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_trajectory` .. rubric:: Examples >>> report.add_reduction_trajectory(X_3d, times=times, labels=y) .. py:function:: add_reduction_trajectory_separation(self, separation, *, times = None, top_n = None, name = 'Trajectory Separation') Add a trajectory-separation line chart to *self*. :param self: Target report. :type self: Report :param separation: Separation scores keyed by class-pair label. :type separation: dict :param times: Time axis values. :type times: array-like, optional :param top_n: Limit the chart to the top-N most-separated pairs. :type top_n: int, optional :param name: Section title. :type name: str :returns: *self* with the new section appended, or unchanged if *separation* is empty. :rtype: Report .. seealso:: :py:obj:`coco_pipe.viz.dim_reduction.plot_trajectory_separation` .. rubric:: Examples >>> report.add_reduction_trajectory_separation(sep, times=times, top_n=5) .. py:function:: 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. :param reductions: Scored reduction objects implementing ``get_summary()``. :type reductions: list :param embeddings: Explicit embedding arrays aligned with *reductions*. Required for embedding, trajectory, and Shepard-diagram sections. :type embeddings: list, optional :param labels: Class labels aligned with each embedding's sample axis. :type labels: array-like, optional :param metadata: Column-oriented metadata for point colouring in embedding plots. :type metadata: dict, optional :param times: Time axis aligned with 3-D trajectory embeddings. :type times: array-like, optional :param sections: Ordered list of section keys (see :data:`DEFAULT_REDUCTION_SECTIONS`). :type sections: list of str or ``"default"`` :param interactive: Reserved for future use. Currently ignored; pass ``False``. :type interactive: bool :param theme: Matplotlib theme preset. :type theme: ``"paper"`` | ``"notebook"`` | ``"poster"`` :param title: Report title. :type title: str :param config: Extra configuration metadata stored in the report header. :type config: dict, optional :param asset_urls: Override JavaScript asset URLs used by the report shell. :type asset_urls: dict, optional :param qc_result: Structured QC drop log rendered before analysis sections. :type qc_result: QCResult, optional :param output_path: If given, save the rendered HTML to this path. :type output_path: str, optional :returns: Fully populated report. Sections whose data is absent are skipped silently. :rtype: Report :raises ValueError: If *embeddings* is provided but its length differs from *reductions*. .. seealso:: :py:obj:`coco_pipe.report.api.from_reductions` Thin public wrapper. :py:obj:`make_decoding_report` Equivalent factory for decoding results. .. rubric:: Examples >>> report = make_reduction_report([pca, tsne], embeddings=[X_pca, X_tsne]) >>> report.save("reduction_report.html") .. py:function:: 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*. :param self: Target report. :type self: Report :param reducer: Reduction object implementing ``get_summary()``. :type reducer: Any :param name: Section title. Defaults to the reduction method name. :type name: str, optional :param X_emb: Explicit embedding to visualize. When omitted, the section renders scalar summaries, diagnostics, and interpretation outputs only. :type X_emb: np.ndarray, optional :param labels: Optional labels aligned with ``X_emb`` for embedding or trajectory plots. :type labels: np.ndarray, optional :param metadata: Optional column-oriented metadata aligned with the sample axis of a 2D embedding. :type metadata: dict, optional :param times: Optional explicit time axis aligned with the time dimension of a 3D trajectory tensor. :type times: np.ndarray, optional :returns: *self* with the new section appended. :rtype: Report :raises ValueError: If ``X_emb`` is provided with an unsupported number of dimensions. .. seealso:: :py:obj:`coco_pipe.dim_reduction.core.DimReduction.get_summary`, :py:obj:`coco_pipe.viz.interactive.dim_reduction.plot_embedding`, :py:obj:`coco_pipe.viz.interactive.dim_reduction.plot_trajectory` .. py:function:: add_comparison(self, metrics_df, name = 'Method Comparison') Add a comparison section for multiple reduction methods to *self*. :param self: Target report. :type self: Report :param metrics_df: Wide/tidy metric data or an object exposing ``to_frame()``. :type metrics_df: DataFrame or MethodSelector-like :param name: Section title. :type name: str :returns: *self* with the new section appended. :rtype: Report :raises ValueError: If no comparison metrics are available after normalization. .. seealso:: :py:obj:`coco_pipe.viz.interactive.dim_reduction.plot_metrics`, :py:obj:`coco_pipe.dim_reduction.evaluation.core.MethodSelector`