pyXenium

Xenium I/O, multimodal analysis, topology workflows, contour-native spatial profiling, GMI inference, and mechanostress analysis.

PyPI · Read the Docs · GitHub · Changelog · Releases

pyXenium is a Python toolkit for 10x Genomics Xenium with seven canonical public surfaces:

• pyXenium.io: Xenium artifact loading, partial export recovery, SData I/O, and SpatialData-compatible export.
• pyXenium.multimodal: canonical RNA + protein loading, joint analysis, immune-resistance scoring, and packaged workflows.
• pyXenium.ligand_receptor: topology-native ligand-receptor analysis.
• pyXenium.pathway: pathway topology analysis and pathway activity scoring.
• pyXenium.contour: contour import, contour expansion, and contour-aware density profiling around polygon annotations.
• pyXenium.gmi: contour-level GMI modeling for sparse main-effect and interaction discovery in spatial transcriptomics.
• pyXenium.mechanostress: morphology-derived mechanical stress states, including fibroblast axis strength, tumor-stroma growth patterning, and cell polarity.

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 namespaces above.

Release & Build

• Current repository version: 0.4.1
• Package index: PyPI
• Documentation site: pyxenium.readthedocs.io
• Canonical build status: GitHub Actions CI
• Supported Python: >=3.8
• License: pyXenium Non-Commercial License

Install

pip install pyXenium==0.4.1

For local development:

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

For documentation work:

pip install -e ".[docs]"

Quick examples

Xenium I/O

from pyXenium.io import read_xenium

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

Canonical multimodal loading

from pyXenium.multimodal import load_rna_protein_anndata

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

Contour expansion

from pyXenium.contour import expand_contours

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

Contour-GMI inference

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

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

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

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

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.

Documentation structure

The docs mirror the package surfaces and high-level workflows:

• Installation / Quickstart
• User Guide
• Workflows
• API Reference
• Changelog

Start here: pyxenium.readthedocs.io

Branding assets

The repository keeps its Read the Docs, GitHub, and PyPI branding assets under:

docs/_static/branding/

Use the derived horizontal PNG for README, PyPI, and GitHub social preview surfaces:

docs/_static/branding/pyxenium-horizontal-dark.png

The canonical source artwork remains docs/_static/branding/pyxenium-horizontal-dark.svg.

License

Copyright (c) 2025 Taobo Hu. All rights reserved.

This project is source-available, not open source. You may use, modify, and redistribute it only for non-commercial purposes under the terms of the LICENSE file. Commercial use requires prior written permission from the copyright holder.