coco_pipe.diagnostics.variance_decomposition_report#

coco_pipe.diagnostics.variance_decomposition_report(features, subject=None, label=None, *, feature_scaling='zscore', n_null_permutations=200, rng=None, probe_blocks=None, probe_cap=100, probe_n_splits=5, probe_seed=42)#

Return design-aware subject and label diagnostics for an embedding.

Pure-label subjects use an additive subject-within-label decomposition. When labels vary within subject, an adjusted additive fixed-effects model reports unique label, unique subject, shared/confounded, and residual SS.

Parameters:

  • features (array-like or DataContainer) – Embedding observations. Containers are flattened with obs as rows.

  • subject (array-like or str, optional) – Observation-aligned vectors, or explicit coordinate names for a DataContainer. container.y is the only implicit label source.

  • label (array-like or str, optional) – Observation-aligned vectors, or explicit coordinate names for a DataContainer. container.y is the only implicit label source.

  • feature_scaling ({"none", "zscore"}, default="zscore") – Z-scoring makes the pooled SS partition invariant to feature units. Constant features are retained as zeros and counted in the output.

  • n_null_permutations (int, default=200) – Number of hierarchy-preserving permutations used for marginal nulls.

  • rng (numpy.random.Generator, optional) – Permutation generator. A deterministic generator is used by default.

  • probe_blocks (array-like or str, optional) – Acquisition/session block identifier. When supplied, subject-probe CV holds out complete subject-block combinations.

  • probe_cap (int) – Subject-probe sampling and cross-validation settings.

  • probe_n_splits (int) – Subject-probe sampling and cross-validation settings.

  • probe_seed (int) – Subject-probe sampling and cross-validation settings.

Returns:

One row per metric with design, scaling, null, and probe metadata. Interpretive caveats are stored in report.attrs["notes"].

Return type:

pandas.DataFrame