gsMap3D 0.1.0__tar.gz

gsmap3d-0.1.0/.gitignore

@@ -0,0 +1,253 @@
+### JetBrains+all template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+.claude/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### JupyterNotebooks template
+# gitignore template for Jupyter Notebooks
+# website: http://jupyter.org/
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Remove previous ipynb_checkpoints
+#   git rm -r .ipynb_checkpoints/
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# vscode
+.vscode
+run_gsmap3d.py

gsmap3d-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+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.

gsmap3d-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: gsMap3D
+Version: 0.1.0
+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>=2.0
+Requires-Dist: plotly
+Requires-Dist: psutil>=5.8.0
+Requires-Dist: pyarrow
+Requires-Dist: pyfiglet
+Requires-Dist: pyranges1~=1.2.0
+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)
+
+______________________________________________________________________

gsmap3d-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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)
+
+______________________________________________________________________