Metadata-Version: 2.4
Name: gsMap3D
Version: 0.1.2
Summary: Genetically informed spatial mapping of cells for complex traits
Project-URL: Home, https://github.com/Ganten-Hornby/gsMap3D
Project-URL: Documentation, https://yanglab.westlake.edu.cn/gsmap3d/docs
Project-URL: Website, https://yanglab.westlake.edu.cn/gsmap3d
Author-email: liyang <songliyang@westlake.edu.cn>, wenhao <chenwenhao@westlake.edu.cn>
License: MIT License
        
        Copyright (c) 2026 JianYang-Lab
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: anndata>=0.8.0
Requires-Dist: bitarray<3.0.0,>=2.9.2
Requires-Dist: distinctipy>=1.3.4
Requires-Dist: einops
Requires-Dist: h5py>=3.0.0
Requires-Dist: jax<1.0.0,>=0.7.2
Requires-Dist: jinja2
Requires-Dist: kaleido
Requires-Dist: matplotlib
Requires-Dist: numba>=0.60
Requires-Dist: numpy~=2.2
Requires-Dist: pandas-plink
Requires-Dist: pandas<3.0,>=2.0
Requires-Dist: plotly
Requires-Dist: psutil>=5.8.0
Requires-Dist: pyarrow
Requires-Dist: pyfiglet
Requires-Dist: pyranges1~=1.3.2
Requires-Dist: pyvista>=0.35.0
Requires-Dist: pyyaml
Requires-Dist: rich>=14.1.0
Requires-Dist: scanpy>=1.11.0
Requires-Dist: scipy>=1.11
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: torch-geometric~=2.7
Requires-Dist: torch~=2.5
Requires-Dist: tqdm
Requires-Dist: typer~=0.20.0
Requires-Dist: xarray
Requires-Dist: zarr>=2.18.0
Provides-Extra: cuda
Requires-Dist: jax[cuda13]<1.0.0,>=0.7.2; extra == 'cuda'
Provides-Extra: doc
Requires-Dist: furo; extra == 'doc'
Requires-Dist: myst-parser; extra == 'doc'
Requires-Dist: nbsphinx; extra == 'doc'
Requires-Dist: sphinx; extra == 'doc'
Requires-Dist: sphinx-argparse; extra == 'doc'
Requires-Dist: sphinx-autobuild; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-basic-ng; extra == 'doc'
Requires-Dist: sphinx-charts; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-inline-tabs; extra == 'doc'
Requires-Dist: sphinx-markdown-tables; extra == 'doc'
Requires-Dist: sphinx-rtd-theme; extra == 'doc'
Requires-Dist: sphinxcontrib-applehelp; extra == 'doc'
Requires-Dist: sphinxcontrib-devhelp; extra == 'doc'
Requires-Dist: sphinxcontrib-htmlhelp; extra == 'doc'
Requires-Dist: sphinxcontrib-jquery; extra == 'doc'
Requires-Dist: sphinxcontrib-jsmath; extra == 'doc'
Requires-Dist: sphinxcontrib-mermaid; extra == 'doc'
Requires-Dist: sphinxcontrib-qthelp; extra == 'doc'
Requires-Dist: sphinxcontrib-serializinghtml; extra == 'doc'
Provides-Extra: tests
Requires-Dist: coverage; extra == 'tests'
Requires-Dist: pytest-cov>=4.0.0; extra == 'tests'
Requires-Dist: pytest>=7.0.0; extra == 'tests'
Provides-Extra: tpu
Requires-Dist: jax[tpu]<1.0.0,>=0.7.2; extra == 'tpu'
Description-Content-Type: text/markdown

# gsMap3D

**gsMap3D** integrates 3D spatial transcriptomics (ST) data with genome-wide association study (GWAS) summary statistics to map cells associated with human complex traits and diseases.

______________________________________________________________________

## ✨ What's New

```text
- Support for 3D ST data mapping
- Dual-embedding strategy for more accurate gene specificity scoring
- Full GPU acceleration across all analysis steps
```

______________________________________________________________________

## 🚀 Features

- **Spatially-aware High-Resolution Trait Mapping**\
    Maps trait-associated cells at single-cell resolution, offering insights into their spatial distributions.

- **Spatial Region Identification**\
    Aggregates trait–cell association p-values into trait–tissue region association p-values, prioritizing tissue regions relevant to traits of interest.

- **Putative Causal Genes Identification**\
    Prioritizes putative causal genes by associating gene expression levels with cell–trait relevance.

- **Scalability**\
    Employs [JAX](https://github.com/google/jax) JIT and GPU/TPU acceleration to scale to million-scale cells (spots) spatial omics datasets.

______________________________________________________________________

## 🧠 Overview of `gsMap3D`

`gsMap3D` operates on a four-step process:

### 1. Gene Specificity Assessment in 3D Spatial Contexts

To address technical noise and capture spatial correlations of gene expression across consecutive ST sections,\
`gsMap3D` constructs batch-corrected dual embeddings of molecular and spatial features. These embeddings jointly model transcriptomic similarity and local spatial context to identify homogeneous cells in 3D space. Gene specificity scores (GSS) are then computed by aggregating normalized gene expression ranks across these 3D homogeneous cells, enabling robust identification of genes that are both highly and specifically expressed in focal cells.

### 2. Linking Gene Specificity to Genetic Variants

`gsMap3D` links gene specificity scores to single nucleotide polymorphisms (SNPs) by assigning GSS to SNPs based on their proximity to gene transcription start sites (TSS) and SNP-to-gene epigenetic linking maps, thereby connecting spatially resolved gene expression patterns with trait-associated genetic variation.

### 3. 3D Spatial S-LDSC for Cell–Trait Association

To quantify cell–trait associations in 3D space, `gsMap3D` integrates the 3D gene specificity scores with GWAS summary statistics using stratified LD score regression (S-LDSC). This framework enables the estimation of trait relevance for individual cells by associating their stratified LD scores with GWAS signals.

### 4. Spatial Region–Trait Association Analysis

To evaluate associations between traits and spatial regions, `gsMap3D` aggregates p-values from cells within a given 3D spatial region using the Cauchy combination test, yielding region-level association statistics that reflect coordinated genetic effects across spatially organized cell populations.

![gsMap3D Method Schematic](docs/source/_static/gsMap3D_Method_schematic.png)

______________________________________________________________________

## 📚 Documentation

Please see our [Documentation](https://yanglab.westlake.edu.cn/gsmap3d-portal/docs) and [Website](https://yanglab.westlake.edu.cn/gsmap3d-portal).

______________________________________________________________________

## 📝 How to Cite

If you use `gsMap3D` in your studies, please cite:

- **gsMap3D**: *to be updated.*

- **gsMap**:\
    Song, L., Chen, W., Hou, J., Guo, M. & Yang, J.\
    *Spatially resolved mapping of cells associated with human complex traits.*\
    **Nature** (2025).\
    [https://doi.org/10.1038/s41586-025-08757-x](https://doi.org/10.1038/s41586-025-08757-x)

______________________________________________________________________
