SpatialQuery 0.0.3__tar.gz → 0.0.5__tar.gz

spatialquery-0.0.5/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: SpatialQuery
+Version: 0.0.5
+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/)**
+
+## Reproducibility
+
+The following tutorials reproduce the main analyses presented in our manuscript:
+
+- [Mouse organogenesis — single-FOV analysis (seqFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_1.html)
+- [Kidney disease atlas — multi-condition analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_2.html)
+- [Colorectal cancer microenvironment — spatial proteomics (CODEX)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_3.html)
+- [Whole-brain atlas — large-scale analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_4.html)
+
+## 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)

spatialquery-0.0.5/README.md

@@ -0,0 +1,64 @@
+# 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/)**
+
+## Reproducibility
+
+The following tutorials reproduce the main analyses presented in our manuscript:
+
+- [Mouse organogenesis — single-FOV analysis (seqFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_1.html)
+- [Kidney disease atlas — multi-condition analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_2.html)
+- [Colorectal cancer microenvironment — spatial proteomics (CODEX)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_3.html)
+- [Whole-brain atlas — large-scale analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_4.html)
+
+## 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)

{spatialquery-0.0.3 → spatialquery-0.0.5}/SpatialQuery/spatial_query.py

@@ -31,39 +31,6 @@ class spatial_query:
 
     A class for performing spatial query analysis on spatial transcriptomics data of a single field of view,
     including pattern discovery, enrichment analysis, differential analysis, and gene-gene covariation assessment.
-
-    Parameters
-    ----------
-    adata : AnnData
-        Annotated data object containing expression matrix and metadata.
-    dataset : str, default='ST'
-        Dataset identifier.
-    spatial_key : str, default='X_spatial'
-        Key in adata.obsm containing spatial coordinates (n_obs, 2).
-    label_key : str, default='cell_type'
-        Key in adata.obs containing cell type annotations.
-    leaf_size : int, default=10
-        Leaf size parameter for KDTree construction. Larger values reduce tree depth
-        but increase computation per query.
-    build_gene_index : bool, default=False
-        If True, constructs SCFind index by compressing original data to binary format to save memory.
-        If False, uses original expression matrix from adata.X directly.
-    feature_name : str, default='gene'
-        Column name in adata.var containing feature identifiers.
-    if_lognorm : bool, default=True
-        If True, applies log1p transformation after library size normalization.
-        Set to False if expression data is already normalized and no more transformation is required.
-    if_normalize_spatial_coord : bool, default=True
-        If True, normalizes spatial coordinates so mean nearest neighbor distance equals 1.
-        This makes max_dist parameter interpretable as "number of cell diameters."
-        Set to False if original spatial units (e.g., micrometers) are required and
-        should be preserved for downstream analysis.
-
-    Notes
-    -----
-    When if_normalize_spatial_coord=True, the max_dist parameter in query functions
-    represents relative spatial scale (in units of mean nearest neighbor distance).
-    When if_normalize_spatial_coord=False, max_dist uses original coordinate units.
     """
     def __init__(
         self,
@@ -77,6 +44,42 @@ class spatial_query:
         if_lognorm: bool = True,
         if_normalize_spatial_coord: bool = True
         ):
+        """
+        Initialize spatial_query object.
+
+        Parameters
+        ----------
+        adata : AnnData
+            Annotated data object containing expression matrix and metadata.
+        dataset : str, default='ST'
+            Dataset identifier.
+        spatial_key : str, default='X_spatial'
+            Key in adata.obsm containing spatial coordinates (n_obs, 2).
+        label_key : str, default='cell_type'
+            Key in adata.obs containing cell type annotations.
+        leaf_size : int, default=10
+            Leaf size parameter for KDTree construction. Larger values reduce tree depth
+            but increase computation per query.
+        build_gene_index : bool, default=False
+            If True, constructs SCFind index by compressing original data to binary format to save memory.
+            If False, uses original expression matrix from adata.X directly.
+        feature_name : str, default='gene'
+            Column name in adata.var containing feature identifiers.
+        if_lognorm : bool, default=True
+            If True, applies log1p transformation after library size normalization.
+            Set to False if expression data is already normalized and no more transformation is required.
+        if_normalize_spatial_coord : bool, default=True
+            If True, normalizes spatial coordinates so mean nearest neighbor distance equals 1.
+            This makes max_dist parameter interpretable as "number of cell diameters."
+            Set to False if original spatial units (e.g., micrometers) are required and
+            should be preserved for downstream analysis.
+
+        Notes
+        -----
+        When if_normalize_spatial_coord=True, the max_dist parameter in query functions
+        represents relative spatial scale (in units of mean nearest neighbor distance).
+        When if_normalize_spatial_coord=False, max_dist uses original coordinate units.
+        """
         if spatial_key not in adata.obsm.keys() or label_key not in adata.obs.keys():
             raise ValueError(f"The Anndata object must contain {spatial_key} in obsm and {label_key} in obs.")
         
@@ -1533,6 +1536,7 @@ def interactive_motif(
     sp,
     zarr_path: str,
     spatialSpotRadius: float = 1,
+    use_adata_store: bool = False,
 ):
     """
     Create an interactive Vitessce widget to explore spatial motifs.
@@ -1555,6 +1559,9 @@ def interactive_motif(
     spatialSpotRadius : float, default=1
         Radius for spatial spots in the Vitessce visualization. Adjust based
         on data density and spatial coordinate scale.
+    use_adata_store : bool, default=False
+        If True, pass the zarr path via ``adata_store`` (for HubMAP workspace).
+        If False, pass via ``adata_path`` (for local usage).
 
     Returns
     -------
@@ -1635,8 +1642,9 @@ def interactive_motif(
 
     vc = VitessceConfig(schema_version="1.0.16", name="SpatialQuery")
 
+    _adata_key = "adata_store" if use_adata_store else "adata_path"
     wrapper_kwargs = dict(
-        adata_path=zarr_path,
+        **{_adata_key: zarr_path},
         obs_set_paths=[f"obs/{label_key}"],
         obs_set_names=["Cell Type"],
         obs_spots_path=f"obsm/{spatial_key}",
@@ -1649,7 +1657,6 @@ def interactive_motif(
     dataset = vc.add_dataset("Query results").add_object(AnnDataWrapper(**wrapper_kwargs))
 
     spatial_view = vc.add_view("spatialBeta", dataset=dataset)
-    lc_view = vc.add_view("layerControllerBeta", dataset=dataset)
     sets_view = vc.add_view("obsSets", dataset=dataset)
     sq_view = vc.add_view("spatialQuery", dataset=dataset)
     sq_heatmap_view = vc.add_view("spatialQueryHeatmap", dataset=dataset)
@@ -1658,7 +1665,7 @@ def interactive_motif(
         ["Cell Type", ct] for ct in sp.labels.unique().tolist()
     ]
 
-    linked_views = [spatial_view, lc_view, sets_view, sq_view]
+    linked_views = [spatial_view, sets_view, sq_view]
     if has_expression:
         features_view = vc.add_view("featureList", dataset=dataset)
         linked_views.append(features_view)
@@ -1669,21 +1676,21 @@ def interactive_motif(
         [plugin.additional_obs_sets, plugin.obs_set_color, initial_obs_set_selection, "cellSetSelection"],
     )
 
-    vc.link_views_by_dict([spatial_view, lc_view], {
+    vc.link_views_by_dict([spatial_view], {
         "spotLayer": CL([{"obsType": "cell", "spatialSpotRadius": spatialSpotRadius}]),
     })
 
     if has_expression:
         vc.layout(
             vconcat(
-                hconcat(spatial_view, vconcat(lc_view, features_view)),
+                hconcat(spatial_view, features_view, split=[2, 1]),
                 hconcat(sets_view, sq_heatmap_view, sq_view),
             )
         )
     else:
         vc.layout(
             vconcat(
-                hconcat(spatial_view, lc_view),
+                spatial_view,
                 hconcat(sets_view, sq_heatmap_view, sq_view),
             )
         )

spatialquery-0.0.5/SpatialQuery.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: SpatialQuery
+Version: 0.0.5
+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/)**
+
+## Reproducibility
+
+The following tutorials reproduce the main analyses presented in our manuscript:
+
+- [Mouse organogenesis — single-FOV analysis (seqFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_1.html)
+- [Kidney disease atlas — multi-condition analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_2.html)
+- [Colorectal cancer microenvironment — spatial proteomics (CODEX)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_3.html)
+- [Whole-brain atlas — large-scale analysis (MERFISH)](https://spatialquery.readthedocs.io/en/latest/tutorials/tutorial_4.html)
+
+## 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)

{spatialquery-0.0.3 → spatialquery-0.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "SpatialQuery"
-version = "0.0.3"
+version = "0.0.5"
 description = "Spatial query tools for analyzing spatial transcriptomics data"
 readme = "README.md"
 license = "MIT"
@@ -37,6 +37,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://github.com/ShaokunAn/Spatial-Query"
+Documentation = "https://spatial-query.readthedocs.io"
 
 [project.optional-dependencies]
 docs = [