Metadata-Version: 2.4
Name: pyXenium
Version: 0.4.6
Summary: Xenium I/O, multimodal analysis, topology workflows, contour-native spatial profiling, GMI inference, mechanostress analysis, and optional external workflow bridges.
Author: Taobo Hu
Maintainer: SPATHO AB
License-Expression: AGPL-3.0-only
Project-URL: Documentation, https://pyxenium.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/hutaobo/pyXenium
Project-URL: Issues, https://github.com/hutaobo/pyXenium/issues
Project-URL: Changelog, https://pyxenium.readthedocs.io/en/latest/changelog.html
Project-URL: Releases, https://github.com/hutaobo/pyXenium/releases
Keywords: xenium,spatial-omics,spatial-transcriptomics,multimodal,anndata
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: matplotlib>=3.8
Requires-Dist: seaborn>=0.13
Requires-Dist: statsmodels>=0.14
Requires-Dist: scanpy>=1.10
Requires-Dist: shapely>=2.0
Requires-Dist: tifffile>=2024.8.10
Requires-Dist: imagecodecs>=2024.6.1
Requires-Dist: Pillow>=10.0
Requires-Dist: zarr>=3.1
Requires-Dist: fsspec>=2024.6.0
Requires-Dist: requests>=2.31
Requires-Dist: PyYAML>=6.0
Requires-Dist: pyarrow>=14.0
Requires-Dist: aiohttp
Requires-Dist: click>=8.1
Provides-Extra: perturb
Requires-Dist: SpatialPerturb>=0.3; python_version >= "3.9" and extra == "perturb"
Provides-Extra: lazyslide
Requires-Dist: lazyslide>=0.10; python_version >= "3.11" and extra == "lazyslide"
Requires-Dist: wsidata>=0.3; python_version >= "3.11" and extra == "lazyslide"
Requires-Dist: tiffslide>=2.5; python_version >= "3.11" and extra == "lazyslide"
Requires-Dist: geopandas>=0.14; python_version >= "3.11" and extra == "lazyslide"
Provides-Extra: docs
Requires-Dist: sphinx>=8; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.16; extra == "docs"
Requires-Dist: myst-parser>=4.0; extra == "docs"
Requires-Dist: myst-nb>=1.1; extra == "docs"
Requires-Dist: sphinx-design>=0.6; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: ipykernel>=6.29; extra == "docs"
Requires-Dist: nbclient>=0.10; extra == "docs"
Requires-Dist: nbformat>=5.10; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/hutaobo/pyXenium/main/docs/_static/branding/pyxenium-horizontal-dark.png" alt="pyXenium horizontal logo" width="960">
</p>

<h1 align="center">pyXenium</h1>

<p align="center">
  nine feature areas for Xenium I/O, multimodal analysis, CCI, pathway topology, contour geometry, GMI inference, mechanostress analysis, and external workflow bridges.
</p>

<p align="center">
  <a href="https://pypi.org/project/pyXenium/"><img src="https://img.shields.io/pypi/v/pyXenium.svg" alt="PyPI version"></a>
  <a href="https://pyxenium.readthedocs.io/en/latest/"><img src="https://readthedocs.org/projects/pyxenium/badge/?version=latest" alt="Read the Docs"></a>
  <a href="https://github.com/hutaobo/pyXenium/actions/workflows/ci.yml"><img src="https://github.com/hutaobo/pyXenium/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://pypi.org/project/pyXenium/"><img src="https://img.shields.io/pypi/pyversions/pyXenium.svg" alt="Python versions"></a>
  <a href="https://github.com/hutaobo/pyXenium/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-0a7f5a.svg" alt="License"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/pyXenium/">PyPI</a>
  ·
  <a href="https://pyxenium.readthedocs.io/en/latest/">Read the Docs</a>
  ·
  <a href="https://github.com/hutaobo/pyXenium">GitHub</a>
  ·
  <a href="https://pyxenium.readthedocs.io/en/latest/changelog.html">Changelog</a>
  ·
  <a href="https://github.com/hutaobo/pyXenium/releases">Releases</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/hutaobo/pyXenium/main/docs/_static/figures/pyxenium-nine-feature-overview.png" alt="pyXenium nine-feature overview figure" width="960">
</p>

<p align="center">
  <em>Figure 1. pyXenium summarizes Xenium I/O, multimodal analysis, spatial topology, contour-aware inference, mechanostress analysis, and external workflow bridges in one submission-ready overview.</em>
</p>

pyXenium is a Python toolkit for **10x Genomics Xenium** organized around nine major sections.

| Section | Canonical entry | Start here |
| --- | --- | --- |
| Xenium I/O | `pyXenium.io` | [Xenium data loading guide](https://pyxenium.readthedocs.io/en/latest/guides/xenium-data-loading.html) |
| Multimodal Analysis | `pyXenium.multimodal` | [Multimodal overview](https://pyxenium.readthedocs.io/en/latest/user-guide/multimodal-overview.html) |
| Cell-Cell Interaction | `pyXenium.cci` | [CCI tutorial hub](https://pyxenium.readthedocs.io/en/latest/tutorials/cci_index.html) |
| Pathway Topology | `pyXenium.pathway` | [Pathway tutorial](https://pyxenium.readthedocs.io/en/latest/tutorials/pathway.html) |
| Contour Geometry | `pyXenium.contour` | [Contour tutorial hub](https://pyxenium.readthedocs.io/en/latest/tutorials/contour_index.html) |
| GMI Inference | `pyXenium.gmi` | [Contour GMI guide](https://pyxenium.readthedocs.io/en/latest/guides/gmi-contour.html) |
| Mechanostress | `pyXenium.mechanostress` | [Mechanostress tutorial](https://pyxenium.readthedocs.io/en/latest/tutorials/mechanostress_atera_pdc.html) |
| AI-Driven Spatial Pathologist | `pyXenium.spatho` | [RTD bridge guide](https://pyxenium.readthedocs.io/en/latest/tutorials/ai_driven_spatial_pathologist.html) |
| SpatialPerturb Bridge | `pyXenium.perturb` | [SpatialPerturb bridge guide](https://pyxenium.readthedocs.io/en/latest/tutorials/spatialperturb_bridge.html) |

Legacy compatibility entry points under `pyXenium.analysis`, `pyXenium.validation`, and
`pyXenium.io.load_xenium_gene_protein(...)` remain importable, but new code should target the
canonical pyXenium namespaces above. The `spatho` and `SpatialPerturb` workflows are installed
and run separately; pyXenium does not vendor them or add them as core runtime dependencies.

## Release & Build

- Current repository version: `0.4.5`
- Package index: [PyPI](https://pypi.org/project/pyXenium/)
- Documentation site: [pyxenium.readthedocs.io](https://pyxenium.readthedocs.io/en/latest/)
- Canonical build status: [GitHub Actions CI](https://github.com/hutaobo/pyXenium/actions/workflows/ci.yml)
- Supported Python: `>=3.8`
- License: [GNU AGPL v3.0 only](https://github.com/hutaobo/pyXenium/blob/main/LICENSE)
- Maintained by: `SPATHO AB`

## Install

```bash
pip install pyXenium==0.4.5
```

For local development:

```bash
git clone https://github.com/hutaobo/pyXenium
cd pyXenium
pip install -e ".[dev]"
```

For documentation work:

```bash
pip install -e ".[docs]"
```

For the optional SpatialPerturb Bridge runtime on Python 3.9+:

```bash
pip install -e ".[perturb]"
```

## Representative examples

### Xenium I/O

```python
from pyXenium.io import read_xenium

slide = read_xenium("/path/to/xenium_export", as_="slide", prefer="zarr")
```

`XeniumSlide` is the only canonical in-memory object in pyXenium. Legacy
alias-based I/O entrypoints have been removed.

To build Atera-style learning stores with contour-segmented H&E crops:

```bash
pyxenium slide build-atera --atera-root Y:\long\10X_datasets\Xenium\Atera --output-root D:\GitHub\stGPT\outputs\xenium_slides\atera
```

This writes one `xenium_slide.zarr` per case plus `slide_manifest.json`, `qc_report.json`, `cell_to_contour.parquet`, `structure_assignments.csv`, and `contour_patches_manifest.json`. Raw Xenium outs directories are read only; per-cell H&E patches are not generated.

### Canonical multimodal loading

```python
from pyXenium.multimodal import load_rna_protein_anndata

adata = load_rna_protein_anndata(
    base_path="/path/to/xenium_export",
    prefer="auto",
)
```

### Contour expansion

```python
from pyXenium.contour import expand_contours

expand_contours(
    slide,
    contour_key="protein_cluster_contours",
    distance=25.0,
    mode="voronoi",
)
```

### Contour-GMI inference

```python
from pyXenium.gmi import ContourGmiConfig, run_atera_breast_contour_gmi

result = run_atera_breast_contour_gmi(
    dataset_root="/path/to/WTA_Preview_FFPE_Breast_Cancer_outs",
    output_dir="pyxenium_gmi_outputs/atera_s1_s5",
    config=ContourGmiConfig(feature_count=500, spatial_feature_count=100),
)
```

`pyXenium.gmi` is a canonical beta surface: the API is public, while biological interpretation
should be checked with the bundled controls, cross-validation, and PDC Slurm reproducibility workflow.
The Atera S1/S5 validation completed on PDC Dardel in the `v0.4.1` release, supporting an
S5/DCIS RNA program led by `NIBAN1` and `SORL1` under the QC20 primary model.

### Mechanostress analysis

```python
from pyXenium.io import read_xenium
from pyXenium.mechanostress import MechanostressConfig, run_mechanostress_workflow

slide = read_xenium("/path/to/xenium_export", as_="slide", include_boundaries=True)
result = run_mechanostress_workflow(
    slide,
    output_dir="pyxenium_mechanostress_outputs/sample_1",
    config=MechanostressConfig(),
)
```

For cohorts organized as one Xenium sample per directory, use:

```python
from pyXenium.mechanostress import MechanostressConfig, run_mechanostress_cohort

cohort = run_mechanostress_cohort(
    "/path/to/headandneckSCC",
    output_dir="pyxenium_mechanostress_outputs/hnscc",
    config=MechanostressConfig(coupling_genes=("KRT5", "EPCAM")),
)
```

`pyXenium.mechanostress` is a canonical beta surface for extracting mechanical stress
signals from Xenium morphology and spatial cell context.

### AI-Driven Spatial Pathologist via spatho

[`AI-Driven Spatial Pathologist`](https://ai-driven-spatial-pathologist.readthedocs.io/en/latest/?badge=latest)
is an external workflow layer for AI-assisted pathology review around Xenium-scale spatial
transcriptomics. Its public Python package and CLI are named `spatho`.

```bash
pip install -U spatho
spatho init-workflow --organ breast --case-name breast_case_01 --dataset-root /path/to/Xenium_outs --output workflow.json
spatho doctor --config workflow.json
spatho run --config workflow.json
```

In pyXenium, this is documented as an optional external workflow bridge rather than a new
`pyXenium.spatho` namespace.
The handoff is possible because `XeniumSlide` keeps the cell table, transcript points,
cell/nucleus boundaries, H&E image metadata, and slide-native organization together
for downstream tools, with an optional `XeniumSlide.to_spatialdata()` bridge for users
who separately install that ecosystem.

## Acknowledgement

`XeniumSlide` is inspired by the container ideas popularized by
[SpatialData](https://spatialdata.scverse.org/en/stable/), while pyXenium now ships a
fully rewritten independent slide model and Zarr store implementation with no core runtime
dependency on the `spatialdata` package. If you build on the bridge or the design lineage,
please also cite [Marconato et al., 2024](https://doi.org/10.1038/s41592-024-02212-x).

### SpatialPerturb Bridge via SpatialPerturb

[`SpatialPerturb`](https://github.com/hutaobo/SpatialPerturb) is an external workflow package
for combining spatial transcriptomics with Perturb-seq references. pyXenium exposes a lightweight
`pyXenium.perturb` bridge that writes a handoff JSON and stable external CLI commands without
vendoring the SpatialPerturb algorithms.

```python
from pyXenium.perturb import SpatialPerturbBridgeConfig, write_spatialperturb_handoff

spec = write_spatialperturb_handoff(
    SpatialPerturbBridgeConfig(
        xenium_path="/path/to/Xenium_outs",
        output_dir="spatialperturb_reports/breast_case_01",
        cell_group_path="/path/to/cell_groups.csv",
        roi_geojson_path="/path/to/xenium_explorer_annotations.geojson",
        sample_name="breast_case_01",
    ),
    "spatialperturb_bridge.json",
)
print(spec["command_text"]["run_reference_benchmark"])
```

SpatialPerturb Bridge scores mean Perturb-seq-derived program similarity projected onto Xenium
tissue. They do not mean the tissue cell contains the corresponding knockout, guide, or drug
perturbation.

## Documentation entry points

The docs now separate the nine feature sections from the main reading paths:

- [Quickstart](https://pyxenium.readthedocs.io/en/latest/quickstart.html)
- [Tutorials hub](https://pyxenium.readthedocs.io/en/latest/tutorials/index.html)
- [User guide](https://pyxenium.readthedocs.io/en/latest/user-guide/index.html)
- [Workflows](https://pyxenium.readthedocs.io/en/latest/workflows/index.html)
- [API reference](https://pyxenium.readthedocs.io/en/latest/api/index.html)
- [Changelog](https://pyxenium.readthedocs.io/en/latest/changelog.html)

Start here: [pyxenium.readthedocs.io](https://pyxenium.readthedocs.io/en/latest/)

## License

This project is licensed under the [GNU Affero General Public License v3.0 only](https://github.com/hutaobo/pyXenium/blob/main/LICENSE).
It is maintained by `SPATHO AB`.
Copyright remains with Taobo Hu and other contributors where applicable.
