Welcome

Welcome#

quadsv is a Python library for detecting spatial patterns in omics data. With it you can score how much each gene’s expression depends on space, find gene pairs that share a spatial pattern, and compare pattern shapes across slides, all through a single statistical framework.

The kernel you pass to the test decides what kind of spatial structure counts. A CAR or Matérn kernel rewards smooth gradients across the tissue. A graph-Laplacian kernel rewards sharp boundaries between neighbouring spots. See Kernel Design for how to pick one.

The library is built for spatial transcriptomics (Visium, Visium HD, MERFISH, Slide-seq, Xenium, …) but works with any data that has spatial or graph structure.

Key features#

  • Reliable. Uses positive-definite kernels, which avoid the false negatives that affect Moran’s I.

  • Scalable. Handles millions of spots through sparse solvers and FFT / NUFFT acceleration.

  • Flexible. Accepts arbitrary 2-D coordinates, regular grids, and precomputed graphs.

  • Integrated. Reads anndata.AnnData and spatialdata.SpatialData directly.

Quick example#

import numpy as np
from quadsv import NUFFTKernel, spatial_q_test

# Spatial coordinates and one gene's expression vector
rng = np.random.default_rng(0)
coords = rng.uniform(0, 20, size=(500, 2))
gene = rng.standard_normal(500)

# Build a Matérn kernel and test the gene for spatial variability
kernel = NUFFTKernel(coords, method="matern", bandwidth=2.0, nu=1.5)
Q, pval = spatial_q_test(gene, kernel)
print(f"Q = {Q:.4f}, p-value = {pval:.4e}")
What is the Q-statistic?

The Q-statistic \(Q = \mathbf{z}^\top \mathbf{K z}\) measures how strongly a feature’s values line up with the spatial structure encoded by the kernel K. A large Q means the feature is spatially structured in the way K looks for; a small Q means the feature is spatially independent under K. Different kernels look for different things: CAR and Matérn pick up smooth, large-scale variation, while a graph Laplacian picks up sharp, local variation. See Theoretical Results for the derivation and Kernel Design for picking a kernel.

Getting started#

Citation#

Su, Jiayu, et al. On the consistent and scalable detection of spatial patterns. arXiv:2602.02825 (2026).

Reporting issues#

Please open a ticket on the GitHub Issues page.

Contents