quadsv.comparators.irregular
============================

.. py:module:: quadsv.comparators.irregular

.. autoapi-nested-parse::

   :class:`ComparatorIrregular` — cross-sample pattern comparison on a
   list of :class:`anndata.AnnData` (irregular spots, NUFFT backend).



Classes
-------

.. autoapisummary::

   quadsv.comparators.irregular.ComparatorIrregular


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

.. py:class:: ComparatorIrregular(samples, gene_names = None, *, feature_mode = 'radial', n_radial_bins = 30, obsm_key = 'spatial', layer = None, unit_scales = None, grid_shape = None, spacing = None, freq_edges = None, eps = 1e-06, presence_threshold = 0.0, nufft_chunk_size = 64, workers = None)

   Bases: :py:obj:`quadsv.comparators.base._ComparatorBase`


   Cross-sample pattern comparison on irregular spots via NUFFT.

   Accepts a list of :class:`anndata.AnnData` (one per sample). For each
   sample, the per-sample ``obsm[obsm_key]`` supplies the irregular
   ``(y, x)`` coordinates and ``.X`` (or ``.layers[layer]`` when set) is the
   expression matrix. Spectra are evaluated with a batched type-1 NUFFT
   (``finufft.nufft2d1``), densifying at most :attr:`nufft_chunk_size`
   columns of ``.X`` at a time so the full slab is never materialized.

   :param samples:
   :type samples: sequence of :class:`anndata.AnnData`
   :param gene_names: If None, inferred from the first sample; every other sample must share
                      the same ``var_names``.
   :type gene_names: sequence of str, optional
   :param feature_mode:
   :type feature_mode: {'radial', '2d'}, default 'radial'
   :param n_radial_bins:
   :type n_radial_bins: int, default 30
   :param obsm_key:
   :type obsm_key: str, default 'spatial'
   :param layer:
   :type layer: str, optional
   :param unit_scales: Per-sample multiplier applied to coords before NUFFT (e.g. pixels→μm).
   :type unit_scales: sequence of float, optional
   :param grid_shape: When both given, used for every sample. Otherwise each sample's
                      k-grid is auto-inferred from coords via
                      :func:`quadsv.kernels.nufft._infer_grid_from_coords`.
   :type grid_shape: optional
   :param spacing: When both given, used for every sample. Otherwise each sample's
                   k-grid is auto-inferred from coords via
                   :func:`quadsv.kernels.nufft._infer_grid_from_coords`.
   :type spacing: optional
   :param freq_edges:
   :type freq_edges: np.ndarray, optional
   :param eps: NUFFT tolerance.
   :type eps: float, default 1e-6
   :param presence_threshold: Minimum fraction of non-zero spots for a gene to count as "observed"
                              in a sample (feeds :attr:`presence_` and, transitively, the masked
                              pattern test).
   :type presence_threshold: float, default 0.0
   :param nufft_chunk_size: Number of genes per batched NUFFT call. 32–128 balances finufft's
                            per-call overhead against the `(n_spots, chunk)` transient RAM.
   :type nufft_chunk_size: int, default 64
   :param workers: Forwarded to per-sample FFTs used by :meth:`normalize_covariates`.
   :type workers: int, optional

   .. rubric:: Notes

   The comparator carries no design / contrast state — supply the
   cross-sample contrast directly to :meth:`test_diff_freq` /
   :meth:`test_diff_expr`. A single fitted comparator can therefore
   serve any number of unrelated comparisons on the same spectra.


   .. py:attribute:: feature_mode
      :value: 'radial'



   .. py:attribute:: freq_edges
      :value: None



   .. py:attribute:: gene_names


   .. py:attribute:: samples