Metadata-Version: 2.4
Name: SpatialQuery
Version: 0.0.4
Summary: Spatial query tools for analyzing spatial transcriptomics data
Author-email: Shaokun An <shan12@bwh.harvard.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ShaokunAn/Spatial-Query
Project-URL: Documentation, https://spatial-query.readthedocs.io
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23.0
Requires-Dist: anndata>=0.8.0
Requires-Dist: pandas>=2.0.3
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.5
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: scanpy>=1.9.5
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: mlxtend>=0.23.1
Requires-Dist: tqdm>=4.60.0
Requires-Dist: zarr>=2.14.0
Provides-Extra: docs
Requires-Dist: sphinx>=5.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# SpatialQuery

SpatialQuery is a Python package for systematic spatial analysis of single-cell resolution spatial omics data. It provides a unified framework to discover, quantify, and compare recurring spatial cell type patterns — termed *motifs* — across single or multiple fields of view (FOVs).

Starting from annotated spatial omics datasets (spatial transcriptomics and spatial proteomics data), SpatialQuery constructs cell neighborhoods using KNN or distance-based approaches and mines frequent cell type co-occurrence patterns via the FP-Growth algorithm. It then tests whether these motifs are statistically enriched beyond what is expected by chance, and supports comparison of motif compositions across biological conditions (e.g., healthy vs. disease) through differential motif analysis.

Beyond spatial structure, SpatialQuery links motifs to molecular phenotypes. For cells participating in a given motif, it performs motif-associated differential expression analysis to identify genes whose expression differs between motif-positive and motif-negative cells or across conditions. It further detects cross-cell gene-gene covariation — spatially dependent correlations between gene expression in anchor cells and their neighbors — to reveal intercellular signaling relationships that are specific to particular spatial contexts.

Key capabilities include:

- **Spatial motif discovery**: Identify frequent cell type patterns in local neighborhoods
- **Motif enrichment analysis**: Statistically test whether motifs occur more than expected
- **Differential motif analysis**: Compare spatial compositions across conditions
- **Motif-associated differential expression**: Find DE genes linked to specific motifs
- **Cross-cell gene-gene covariation**: Detect spatially dependent intercellular gene correlations
- **Multi-FOV support**: Pool and compare results across multiple tissue sections or samples

## Installation

```bash
pip install SpatialQuery
```

## Documentation

Full documentation, tutorials, and API reference: **[https://spatialquery.readthedocs.io/en/latest/](https://spatialquery.readthedocs.io/en/latest/)**

## Quick Start

```python
from SpatialQuery import spatial_query

# Single FOV analysis
sq = spatial_query(adata, spatial_key="X_spatial", label_key="cell_type", feature_name="gene")
enrich_motif = sq.motif_enrichment_dist(ct="T_cell", max_dist=10, min_support=0.5)
```

```python
from SpatialQuery import spatial_query_multi

# Multi-FOV analysis
spm = spatial_query_multi(adatas=adatas, datasets=datasets,
                          spatial_key="X_spatial", label_key="cell_type", feature_name="gene")
enrich_motif = spm.motif_enrichment_dist(ct="T_cell", dataset="healthy", max_dist=10, min_support=0.5)
```

## License

MIT

## Contact

- **Author**: Shaokun An
- **Email**: shaokunan1@gmail.com
- **GitHub**: [ShaokunAn](https://github.com/ShaokunAn)
