Metadata-Version: 2.4
Name: py-spacetrooper
Version: 0.1.1
Summary: Quality Control for image-based spatial transcriptomics data — Python port of SpaceTrooper
Author: SpaceTrooper Team
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.9
Requires-Dist: scikit-learn>=1.1
Requires-Dist: anndata>=0.8
Requires-Dist: matplotlib>=3.5
Requires-Dist: seaborn>=0.12
Requires-Dist: shapely>=2.0
Requires-Dist: geopandas>=0.12
Requires-Dist: pyarrow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: rpy2>=3.5; extra == "dev"

# py-spacetrooper

[![PyPI version](https://img.shields.io/pypi/v/py-spacetrooper)](https://pypi.org/project/py-spacetrooper/)
[![Python versions](https://img.shields.io/pypi/pyversions/py-spacetrooper)](https://pypi.org/project/py-spacetrooper/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI downloads](https://img.shields.io/pypi/dm/py-spacetrooper)](https://pypi.org/project/py-spacetrooper/)

Python port of [SpaceTrooper](https://github.com/drighelli/SpaceTrooper) — Quality Control for image-based spatial transcriptomics data.

**Parity**: Pearson r = 0.989 vs R | **Speed**: 102× faster

## Install

```bash
pip install py-spacetrooper
```

## Quickstart

```python
import anndata as ad
from spacetrooper import SpaceTrooper

# Load your spatial data
adata = ad.read_h5ad("your_data.h5ad")

# Run QC pipeline
st = SpaceTrooper(adata)
st.spatial_per_cell_qc()
st.compute_qc_score()

# Access results
print(st.adata.obs["QC_score"])  # QC scores (0-1)
```

## Functional API

```python
from spacetrooper import (
    spatial_per_cell_qc,
    compute_outliers_qc_score,
    check_outliers,
    compute_qc_score,
)

spatial_per_cell_qc(adata)
compute_outliers_qc_score(adata)
check_outliers(adata)
compute_qc_score(adata)
```

## Supported platforms

| Platform | Function | Description |
|---|---|---|
| Nanostring CosMx | `read_cosmx_spe` | Transcriptomics + Proteomics |
| Vizgen MERFISH | `read_merfish_spe` | MERFISH / Merscope |
| 10x Xenium | `read_xenium_spe` | Xenium output bundle |

## What's included

| Python function | R equivalent | Description |
|---|---|---|
| `spatial_per_cell_qc` | `spatialPerCellQC` | Per-cell QC metrics |
| `compute_spatial_outlier` | `computeSpatialOutlier` | Outlier detection (medcouple/MAD) |
| `compute_outliers_qc_score` | `computeOutliersQCScore` | Outlier labels for QC formula |
| `check_outliers` | `checkOutliers` | Validate outlier counts |
| `compute_qc_score` | `computeQCScore` | Ridge logistic regression QC score |
| `compute_threshold_flags` | `computeThresholdFlags` | Fixed threshold flags |
| `read_cosmx_spe` | `readCosmxSPE` | Read CosMx data |
| `read_merfish_spe` | `readMerfishSPE` | Read MERFISH data |
| `read_xenium_spe` | `readXeniumSPE` | Read Xenium data |
| `read_polygons` | `readPolygons` | Read polygon boundaries |
| `plot_metric_hist` | `plotMetricHist` | Metric histogram |
| `plot_centroids` | `plotCentroids` | Spatial scatter plot |

## Parity with R

| Metric | Value | Threshold |
|---|---|---|
| QC_score Pearson r | **0.989** | ≥ 0.90 |
| Intermediate metrics | < 1e-13 | < 1e-8 |
| Wall-clock speed | **102× faster** | — |

## Citation

```bibtex
@article{righelli2024spacetrooper,
  title={SpaceTrooper: Quality Control for image-based spatial transcriptomics},
  author={Righelli, Dario and Banzi, Benedetta and Marchionni, Matteo and others},
  year={2024},
  journal={Bioinformatics}
}
```

## License

MIT (matches upstream [SpaceTrooper](https://github.com/drighelli/SpaceTrooper))
