coco_pipe.report.dim_reduction_sweep#

Records/artifact-based dimensionality-reduction sweep reporting.

The dim-reduction counterpart to coco_pipe.report.decoding_sweep: helpers that operate on persisted fit/eval run artifacts (the 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 coco_pipe.report.dim_reduction; study-specific policy (cohort metadata, scope ordering, topomaps, report links) stays in the consuming project.

Attributes#

DEFAULT_REDUCTION_TIE_BREAKERS

Classes#

DimReductionReportContext

Resolved configuration + injection seams for a dataset report.

Functions#

merge_fit_eval(fit_runs[, eval_runs, eval_name, ...])

Left-merge successful evaluation metrics onto fit runs by key.

rank_reduction_runs(fit_runs[, eval_runs, group_by, ...])

Return the best successful fit run per group.

add_reduction_best_run_cards(section, runs, *[, ...])

Append a best-run callout + StatCards per group to section.

build_reduction_eval_results_section(eval_frame, *[, ...])

Build the post-hoc evaluation section, or None if empty.

build_reduction_condition_ranking_section(...[, ...])

Build the condition-ranking table + reducer-profile radars.

build_reduction_rollup_report(leaderboard, *, title[, ...])

Build the cross-mode dimensionality-reduction roll-up report.

build_meta_dict(container, ids, ctx)

Build a plotting-metadata dict from a container's observation frame.

build_best_fit_plots(title, artifact, meta_dict, ctx)

Build the best-fit diagnostics element for a single reducer fit.

build_flat_condition_section(condition, ...)

Build the per-condition section for analysis_mode == "flat".

build_unit_summary(section, unit_runs, ctx, *, ...)

Append unit-level ranking tables, bar charts, stability boxes + topomaps.

build_nonflat_condition_section(condition, ...)

Build the per-condition section for non-flat modes (family/sensor/etc.).

build_pooled_section(pooled_runs, pooled_eval_runs, ctx)

Build the pooled multi-condition section, or None when there are no runs.

build_data_availability_summary(overview_sec, ctx, ...)

Append a data-availability accordion to overview_sec (no-op if empty).

build_failure_sections(report, fit_runs_df, ...)

Append fit/eval failure sections to report when failures exist.

build_dataset_report(ctx, *, fit_runs_path, eval_runs_path)

Assemble the full per-dataset dimensionality-reduction report.

Module Contents#

coco_pipe.report.dim_reduction_sweep.DEFAULT_REDUCTION_TIE_BREAKERS: tuple[tuple[str, bool], ...]#
coco_pipe.report.dim_reduction_sweep.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).

Parameters:
Return type:

pandas.DataFrame

coco_pipe.report.dim_reduction_sweep.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 coco_pipe.dim_reduction artifact schema (status/fit_id/reducer columns).

Parameters:
Return type:

pandas.DataFrame

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

None

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

coco_pipe.report.core.Section | None

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

coco_pipe.report.core.Section | None

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

coco_pipe.report.core.Report

class coco_pipe.report.dim_reduction_sweep.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 container_builder, which loads the dataset container for a condition, plus the optional build_dataset_report() overview_extras hook for cohort summaries.

analysis_mode: str#
selection_metric: str#
reducers: collections.abc.Sequence[str]#
conditions: collections.abc.Sequence[str]#
container_builder: collections.abc.Callable[[str], Any | None]#
output_root: pathlib.Path#
eval_specs: collections.abc.Sequence[collections.abc.Mapping[str, Any]] = ()#
interactive: bool = False#
input_mode: str = ''#
representation: str = ''#
family_label: str = ''#
run_pooled: bool = False#
pooled_condition: str = ''#
dataset_name: str = ''#
report_title: str = 'Dimensionality Reduction'#
excluded_columns: frozenset[str]#
excluded_normalized: frozenset[str]#
excluded_normalized_substrings: tuple[str, ...] = ()#
excluded_suffixes: tuple[str, ...] = ()#
meta_extractors: collections.abc.Mapping[str, collections.abc.Callable[[dict[str, numpy.ndarray]], Any]]#
topomap_channels: frozenset[str] | None = None#
unit_labels: collections.abc.Mapping[str, str]#
fit_failure_columns: collections.abc.Sequence[str] = ()#
eval_failure_columns: collections.abc.Sequence[str] = ()#
unit_label(default)#

Return the human-readable unit label for the current mode.

Parameters:

default (str)

Return type:

str

coco_pipe.report.dim_reduction_sweep.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 meta_extractors (e.g. eye-state derivation). Rows are aligned to ids when provided.

Parameters:
Return type:

dict[str, numpy.ndarray]

coco_pipe.report.dim_reduction_sweep.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 topomap_channels) and a scree plot of the explained_variance_ratio diagnostic. Returns None when the embedding is not 2-D.

Parameters:
Return type:

Any

coco_pipe.report.dim_reduction_sweep.build_flat_condition_section(condition, condition_runs, eval_frame, ctx)#

Build the per-condition section for analysis_mode == "flat".

Parameters:
Return type:

coco_pipe.report.core.Section

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

None

coco_pipe.report.dim_reduction_sweep.build_nonflat_condition_section(condition, condition_runs, eval_frame, ctx)#

Build the per-condition section for non-flat modes (family/sensor/etc.).

Parameters:
Return type:

coco_pipe.report.core.Section

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

coco_pipe.report.core.Section | None

coco_pipe.report.dim_reduction_sweep.build_data_availability_summary(overview_sec, ctx, dataset_stats, fit_runs_df)#

Append a data-availability accordion to overview_sec (no-op if empty).

Parameters:
Return type:

None

coco_pipe.report.dim_reduction_sweep.build_failure_sections(report, fit_runs_df, eval_runs_df, ctx)#

Append fit/eval failure sections to report when failures exist.

Parameters:
Return type:

None

coco_pipe.report.dim_reduction_sweep.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.

Parameters:
Return type:

coco_pipe.report.core.Report

On this page
Edit on GitHub
Show Source