quadsv.detectors.base
=====================

.. py:module:: quadsv.detectors.base

.. autoapi-nested-parse::

   Shared base class for single-sample spatial pattern detectors.

   Concrete detectors follow a three-step workflow:

   1. **Construction** — :meth:`Detector.__init__` takes kernel method + backend
      configs + kernel hyperparameters. No data is attached.
   2. **Data setup** — :meth:`Detector.setup_data` takes the input container
      (:class:`anndata.AnnData` for :class:`DetectorIrregular`,
      :class:`spatialdata.SpatialData` for :class:`DetectorGrid`), performs
      preprocessing (feature filtering, coordinate / obsp extraction, or
      rasterization), and builds the kernel.
   3. **Computation** — :meth:`Detector.compute_qstat` and
      :meth:`Detector.compute_rstat` take feature selections + compute-time knobs
      (``n_jobs``, ``chunk_size``, etc.) and return per-feature results.

   The base class owns the attribute contract (``kernel_method_``,
   ``kernel_params_``, ``kernel_``, ``n``, ``_data_ready``) and enforces the
   workflow via :meth:`_require_setup`. Concrete subclasses implement
   :meth:`_merge_kernel_defaults`, :meth:`setup_data`, :meth:`compute_qstat`,
   and :meth:`compute_rstat`.



Classes
-------

.. autoapisummary::

   quadsv.detectors.base.Detector


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

.. py:class:: Detector(kernel_method, **kernel_params)

   Bases: :py:obj:`abc.ABC`


   Abstract base for single-sample pattern detectors.

   :ivar kernel_method\_: Kernel method name (e.g. ``'matern'``, ``'car'``). Set at construction.
   :vartype kernel_method\_: str
   :ivar kernel_params\_: Resolved kernel parameters after backend-specific defaults are merged
                          with user overrides. Set at construction.
   :vartype kernel_params\_: dict
   :ivar kernel\_: Kernel object built in :meth:`setup_data`. ``None`` before data setup.
   :vartype kernel\_: :class:`~quadsv.kernels.Kernel` or None
   :ivar n: Effective number of observations after preprocessing. ``None`` before
            data setup.

   :vartype n: int or None


   .. py:method:: compute_qstat(features = None, **kwargs)
      :abstractmethod:


      Univariate Q-test across ``features``.



   .. py:method:: compute_rstat(**kwargs)
      :abstractmethod:


      Bivariate R-test. Signature / feature selection are subclass-specific.



   .. py:method:: setup_data(data, **kwargs)
      :abstractmethod:


      Attach ``data``, preprocess features, and build :attr:`kernel_`.

      Must set :attr:`kernel_`, :attr:`n`, and ``self._data_ready = True``
      before returning ``self``.



   .. py:attribute:: kernel_
      :type:  quadsv.kernels.Kernel | None
      :value: None



   .. py:attribute:: kernel_method_
      :type:  str


   .. py:attribute:: kernel_params_
      :type:  dict


   .. py:attribute:: n
      :type:  int | None
      :value: None