quadsv.comparators.base

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

This module hosts the private _ComparatorBase mixin that ComparatorIrregular and 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 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 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: quadsv.comparators.irregular and quadsv.comparators.grid.