quadsv.comparators.base
=======================

.. py:module:: quadsv.comparators.base

.. autoapi-nested-parse::

   Shared mixin and input-validation helpers for the comparator layer.

   This module hosts the private :class:`_ComparatorBase` mixin that
   :class:`~quadsv.ComparatorIrregular` and :class:`~quadsv.ComparatorGrid`
   inherit from. The mixin owns:

   - the ``compute_spectra`` driver that turns per-sample 2-D images
     into the ``(n_samples, n_genes, K)`` ``spectra_`` tensor;
   - the chainable preprocessing methods ``normalize_background()`` and
     ``normalize_covariates(covariates)`` — thin wrappers around the
     same-named standalone functions in
     :mod:`quadsv.comparators.multisample` that mutate ``spectra_`` in
     place;
   - the test methods ``test_diff_freq(design, ...)`` and
     ``test_diff_expr(design, ...)`` — design-at-call-time so a single
     fitted comparator can serve any number of unrelated contrasts on
     the same spectra;
   - the diagnostic ``effective_rank(level=..., design=...)``.

   The shape-only / sum-1 feature representation is reached via the
   ``normalize_shape: bool = False`` keyword on :meth:`test_diff_freq`
   (forwarded to its dispatch target), not via a chainable method — this
   keeps the per-test choice non-destructive.

   The helpers ``_validate_common`` (constructor argument sanity) and
   ``_validate_design`` (test-time ``design`` normalisation across 1-D
   arrays, 2-D ndarrays, and DataFrames) live at the bottom of the file.

   Concrete classes live in sibling modules:
   :mod:`quadsv.comparators.irregular` and
   :mod:`quadsv.comparators.grid`.