coco_pipe.diagnostics.variance
==============================

.. py:module:: coco_pipe.diagnostics.variance

.. autoapi-nested-parse::

   Model-free subject and label variance diagnostics for embeddings.



Functions
---------

.. autoapisummary::

   coco_pipe.diagnostics.variance.crossed_ss_fractions
   coco_pipe.diagnostics.variance.nested_ss
   coco_pipe.diagnostics.variance.omega_squared_from_ss
   coco_pipe.diagnostics.variance.null_control
   coco_pipe.diagnostics.variance.subject_probe
   coco_pipe.diagnostics.variance.variance_decomposition_report


Module Contents
---------------

.. py:function:: 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 :func:`variance_decomposition_report` for an additive
   design-aware partition.


.. py:function:: nested_ss(features, subject, label)

   Return the additive subject-within-label ANOVA decomposition.


.. py:function:: 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.


.. py:function:: null_control(features, subject, label, *, n_null_permutations = 200, rng = None)

   Estimate hierarchy-preserving permutation nulls for marginal effects.


.. py:function:: subject_probe(features, subject, *, kind = 'linear', cap = 100, n_splits = 5, seed = 42, blocks=None)

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


.. py:function:: 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.

   :param features: Embedding observations. Containers are flattened with ``obs`` as rows.
   :type features: array-like or DataContainer
   :param subject: Observation-aligned vectors, or explicit coordinate names for a
                   ``DataContainer``. ``container.y`` is the only implicit label source.
   :type subject: array-like or str, optional
   :param label: Observation-aligned vectors, or explicit coordinate names for a
                 ``DataContainer``. ``container.y`` is the only implicit label source.
   :type label: array-like or str, optional
   :param feature_scaling: Z-scoring makes the pooled SS partition invariant to feature units.
                           Constant features are retained as zeros and counted in the output.
   :type feature_scaling: {"none", "zscore"}, default="zscore"
   :param n_null_permutations: Number of hierarchy-preserving permutations used for marginal nulls.
   :type n_null_permutations: int, default=200
   :param rng: Permutation generator. A deterministic generator is used by default.
   :type rng: numpy.random.Generator, optional
   :param probe_blocks: Acquisition/session block identifier. When supplied, subject-probe CV
                        holds out complete subject-block combinations.
   :type probe_blocks: array-like or str, optional
   :param probe_cap: Subject-probe sampling and cross-validation settings.
   :type probe_cap: int
   :param probe_n_splits: Subject-probe sampling and cross-validation settings.
   :type probe_n_splits: int
   :param probe_seed: Subject-probe sampling and cross-validation settings.
   :type probe_seed: int

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