Metadata-Version: 2.4
Name: spatialsnake
Version: 0.0.4
Summary: A Python package for spatial transcriptomics analysis workflows.
Home-page: https://github.com/l-zh007/spatialsnake
Author: lzh
Author-email: lzh <l-zh007@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/l-zh007/spatialsnake
Project-URL: Issues, https://github.com/l-zh007/spatialsnake/issues
Keywords: spatial transcriptomics,bioinformatics,snakemake,spatialdata
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools<81,>=80.9.0
Requires-Dist: spatialdata>=0.5.0
Requires-Dist: spatialdata-io>=0.3.0
Requires-Dist: spatialdata-plot>=0.2.11
Requires-Dist: squidpy>=1.6.5
Requires-Dist: napari-spatialdata>=0.5.7
Requires-Dist: numpy>=2.2.6
Requires-Dist: scanpy>=1.10.4
Requires-Dist: anndata>=0.12.0
Requires-Dist: umap-learn>=0.5.7
Requires-Dist: pandas>=2.2.3
Requires-Dist: scipy>=1.13.1
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: numba>=0.62.1
Requires-Dist: llvmlite>=0.45.1
Requires-Dist: shapely>=2.1.1
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: seaborn>=0.13.2
Requires-Dist: plotnine>=0.15.0
Requires-Dist: Pillow>=11.3.0
Requires-Dist: cell2location>=0.1.5
Requires-Dist: scvi-tools>=1.4.0
Requires-Dist: zarr>=2.18.7
Requires-Dist: h5py>=3.14.0
Requires-Dist: tifffile>=2025.8.28
Requires-Dist: imageio>=2.37.0
Requires-Dist: ome-zarr>=0.11.1
Requires-Dist: statsmodels>=0.14.5
Requires-Dist: Pint>=0.25
Requires-Dist: pyarrow>=21.0.0
Requires-Dist: click>=8.3.0
Requires-Dist: typer>=0.16.0
Requires-Dist: docopt>=0.6.2
Requires-Dist: PyYAML>=6.0.3
Requires-Dist: geosketch>=1.3
Requires-Dist: cell2location>=0.1.5
Requires-Dist: geopandas>=1.1.1
Requires-Dist: pydeseq2>=0.5.2
Requires-Dist: harmonypy>=0.0.10
Requires-Dist: igraph>=0.11.9
Requires-Dist: louvain>=0.8.2
Provides-Extra: extended
Requires-Dist: scikit-misc>=0.5.2; extra == "extended"
Requires-Dist: dask-image>=2024.5.3; extra == "extended"
Requires-Dist: ipython>=9.5.0; extra == "extended"
Requires-Dist: pyogrio>=0.12.1; extra == "extended"
Requires-Dist: pooch>=1.8.2; extra == "extended"
Requires-Dist: dask>=2024.11.2; extra == "extended"
Requires-Dist: dask-expr>=1.1.19; extra == "extended"
Requires-Dist: pims>=0.7; extra == "extended"
Requires-Dist: xarray>=2025.1.2; extra == "extended"
Requires-Dist: pyro-ppl>=1.9.1; extra == "extended"
Requires-Dist: pyro-api>=0.1.1; extra == "extended"
Requires-Dist: opt-einsum>=3.3.0; extra == "extended"
Requires-Dist: cellphonedb>=5.0.1; extra == "extended"
Requires-Dist: torch>=2.8.0; extra == "extended"
Requires-Dist: pytorch-lightning>=2.5.5; extra == "extended"
Requires-Dist: cellcharter>=0.3.5; extra == "extended"
Requires-Dist: cytoolz>=1.0.1; extra == "extended"
Requires-Dist: ktplotspy>=0.3.3; extra == "extended"
Requires-Dist: liana>=1.6.1; extra == "extended"
Requires-Dist: loompy>=3.0.8; extra == "extended"
Requires-Dist: pyscenic>=0.12.1; extra == "extended"
Requires-Dist: leidenalg; extra == "extended"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<p align="center"> 
  <img src="spatialsnake-logo.png" alt="spatialsnake logo" width="760">
</p>

<p align="center">
  <img
    width="820"
    src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=500&size=16&duration=3200&pause=1100&color=4C78A8&center=true&vCenter=true&width=820&lines=Unified+SpatialData-based+workflows+across+spatial+platforms;Decision-guided+modules+from+data+ingestion+to+annotation;Reproducible+single-sample+and+cross-sample+analysis;Modular+tools+for+integration%2C+transformation%2C+and+comparison"
    alt="Spatialsnake workflow features"
  />
</p>

<p align="center">
  <a href="https://spatialsnake-tutorial.readthedocs.io/en/latest/">
    <img src="https://img.shields.io/badge/docs-Read%20the%20Documentation-blue" alt="Documentation">
  </a>
  <a href="https://pypi.org/project/spatialsnake/">
    <img src="https://img.shields.io/pypi/v/spatialsnake" alt="PyPI">
  </a>
  <a href="https://snakemake.github.io">
    <img src="https://img.shields.io/badge/snakemake-%E2%89%A58.0.0-brightgreen.svg" alt="Snakemake">
  </a>
</p>

<p align="center">
  A Snakemake workflow for spatial transcriptomics powered by the <code>spatialdata</code> framework.
</p>

`spatialsnake` is an automated pipeline for `spatial transcriptomics` analysis. Implemented in `Python` on top of the `scverse` ecosystem, it uses SpatialData to convert datasets from multiple spatial transcriptomics platforms into a unified `zarr`-based object format. This design supports a consistent workflow spanning data ingestion, preprocessing, clustering, annotation, and downstream analysis through a command-line interface with workflow-based parameter control.

## Project at a Glance

| Item | Summary |
| --- | --- |
| Official Documentation | [spatialsnake Documentation](https://spatialsnake-tutorial.readthedocs.io/en/latest/) |
| Tutorial Article | [Core Analysis Tutorial](https://spatialsnake-tutorial.readthedocs.io/en/latest/core_analysis/index.html) |
| Workflow Modes | `single_analysis`, `compare_analysis` |
| Utility Entry Points | `useful_tool`, `produce-file`, `install-packages` |
| Main Analysis Options | `integrate`, `preprocess`, `clustering`, `reclustering`, `annotation_help`, `annotation`, `advance_analysis`, `compare_stage` |
| Supported Input Types | `visium`, `visium_segment`, `visium_HD`, `xenium`, `Merfish`, `stereo_seq` |

## Core Functions

- Standardize raw spatial transcriptomics data into a unified object during `Ingesting`.
- Run `preprocess` for quality control, filtering, normalization, and dimensionality reduction preparation.
- Perform `clustering` and visualization, followed by `annotation_help` and `annotation`.
- Carry out `reclustering` and `reannotation` for clusters of interest.
- Execute `advance_analysis` for downstream analyses and `compare_stage` for cross-sample comparison.
- Use auxiliary utilities for `splitting`, `merge`, and `transform`.

## Available Platforms

### Sequencing-based

- `visium`: 10x Genomics spatial transcriptomics data
- `visium_HD`: high-resolution 10x Genomics spatial transcriptomics data
- `visium_segment`: cell segmentation outputs from 10x Genomics Space Ranger
- `stereo_seq`: BGI Stereo-seq spatial transcriptomics data, including different bin sizes, `cellbin`, and adjusted `cellbin` data types

### Imaging-based

- `xenium`: image-based 10x Genomics Xenium spatial transcriptomics data
- `Merfish`: Vizgen MERFISH spatial transcriptomics data

## Basic Installation

### 1. Create the base conda environment

```bash
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
conda create -n spatialsnake_env python=3.12.11 snakemake-minimal=9.8.1 r-base=4.4.0 -y
conda activate spatialsnake_env
```

### 2. Install the documented core dependencies

```bash
conda install -c conda-forge r-optparse r-tidyverse r-future r-jsonlite r-rcolorbrewer r-patchwork r-cowplot r-pheatmap r-seurat r-remotes r-biocmanager r-presto r-nmf r-circlize
conda install -c bioconda bioconductor-annotationdbi bioconductor-complexheatmap bioconductor-clusterprofiler bioconductor-edger bioconductor-org.hs.eg.db bioconductor-org.mm.eg.db bioconductor-rhdf5 bioconductor-biocneighbors
conda install -c conda-forge bbknn cython
```

### 3. Install `spatialsnake`

#### Option 1. Install from PyPI

```bash
pip install spatialsnake
spatialsnake --version
```

#### Option 2. Install from conda

Use this as a fresh conda-native install path instead of the manual dependency
steps above:

```bash
conda create -n spatialsnake_env -c conda-forge -c bioconda spatialsnake -y
conda activate spatialsnake_env
spatialsnake --version
spatialsnake install-packages
```

#### Option 3. Install from source code

```bash
git clone https://github.com/zhenghlin/spatialsnake.git
cd spatialsnake
python -m pip install .
python -m pip install ".[extended]"
spatialsnake --version
```

### 4. Optional extended package step

For PyPI or source installs:

```bash
pip install "spatialsnake[extended]"
spatialsnake install-packages
```

For conda installs:

```bash
spatialsnake install-packages --extended
```

With the minimal installation, the documented workflow includes `integrate`, `preprocess`, `clustering`, `reclustering`, `annotation_help`, `annotation`, `reannotation`, and utility operations for merge and split. For conda installs, `spatialsnake install-packages` completes the minimal pip-only core packages; `spatialsnake install-packages --extended` adds downstream Python packages, `pybanksy`, and R/GitHub packages for documented extended components including `compare_stage`, `transform`, `banksy`, and `cellchat`-related workflows. For PyPI installs, keep using `pip install "spatialsnake[extended]"` before `spatialsnake install-packages`.

## Working Directory

Prepare the working directory before running the main workflow:

```text
project_root/
├── data/
├── sample.txt
├── results/
└── <analysis_option>.yaml
```

```bash
mkdir -p project_root/data project_root/results
touch project_root/sample.txt
```

`sample.txt` is the required sample information table for every module in the main workflow. In the working directory, `data/` stores raw input data, `results/` stores analysis outputs generated by the workflow, and `<analysis_option>.yaml` is an optional configuration file.

## Minimal Usage

The command-line interface provides the following documented entry points:

```bash
spatialsnake <command> <INPUT> <TYPE> [--option=<analysis_option>] [options]
spatialsnake useful_tool [--option=<ways>] <INPUT> [options]
spatialsnake produce-file [--option=<analysis_option>]
spatialsnake install-packages [--extended] [--dry-run]
spatialsnake (-h | --help)
spatialsnake --version
```

Main workflow selection:

- `<command>`: choose `single_analysis` or `compare_analysis`
- `<TYPE>`: choose from `visium`, `visium_segment`, `visium_HD`, `xenium`, `Merfish`, and `stereo_seq`
- `--option=<analysis_option>`: choose from `integrate`, `preprocess`, `clustering`, `reclustering`, `annotation_help`, `annotation`, `advance_analysis`, and `compare_stage`

Configuration files can be generated with:

```bash
spatialsnake produce-file --option=<analysis_option>
```

The generated YAML template can then be applied with `--configfile`. Parameters provided directly on the command line take priority over parameters defined in the YAML file.

## Further Reading

- Read the full [official documentation](https://spatialsnake-tutorial.readthedocs.io/en/latest/).
- Start from the example-based [core analysis tutorial](https://spatialsnake-tutorial.readthedocs.io/en/latest/core_analysis/index.html).
- If you encounter problems or would like to suggest extensions, please [open an issue on GitHub](https://github.com/l-zh007/spatialsnake/issues).

## Reference

> Köster, J., Mölder, F., Jablonski, K. P., Letcher, B., Hall, M. B., Tomkins-Tinch, C. H., Sochat, V., Forster, J., Lee, S., Twardziok, S. O., Kanitz, A., Wilm, A., Holtgrewe, M., Rahmann, S., and Nahnsen, S. *Sustainable data analysis with Snakemake*. F1000Research, 10:33, 2021. https://doi.org/10.12688/f1000research.29032.2
