coco_pipe.report.dim_reduction_sweep ==================================== .. py:module:: coco_pipe.report.dim_reduction_sweep .. autoapi-nested-parse:: Records/artifact-based dimensionality-reduction sweep reporting. The dim-reduction counterpart to :mod:`coco_pipe.report.decoding_sweep`: helpers that operate on persisted fit/eval run artifacts (the :mod:`coco_pipe.dim_reduction` schema) to merge and rank runs and to assemble a cross-mode roll-up report. The per-reduction section builders live in :mod:`coco_pipe.report.dim_reduction`; study-specific policy (cohort metadata, scope ordering, topomaps, report links) stays in the consuming project. Attributes ---------- .. autoapisummary:: coco_pipe.report.dim_reduction_sweep.DEFAULT_REDUCTION_TIE_BREAKERS Classes ------- .. autoapisummary:: coco_pipe.report.dim_reduction_sweep.DimReductionReportContext Functions --------- .. autoapisummary:: coco_pipe.report.dim_reduction_sweep.merge_fit_eval coco_pipe.report.dim_reduction_sweep.rank_reduction_runs coco_pipe.report.dim_reduction_sweep.add_reduction_best_run_cards coco_pipe.report.dim_reduction_sweep.build_reduction_eval_results_section coco_pipe.report.dim_reduction_sweep.build_reduction_condition_ranking_section coco_pipe.report.dim_reduction_sweep.build_reduction_rollup_report coco_pipe.report.dim_reduction_sweep.build_meta_dict coco_pipe.report.dim_reduction_sweep.build_best_fit_plots coco_pipe.report.dim_reduction_sweep.build_flat_condition_section coco_pipe.report.dim_reduction_sweep.build_unit_summary coco_pipe.report.dim_reduction_sweep.build_nonflat_condition_section coco_pipe.report.dim_reduction_sweep.build_pooled_section coco_pipe.report.dim_reduction_sweep.build_data_availability_summary coco_pipe.report.dim_reduction_sweep.build_failure_sections coco_pipe.report.dim_reduction_sweep.build_dataset_report Module Contents --------------- .. py:data:: DEFAULT_REDUCTION_TIE_BREAKERS :type: tuple[tuple[str, bool], ...] .. py:function:: merge_fit_eval(fit_runs, eval_runs = None, *, eval_name = None, metrics = tuple(EVAL_METRIC_COLUMNS), key = 'fit_id') Left-merge successful evaluation metrics onto fit runs by *key*. Returns the fit-run frame unchanged when there is no usable evaluation data. When *eval_name* is given, evaluations are filtered to it first so each fit run contributes at most one evaluation row (avoiding row multiplication). .. py:function:: rank_reduction_runs(fit_runs, eval_runs = None, *, selection_metric, group_by = ('scope', 'condition'), eval_name = None, tie_breakers = DEFAULT_REDUCTION_TIE_BREAKERS, reducers = None, metrics = tuple(EVAL_METRIC_COLUMNS)) Return the best successful fit run per group. Merges evaluation metrics onto the (successful) fit runs, optionally restricts to *reducers*, and takes the top run per *group_by* ranked by *selection_metric* then *tie_breakers*. Empty when no successful fit runs survive. The fit/eval frames follow the :mod:`coco_pipe.dim_reduction` artifact schema (``status``/``fit_id``/``reducer`` columns). .. py:function:: add_reduction_best_run_cards(section, runs, *, group_col = 'condition', selection_metric, fallback_metric = 'trustworthiness', tie_breakers = DEFAULT_REDUCTION_TIE_BREAKERS, metrics = _DEFAULT_BEST_RUN_METRICS) Append a best-run callout + StatCards per group to *section*. For each group value (default ``condition``), renders the winning run's reducer / component count / optional unit plus its quality metrics. A no-op when there are no successful runs. Study code owns which section this lands in; the card layout is shared. .. py:function:: build_reduction_eval_results_section(eval_frame, *, sort_col = None, selector_columns = ('scope', 'condition', 'family', 'unit_name', 'reducer', 'eval_name'), title = 'Evaluation Results', accordion_label = 'Show Post-hoc Evaluation Results', selection_metric = None, eval_name_order = None, conditions = None, top_n = 15) Build the post-hoc evaluation section, or None if empty. The section holds a collapsible results table plus, below it, top-*top_n* unit bar charts ranked by *selection_metric* (or the first available separation metric): one tab per evaluation (the primary evaluation first, per *eval_name_order*), each with a condition sub-tab whose bars are colored by unit and labeled with the winning ``n_components``. .. py:function:: build_reduction_condition_ranking_section(condition_runs, *, conditions, reducers, selection_metric, fallback_metric = 'trustworthiness', ranking_columns = ('condition', 'family', 'unit_name', 'reducer', 'n_components', 'eval_name', *EVAL_METRIC_COLUMNS, 'trustworthiness', 'continuity'), selector_columns = ('condition', 'family', 'unit_name', 'reducer', 'eval_name'), radar_metrics = ('trustworthiness', 'continuity', 'shepard_correlation', *EVAL_METRIC_COLUMNS), default_sort = None, title = 'Condition Ranking') Build the condition-ranking table + reducer-profile radars. *condition_runs* are the successful condition-scope runs (the caller owns the scope/status filter). The section shows a sortable ranking table plus, when there are multiple reducers, an overall and per-condition reducer-profile radar. Returns None when *condition_runs* is empty. .. py:function:: build_reduction_rollup_report(leaderboard, *, title, x_metric = 'trustworthiness', y_metric = SEPARATION_RF_METRIC_KEY, sort_col = None, mode_label_map = None, strategy_note = None, link_rows = None, task_failures = (), selector_columns = _DEFAULT_ROLLUP_SELECTORS, asset_urls = None) Build the cross-mode dimensionality-reduction roll-up report. A sortable leaderboard table plus an *x_metric* vs *y_metric* scatter (e.g. faithful-vs-discriminative: trustworthiness x separation), optional per-mode report links and a failures table. The caller owns the metric choice, the ``analysis_mode`` label map, the strategy note and the report links; this function owns the generic scaffolding. .. py:class:: DimReductionReportContext Resolved configuration + injection seams for a dataset report. Constructed once by the consuming project and threaded through the section builders. Study-specific policy travels as **data** (metadata-exclusion sets, topomap channel vocabulary, unit labels, failure columns); the single behavioural seam is :attr:`container_builder`, which loads the dataset container for a condition, plus the optional :func:`build_dataset_report` ``overview_extras`` hook for cohort summaries. .. py:attribute:: analysis_mode :type: str .. py:attribute:: selection_metric :type: str .. py:attribute:: reducers :type: collections.abc.Sequence[str] .. py:attribute:: conditions :type: collections.abc.Sequence[str] .. py:attribute:: container_builder :type: collections.abc.Callable[[str], Any | None] .. py:attribute:: output_root :type: pathlib.Path .. py:attribute:: eval_specs :type: collections.abc.Sequence[collections.abc.Mapping[str, Any]] :value: () .. py:attribute:: interactive :type: bool :value: False .. py:attribute:: input_mode :type: str :value: '' .. py:attribute:: representation :type: str :value: '' .. py:attribute:: family_label :type: str :value: '' .. py:attribute:: run_pooled :type: bool :value: False .. py:attribute:: pooled_condition :type: str :value: '' .. py:attribute:: dataset_name :type: str :value: '' .. py:attribute:: report_title :type: str :value: 'Dimensionality Reduction' .. py:attribute:: excluded_columns :type: frozenset[str] .. py:attribute:: excluded_normalized :type: frozenset[str] .. py:attribute:: excluded_normalized_substrings :type: tuple[str, ...] :value: () .. py:attribute:: excluded_suffixes :type: tuple[str, ...] :value: () .. py:attribute:: meta_extractors :type: collections.abc.Mapping[str, collections.abc.Callable[[dict[str, numpy.ndarray]], Any]] .. py:attribute:: topomap_channels :type: frozenset[str] | None :value: None .. py:attribute:: unit_labels :type: collections.abc.Mapping[str, str] .. py:attribute:: fit_failure_columns :type: collections.abc.Sequence[str] :value: () .. py:attribute:: eval_failure_columns :type: collections.abc.Sequence[str] :value: () .. py:method:: unit_label(default) Return the human-readable unit label for the current mode. .. py:function:: build_meta_dict(container, ids, ctx) Build a plotting-metadata dict from a container's observation frame. Filters excluded columns (per *ctx* policy), applies eval-spec label maps / filters, and runs any registered :attr:`~DimReductionReportContext.meta_extractors` (e.g. eye-state derivation). Rows are aligned to *ids* when provided. .. py:function:: build_best_fit_plots(title, artifact, meta_dict, ctx, feature_names = None) Build the best-fit diagnostics element for a single reducer fit. Renders the native 2-D / first-3-dims embedding scatter and, when available, a scalp topomap of the component loadings (only when *feature_names* are montage channels per :attr:`~DimReductionReportContext.topomap_channels`) and a scree plot of the ``explained_variance_ratio`` diagnostic. Returns ``None`` when the embedding is not 2-D. .. py:function:: build_flat_condition_section(condition, condition_runs, eval_frame, ctx) Build the per-condition section for ``analysis_mode == "flat"``. .. py:function:: build_unit_summary(section, unit_runs, ctx, *, unit_label, title_prefix) Append unit-level ranking tables, bar charts, stability boxes + topomaps. The peak/stability/topomap visuals are tabbed by ``eval_name`` (the scientific contrast) with every unit compared side by side inside each tab — rather than one tab per unit, which collapses to single-bar charts. .. py:function:: build_nonflat_condition_section(condition, condition_runs, eval_frame, ctx) Build the per-condition section for non-flat modes (family/sensor/etc.). .. py:function:: build_pooled_section(pooled_runs, pooled_eval_runs, ctx, pooled_container = None) Build the pooled multi-condition section, or None when there are no runs. .. py:function:: build_data_availability_summary(overview_sec, ctx, dataset_stats, fit_runs_df) Append a data-availability accordion to *overview_sec* (no-op if empty). .. py:function:: build_failure_sections(report, fit_runs_df, eval_runs_df, ctx) Append fit/eval failure sections to *report* when failures exist. .. py:function:: build_dataset_report(ctx, *, fit_runs_path, eval_runs_path, containers_by_scope = None, dataset_stats = None, overview_extras = None) Assemble the full per-dataset dimensionality-reduction report. Builds the Overview (config + data availability + best-run cards, plus any *overview_extras* such as a cohort summary), QC sections, evaluation results, condition ranking, per-condition sections, the pooled section and failure tables. All study-specific policy is carried by *ctx*.