quadsv.detectors.grid

quadsv.detectors.grid#

Classes#

DetectorGrid

Detect spatial patterns on regular grids (SpatialData bins) with

Module Contents#

class quadsv.detectors.grid.DetectorGrid(kernel_method='car', **kernel_params)[source]#

Bases: quadsv.detectors.base.Detector

Detect spatial patterns on regular grids (SpatialData bins) with FFT-accelerated kernel tests.

Univariate (Q-test) and bivariate (R-test) kernel-based spatial statistics on rasterized spatialdata.SpatialData bins.

Workflow#

  1. Construct with kernel method + kernel hyperparameters / grid controls.

  2. Setup with setup_data() passing the spatialdata.SpatialData plus the bin / table / col / row keys. Setup rasterizes the table and builds the FFTKernel at the resulting grid shape.

  3. Compute with compute_qstat() / compute_rstat().

param kernel_method:

One of 'gaussian', 'matern', 'moran', 'graph_laplacian', 'car'.

type kernel_method:

str, default 'car'

param **kernel_params:

Kernel hyperparameters plus grid controls (spacing, topology, fft_solver, workers). See FFTKernel.

ivar sdata:

Input container set by setup_data().

vartype sdata:

spatialdata.SpatialData or None

ivar min_count:

Feature count threshold; set by setup_data().

vartype min_count:

int or None

ivar kernel_:

Built in setup_data() once the grid shape is known.

vartype kernel_:

FFTKernel or None

ivar kernel_method_, kernel_params_, n:

See Detector.

Examples

>>> det = DetectorGrid(kernel_method='car', rho=0.8)
>>> det.setup_data(sdata, bins='grid', table_name='table',
...                col_key='col_idx', row_key='row_idx')  
>>> q = det.compute_qstat(features=['Gene_1', 'Gene_2'])
compute_qstat(features=None, n_jobs='auto', workers='auto', return_pval=True, chunk_size='auto', show_progress=True)[source]#

Compute the spatial Q-statistic across features in parallel.

Requires setup_data() to have been called; rasterization and kernel construction happen there. This method pulls the rasterized feature tensor from sdata and runs per-feature FFT Q-tests.

Parameters:

  • features (list of str, optional) – Feature names to analyze. None uses all features that pass the min_count filter from setup_data().

  • n_jobs (int or 'auto', default 'auto') – Joblib workers over feature batches. 'auto' balances against workers — see _auto_schedule(). -1 is also accepted and behaves like 'auto'.

  • workers (int, 'auto', or None, default 'auto') – Threads for scipy.fft inside each worker. 'auto' co-balances with n_jobs; None defers to scipy’s default.

  • return_pval (bool, default True) – Whether to compute p-values + Benjamini–Hochberg–adjusted p-values.

  • chunk_size (int or 'auto', default 'auto') – Features per worker batch. 'auto' resolves to ~256 MB / (ny·nx·24) via _auto_chunk_size() and clips to [16, 1024].

  • show_progress (bool, default True) – Show a tqdm progress bar over worker chunks.

Returns:

Indexed by feature. Columns: Q, Z_score, and (if return_pval=True) P_value, P_adj. Sorted by Q desc.

Return type:

DataFrame

compute_rstat(features_x=None, features_y=None, return_pval=True, chunk_size='auto', workers='auto', show_progress=True)[source]#

Compute the bivariate spatial R-statistic across feature pairs.

Requires setup_data() to have been called.

Parameters:

  • features_x (list of str, optional) – Features for the X variable. If None and features_y is None, uses all features (symmetric pairwise mode).

  • features_y (list of str, optional) – Features for the Y variable. If None, pairs are drawn from features_x (symmetric, upper-triangular). If provided, returns all X × Y pairs (bipartite).

  • return_pval (bool, default True) – Whether to compute p-values + Benjamini–Hochberg–adjusted p-values.

  • chunk_size (int or 'auto', default 'auto') – Y-features per batch (reuses the pre-computed K @ Y block). 'auto' targets ~256 MB per embedding batch via _auto_chunk_size().

  • workers (int, 'auto', or None, default 'auto') – Threads for scipy.fft inside the embedding pass. 'auto' gives every FFT all CPU cores (the R-test loop is sequential over X/Y chunk pairs so there is no joblib contention).

  • show_progress (bool, default True) – Show a tqdm progress bar over X chunks.

Returns:

Columns Feature_1, Feature_2, R, Z_score and (if return_pval=True) P_value, P_adj. Sorted by R desc.

Return type:

DataFrame

setup_data(sdata, *, bins, table_name, col_key, row_key, value_key=None, min_count=None)[source]#

Attach sdata, rasterize the chosen bins table, and build the FFTKernel.

Parameters:

  • sdata (spatialdata.SpatialData) – Input container.

  • bins (str) – Name of the SpatialElement (Shape) defining the grid-like bins.

  • table_name (str) – Name of the table annotating the SpatialElement in sdata.tables.

  • col_key (str) – .obs columns holding integer column / row indices for the bins.

  • row_key (str) – .obs columns holding integer column / row indices for the bins.

  • value_key (str, optional) – Value column in .obs to rasterize. None uses counts / presence.

  • min_count (int, optional) – Minimum total count for a feature to pass filtering. None disables.

Returns:

self

Return type:

DetectorGrid

min_count: int | None = None[source]#

Minimum total count per feature applied in setup_data().

sdata: SpatialData | None = None[source]#

Reference to the input spatialdata.SpatialData, set by setup_data().

Parameters:

  • kernel_method (str)

  • kernel_params (Any)

Contents