splisosm.kernel
===============

.. py:module:: splisosm.kernel

.. autoapi-nested-parse::

   Spatial kernel abstractions.



Classes
-------

.. autoapisummary::

   splisosm.kernel.SpatialCovKernel


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

.. py:class:: SpatialCovKernel(coords, k_neighbors = 4, model = 'icar', rho = 0.99, standardize_cov = True, centering = False, approx_rank = None)

   Bases: :py:obj:`Kernel`


   Graph-based spatial covariance kernel built from spot coordinates.

   :param coords: Spot coordinates of shape (n_spots, 2).
   :param k_neighbors: Number of nearest neighbors used to build the graph.
   :param model: Spatial process model for inverse covariance construction. Supported
                 values are ``'icar'``, ``'car'``, ``'isar'``, and ``'sar'``.
   :param rho: Spatial autocorrelation coefficient.
   :param standardize_cov: If True, scales covariance to unit marginal variance.
   :param centering: If True, applies centering so row/column sums are approximately
                     zero.
   :param approx_rank: If provided, computes and stores a rank-`approx_rank` factorization.


   .. py:method:: eigendecomposition()

      Compute and store eigendecomposition of the dense kernel.

      :raises ValueError: If only low-rank kernel factors are stored.



   .. py:method:: eigenvalues(k = None)

      Return leading eigenvalues of the kernel matrix.

      :param k: Number of leading eigenvalues to return. If None, all
                available eigenvalues are returned.

      :returns: Eigenvalues sorted in descending order.
      :rtype: torch.Tensor



   .. py:method:: rank()

      Return effective rank of the kernel representation.

      :returns: Kernel rank.
      :rtype: int



   .. py:method:: realization()

      Return the realized dense kernel matrix.

      :returns: Dense matrix of shape (n_spots, n_spots).
      :rtype: torch.Tensor



   .. py:method:: shape()

      Return kernel shape.

      :returns: Pair (n_spots, n_spots).
      :rtype: tuple of int



   .. py:method:: xtKx(x)

      Compute the kernel quadratic form for multivariate inputs.

      :param x: Input matrix of shape (n_spots, d).
      :type x: torch.Tensor

      :returns: Quadratic form of shape (d, d).
      :rtype: torch.Tensor



   .. py:attribute:: K_sp
      :type:  torch.Tensor | None

      Dense kernel matrix of shape (n_spots, n_spots) when full-rank storage is used.
      ``None`` when low-rank storage is used.


   .. py:attribute:: Q
      :type:  torch.Tensor | None

      Low-rank factor of shape (n_spots, rank) such that ``K_sp ~= Q @ Q.T``.
      ``None`` when full-rank storage is used.


   .. py:attribute:: inv_cov
      :type:  torch.Tensor

      Sparse precision matrix (aka inverse spatial kernel) of shape (n_spots, n_spots).