Metadata-Version: 2.4
Name: scatlaspy
Version: 1.0.0
Summary: A scalable Python platform for atlas-scale single-cell omics analysis beyond in-memory limits.
Author: Han Xu, Yangzhan Ye, Senpeng Zhang
Maintainer: scAtlasPy development team
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/GaoLabXDU/scatlaspy
Project-URL: Documentation, https://scatlaspy.readthedocs.io
Project-URL: Repository, https://github.com/GaoLabXDU/scatlaspy
Project-URL: Issues, https://github.com/GaoLabXDU/scatlaspy/issues
Keywords: single-cell,cell atlas,bioinformatics,omics,out-of-core
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26.4
Requires-Dist: scipy>=1.11.4
Requires-Dist: pandas>=2.0.3
Requires-Dist: h5py>=3.11.0
Requires-Dist: matplotlib>=3.8.4
Requires-Dist: tqdm>=4.66.4
Requires-Dist: scikit-learn>=1.4.2
Requires-Dist: igraph>=0.11.0
Requires-Dist: louvain>=0.8.2
Requires-Dist: setuptools<81
Requires-Dist: umap-learn>=0.5.6
Requires-Dist: anndata>=0.11.4
Requires-Dist: pyarrow>=15.0.2
Requires-Dist: scanpy>=1.10.4
Requires-Dist: duckdb>=1.5.3
Provides-Extra: parametric
Requires-Dist: torch>=2.2.0; extra == "parametric"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Requires-Dist: hypothesis>=6.112.2; extra == "test"
Requires-Dist: psutil>=6.1.1; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx<8.2,>=8.1.3; extra == "docs"
Requires-Dist: myst-parser<5.0,>=4.0.1; extra == "docs"
Requires-Dist: myst-nb>=1.4.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
Requires-Dist: sphinx-design<0.7,>=0.6.1; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints<3.1,>=3.0.1; extra == "docs"
Requires-Dist: sphinx-book-theme<1.2,>=1.1.4; extra == "docs"
Requires-Dist: numpydoc>=1.10.0; extra == "docs"
Requires-Dist: ipywidgets>=8.1.8; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="docs/_static/img/scAtlas_full_paths.svg" alt="scAtlasPy logo" width="320">
</p>

# scAtlasPy

**A scalable Python platform for atlas-scale single-cell omics analysis beyond in-memory limits.**

scAtlasPy is a Python platform for analyzing cell atlases that are too large to
fit in memory. It extends familiar single-cell analysis workflows to
atlas-scale datasets, supporting preprocessing, dimensionality reduction,
clustering, visualization, marker analysis, and machine learning within a
unified on-disk environment.

At the center of scAtlasPy is a persistent `.sasql` atlas database. Expression
matrices, metadata, embeddings, and analysis results remain on disk, while
analysis functions retrieve only the cells, genes, or minibatches needed for the
current operation.

## Installation

Install the released package from PyPI:

```bash
pip install scatlaspy
```

Distilled UMAP and distilled Louvain clustering use PyTorch. Install `torch` in
the same environment if you plan to run these tools:

```bash
pip install torch
```

For CUDA, MPS, or other accelerator-specific PyTorch builds, follow the
installation command recommended for your hardware by the PyTorch project.

## Quick Start

```python
import scatlaspy as sap

atlas = sap.Atlas("pbmc.sasql")
atlas.load_h5ad("pbmc.h5ad", load_type="random")

sap.pp.calculate_qc_metrics(atlas)
sap.pp.filter_cells(atlas, min_genes=200)
sap.pp.filter_genes(atlas, min_cells=3)
sap.pp.normalize_and_log1p(atlas)
sap.pp.highly_variable_genes(atlas, n_top_genes=2000)

# Use mode="center_only" if PCA should preserve gene-level variance differences.
sap.pp.scale(atlas)

atlas.build_read_index(
    cell_condition="filter_cells",
    gene_condition="filter_genes",
    use_hvg=True,
    use_data="data_scale",
)

sap.tl.pca(atlas)
sap.tl.umap(atlas)
sap.tl.graph_clustering(atlas)
sap.pl.umap(atlas, color="scatlas_cluster")

atlas.close()
```

## What scAtlasPy Enables

- **Full-resolution atlas workflows:** run QC, filtering, normalization, HVG,
  PCA, clustering, UMAP, marker ranking, and visualization without loading the
  full matrix into memory.
- **High-throughput data retrieval:** stream sparse or dense minibatches from
  disk-resident atlases for downstream algorithms and machine-learning models.
- **Persistent analysis state:** store metadata, transformed expression values,
  embeddings, loadings, clusters, marker statistics, and plots inputs in one
  atlas database.
- **Interoperability:** import from AnnData-compatible `.h5ad` files and export
  selected results back to the broader single-cell ecosystem.
- **Extensibility:** build new atlas-scale methods on top of stable metadata,
  SQL, sparse retrieval, dense minibatch, and result-writing interfaces.

## Documentation

- Documentation: https://scatlaspy.readthedocs.io
- API reference: https://scatlaspy.readthedocs.io/en/latest/api/
- Tutorials: https://scatlaspy.readthedocs.io/en/latest/tutorials/

## Citation

If you use scAtlasPy in academic work, please cite the project repository for
now. A formal citation will be added when a paper or archived release is
available.

## License

scAtlasPy is released under the BSD 3-Clause License.
