coco_pipe.diagnostics.variance#

Model-free subject and label variance diagnostics for embeddings.

Functions#

crossed_ss_fractions(features, subject, label)

Return separate marginal label and subject eta-squared diagnostics.

nested_ss(features, subject, label)

Return the additive subject-within-label ANOVA decomposition.

omega_squared_from_ss(ss)

Compute design-appropriate omega squared for a nested decomposition.

null_control(features, subject, label, *[, ...])

Estimate hierarchy-preserving permutation nulls for marginal effects.

subject_probe(features, subject, *[, kind, cap, ...])

Cross-validate subject identity, optionally holding out whole blocks.

variance_decomposition_report(features[, subject, ...])

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

Module Contents#

coco_pipe.diagnostics.variance.crossed_ss_fractions(features, subject, label)#

Return separate marginal label and subject eta-squared diagnostics.

These effects may overlap and must not be added or subtracted to obtain a residual. Use variance_decomposition_report() for an additive design-aware partition.

Return type:

dict[str, float | bool]

coco_pipe.diagnostics.variance.nested_ss(features, subject, label)#

Return the additive subject-within-label ANOVA decomposition.

Return type:

dict[str, numpy.ndarray | int]

coco_pipe.diagnostics.variance.omega_squared_from_ss(ss)#

Compute design-appropriate omega squared for a nested decomposition.

The label effect is estimated from subject means so recordings from the same subject are not treated as independent replicates. Subject-within-label is reported as partial omega squared against the recording-level residual.

Parameters:

ss (dict[str, Any])

Return type:

dict[str, float]

coco_pipe.diagnostics.variance.null_control(features, subject, label, *, n_null_permutations=200, rng=None)#

Estimate hierarchy-preserving permutation nulls for marginal effects.

Parameters:
Return type:

dict[str, Any]

coco_pipe.diagnostics.variance.subject_probe(features, subject, *, kind='linear', cap=100, n_splits=5, seed=42, blocks=None)#

Cross-validate subject identity, optionally holding out whole blocks.

Parameters:
Return type:

tuple[float | None, int]

coco_pipe.diagnostics.variance.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