Metadata-Version: 2.4
Name: scviva-tools
Version: 0.1.5
Summary: Consolidated spatial transcriptomics analysis toolkit with variational inference methods
Project-URL: Bug Tracker, https://github.com/YosefLab/scviva-tools/issues
Project-URL: Documentation, https://github.com/YosefLab/scviva-tools
Project-URL: Source, https://github.com/YosefLab/scviva-tools
Author-email: Ori Kronfeld <ori.kronfeld@weizmann.ac.il>
Maintainer-email: Ori Kronfeld <ori.kronfeld@weizmann.ac.il>
License: BSD 3-Clause License
        
        Copyright (c) 2026, Ori Kronfeld, Weizmann Institute of Science
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: deconvolution,deep learning,single-cell,spatial transcriptomics,variational inference
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.12
Requires-Dist: anndata>=0.11
Requires-Dist: lightning>=2
Requires-Dist: numpy>=2
Requires-Dist: pandas>=2
Requires-Dist: pyro-ppl>=1.8
Requires-Dist: rich>=12
Requires-Dist: scanpy[skmisc]>=1.10
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.12
Requires-Dist: scvi-tools>=1.4
Requires-Dist: sparse>=0.14
Requires-Dist: torch>=2
Requires-Dist: tqdm>=4.60
Provides-Extra: all
Requires-Dist: cell2location; extra == 'all'
Requires-Dist: coverage; extra == 'all'
Requires-Dist: cugraph>=24; extra == 'all'
Requires-Dist: cuml>=24; extra == 'all'
Requires-Dist: cupy-cuda12x; extra == 'all'
Requires-Dist: geomloss; extra == 'all'
Requires-Dist: igraph; extra == 'all'
Requires-Dist: ipykernel; extra == 'all'
Requires-Dist: ipython; extra == 'all'
Requires-Dist: jupyter; extra == 'all'
Requires-Dist: leidenalg; extra == 'all'
Requires-Dist: matplotlib; extra == 'all'
Requires-Dist: myst-nb; extra == 'all'
Requires-Dist: myst-parser; extra == 'all'
Requires-Dist: numba; extra == 'all'
Requires-Dist: plotnine; extra == 'all'
Requires-Dist: pooch; extra == 'all'
Requires-Dist: pre-commit; extra == 'all'
Requires-Dist: pynndescent; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest-pretty; extra == 'all'
Requires-Dist: pytest>=7; extra == 'all'
Requires-Dist: rapids-singlecell[rapids]; extra == 'all'
Requires-Dist: scrublet; extra == 'all'
Requires-Dist: seaborn; extra == 'all'
Requires-Dist: spatialdata>=0.2; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints; extra == 'all'
Requires-Dist: sphinx-book-theme>=1.0.1; extra == 'all'
Requires-Dist: sphinx-copybutton; extra == 'all'
Requires-Dist: sphinx-design; extra == 'all'
Requires-Dist: sphinx<9; extra == 'all'
Requires-Dist: sphinxcontrib-bibtex; extra == 'all'
Requires-Dist: squidpy>=1.4; extra == 'all'
Requires-Dist: statsmodels; extra == 'all'
Requires-Dist: torch-geometric; extra == 'all'
Requires-Dist: twine>=4.0.2; extra == 'all'
Requires-Dist: umap-learn>=0.5; extra == 'all'
Provides-Extra: cuda
Requires-Dist: mlx[cuda]; extra == 'cuda'
Requires-Dist: torchaudio; extra == 'cuda'
Requires-Dist: torchvision; extra == 'cuda'
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: twine>=4.0.2; extra == 'dev'
Provides-Extra: doc
Requires-Dist: ipykernel; extra == 'doc'
Requires-Dist: ipython; extra == 'doc'
Requires-Dist: myst-nb; extra == 'doc'
Requires-Dist: myst-parser; extra == 'doc'
Requires-Dist: pooch; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-book-theme>=1.0.1; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-design; extra == 'doc'
Requires-Dist: sphinx<9; extra == 'doc'
Requires-Dist: sphinxcontrib-bibtex; extra == 'doc'
Provides-Extra: file-sharing
Requires-Dist: fcswrite; extra == 'file-sharing'
Requires-Dist: gdown; extra == 'file-sharing'
Requires-Dist: pooch; extra == 'file-sharing'
Requires-Dist: readfcs; extra == 'file-sharing'
Provides-Extra: hub
Requires-Dist: boto3; extra == 'hub'
Requires-Dist: dvc[s3]; extra == 'hub'
Requires-Dist: huggingface-hub; extra == 'hub'
Provides-Extra: metal
Requires-Dist: mlx-metal; extra == 'metal'
Requires-Dist: torchaudio; extra == 'metal'
Requires-Dist: torchvision; extra == 'metal'
Provides-Extra: rapids
Requires-Dist: cugraph>=24; extra == 'rapids'
Requires-Dist: cuml>=24; extra == 'rapids'
Requires-Dist: cupy-cuda12x; extra == 'rapids'
Requires-Dist: rapids-singlecell[rapids]; extra == 'rapids'
Provides-Extra: spatial
Requires-Dist: geomloss; extra == 'spatial'
Requires-Dist: numba; extra == 'spatial'
Requires-Dist: pooch; extra == 'spatial'
Requires-Dist: pynndescent; extra == 'spatial'
Requires-Dist: seaborn; extra == 'spatial'
Requires-Dist: spatialdata>=0.2; extra == 'spatial'
Requires-Dist: squidpy>=1.4; extra == 'spatial'
Requires-Dist: statsmodels; extra == 'spatial'
Requires-Dist: torch-geometric; extra == 'spatial'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-pretty; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: tpu
Requires-Dist: torch-xla[tpu]; extra == 'tpu'
Provides-Extra: tutorials
Requires-Dist: cell2location; extra == 'tutorials'
Requires-Dist: geomloss; extra == 'tutorials'
Requires-Dist: igraph; extra == 'tutorials'
Requires-Dist: jupyter; extra == 'tutorials'
Requires-Dist: leidenalg; extra == 'tutorials'
Requires-Dist: matplotlib; extra == 'tutorials'
Requires-Dist: numba; extra == 'tutorials'
Requires-Dist: plotnine; extra == 'tutorials'
Requires-Dist: pooch; extra == 'tutorials'
Requires-Dist: pynndescent; extra == 'tutorials'
Requires-Dist: scrublet; extra == 'tutorials'
Requires-Dist: seaborn; extra == 'tutorials'
Requires-Dist: spatialdata>=0.2; extra == 'tutorials'
Requires-Dist: squidpy>=1.4; extra == 'tutorials'
Requires-Dist: statsmodels; extra == 'tutorials'
Requires-Dist: torch-geometric; extra == 'tutorials'
Requires-Dist: umap-learn>=0.5; extra == 'tutorials'
Description-Content-Type: text/markdown

# scviva-tools

Consolidated spatial transcriptomics analysis toolkit based on [scvi-tools](https://scvi-tools.org).

Provides seven spatial transcriptomics models and tools as first-class citizens:
- **scVIVA** — niche-aware representation learning (Levy et al., 2025)
- **DestVI** — multi-resolution cell-type deconvolution (Lopez et al., 2022)
- **ResolVI** — noise and bias correction for cellular-resolution ST (Ergen & Yosef, 2025)
- **GIMVI** — joint imputation of missing genes across paired scRNA-seq and spatial data (Lopez et al., 2019)
- **Stereoscope** — probabilistic cell-type deconvolution of spatial spots (Andersson et al., 2020)
- **Tangram** — mapping scRNA-seq data onto spatial coordinates (Biancalani et al., 2021)
- **Harreman** — metabolic exchange and cell-cell communication inference for spatial data (Etxezarreta-Arrastoa et al., 2025), integrating outputs from DestVI, ResolVI, and SCVIVA

See [docs/user_guide/models](docs/user_guide/models) for a full description of each model, and
[docs/tutorials](docs/tutorials) for worked examples of every model above.

## Installation

```bash
pip install scviva-tools

# Optional extras
pip install "scviva-tools[spatial]"    # SpatialData + squidpy integration
pip install "scviva-tools[rapids]"     # GPU-accelerated neighbor graphs (cuML/cuPy/cuGraph)
pip install "scviva-tools[tutorials]"  # jupyter, matplotlib, seaborn
pip install "scviva-tools[all]"        # everything above
```

See [docs/installation.md](docs/installation.md) for details, including a development install.

## Quick Start

```python
import scviva

# scVIVA
scviva.SCVIVA.setup_anndata(adata, layer="counts", spatial_key="spatial")
model = scviva.SCVIVA(adata)
model.train()

# DestVI
import scvi
scvi.model.CondSCVI.setup_anndata(sc_adata, labels_key="cell_type", layer="counts")
sc_model = scvi.model.CondSCVI(sc_adata)
sc_model.train()

scviva.DestVI.setup_anndata(st_adata, layer="counts")
st_model = scviva.DestVI.from_rna_model(st_adata, sc_model)
st_model.train()

# ResolVI
scviva.ResolVI.setup_anndata(adata, layer="counts", spatial_key="spatial")
model = scviva.ResolVI(adata)
model.train()
```

Models beyond scVIVA/DestVI/ResolVI (GIMVI, Stereoscope, Tangram) live under `scviva.external`,
e.g. `scviva.external.Tangram`.

### Downstream tools (`scviva.tl` / `scviva.pl`)

`scviva.tl` and `scviva.pl` mirror scanpy's `sc.tl`/`sc.pl` convention, resolving lazily to
`scviva.tools`/`scviva.plotting` so heavy optional dependencies aren't imported eagerly:

```python
# Harreman: metabolic exchange & cell-cell communication analysis, optionally
# integrating DestVI/ResolVI/SCVIVA outputs
scviva.tl.harreman.hs.compute_local_autocorrelation(adata, use_metabolic_genes=True)
scviva.pl.harreman.local_correlation_plot(adata)
```

`scviva.tl.harreman` itself exposes a scanpy-style sub-API: `tl`/`hs`/`pp`/`ds`/`pl` for
tools/hotspot/preprocessing/datasets/plotting, plus a stateful `HarremanAnalysis` wrapper
(`scviva.tools.harreman.HarremanAnalysis`) that can integrate DestVI/ResolVI/SCVIVA outputs.

## Documentation

Full documentation, including the user guide, API reference, and tutorials, is under
[docs/](docs/index.md). See [CHANGELOG.md](CHANGELOG.md) for a detailed history of recent
changes.

## References

See [docs/references.md](docs/references.md) for full citations.

Copyright (c) 2026, Yosef Lab, Weizmann Institute of Science
