Metadata-Version: 2.5
Name: sigma-omics
Version: 0.3.1
Summary: Interface-aware spectral graph learning of pathological metabolic transitions
Project-URL: Homepage, https://github.com/Elsa-bingxue/SIGMA
Project-URL: Repository, https://github.com/Elsa-bingxue/SIGMA
Project-URL: Issues, https://github.com/Elsa-bingxue/SIGMA/issues
Author-email: Bingxue Du <dubingxue73@gmail.com>
License: MIT
License-File: LICENSE
Keywords: mass spectrometry imaging,pathological interface,spatial metabolomics,spatial omics,spectral graph learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: anndata>=0.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy<2,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scanpy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: torch-geometric<2.6,>=2.5
Requires-Dist: torch>=2.1
Requires-Dist: zarr<3,>=2.18
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Description-Content-Type: text/markdown

# SIGMA (`sigma-omics`)

**SIGMA resolves pathological metabolic transitions with interface-aware
spectral graph learning.**

SIGMA is a Python framework for identifying pathological interfaces from
spatial metabolomics. It combines tissue coordinates, metabolite intensities
and pathology-derived or weak spatial anchors to recover continuous interface
fields and boundary-associated metabolic programs.

Spatial transcriptomics is optional. When matched data are available, it can
support auxiliary alignment and independent biological validation.

## Install

```bash
pip install sigma-omics
```

The distribution is named `sigma-omics`; the Python package is
`sigma_spatial`.

## Inputs

SIGMA uses an `AnnData` object containing:

- a spot-by-metabolite intensity matrix;
- two-dimensional tissue coordinates;
- tumor/non-tumor annotations, transferred pathology labels or weak spatial
  anchors;
- an optional matched transcriptomic representation.

See the [input format guide](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/input_format.md)
for supported keys and loading examples.

## Quick start

```python
import scanpy as sc
from sigma_spatial import run_analysis

adata = sc.read_h5ad("sample.h5ad")

result = run_analysis(
    adata,
    output_dir="results/sample",
    prefix="sample",
    workflow="auto",
    evidence={"same_section_pathology": True},
    report_level="standard",
    random_state=0,
)

print(result.workflow)
print(result.downstream.leading_program)
```

For an unfamiliar dataset, inspect its declared modalities first:

```python
from sigma_spatial import inspect_input

inspect_input(adata).print_report()
```

The same standard report is available from the command line:

```bash
sigma-omics report sample.h5ad results/sample \
  --workflow auto \
  --same-section-pathology \
  --report-level standard \
  --seed 0
```

## Outputs

SIGMA returns:

- a continuous pathological-region probability field;
- an inferred interface and signed-distance coordinate;
- spatial metabolic programs and their distance profiles;
- ranked interface-associated metabolites;
- interface influence ranges and directional anisotropy;
- optional matched-ST validation summaries.

Core fields are stored in `AnnData`; downstream tables and publication-quality
figures are written to the selected output directory. See
[output schema](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/output_schema.md)
for the complete list.

## Supported workflows

SIGMA supports same-section pathology, joint SM+ST inference, transferred
pathology and region-defined disease analyses. Spatial metabolomics remains the
target modality in every workflow. An explicitly anchored SM-only workflow is
also available for datasets without matched transcriptomics.

```python
from sigma_spatial import run_sigma_weak_anchor

result = run_sigma_weak_anchor(
    adata,
    anchor_key="sigma_anchor",
    already_log=True,
    random_state=0,
)
```

## Reproducibility

Every run records its workflow, parameters, matrix source, package version and
random seed. Reference analyses can additionally use frozen rankings and
program assignments to reproduce manuscript panels.

Detailed workflow rules, program selection and manuscript reproduction are
documented in the
[workflow and reproducibility guide](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/workflows_and_reproducibility.md).

## Links

- [GitHub repository](https://github.com/Elsa-bingxue/SIGMA)
- [Input format](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/input_format.md)
- [Output schema](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/output_schema.md)
- [Weak-anchor validation](https://github.com/Elsa-bingxue/SIGMA/blob/main/docs/weak_anchor_validation.md)
- [Issues](https://github.com/Elsa-bingxue/SIGMA/issues)

## Scope

The package contains reusable SIGMA computation and standardized downstream
reporting. Large reference datasets, manuscript simulations, benchmarks, GO
enrichment and sample-specific interpretation remain in the analysis
repository.
