Metadata-Version: 2.5
Name: sigma-omics
Version: 0.2.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: graph neural network,mass spectrometry imaging,spatial metabolomics,spatial omics,tumor boundary
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 takes a spatial metabolomics intensity matrix and tissue coordinates as
its primary inputs. Pathological annotations, transferred labels, or weak
spatial anchors guide interface inference. Its spectral graph model separates
low-frequency tissue organization from interface-associated metabolic signals.

Matched spatial transcriptomic data can optionally provide auxiliary molecular
information and support downstream biological validation and interpretation.
SIGMA returns an inferred pathological interface, signed-distance coordinates,
interface-associated metabolic programs, ranked metabolites, influence ranges,
and directional anisotropy.

## Install

After the first PyPI release:

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

The distribution name is `sigma-omics`; the Python import remains
`sigma_spatial`.

## Install from source

```bash
pip install -e .
```

## Quick start

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

adata = sc.read_h5ad("sample.h5ad")
result = run_sigma(
    adata,
    anchor_key="sigma_anchor",        # 1=tumor, 0=non-tumor, NaN=unknown
    representation_key="X_harmony",  # validated auxiliary representation
    random_state=0,
)

# Main outputs
result.obs[["sigma_region_probability", "sigma_boundary", "sigma_d_signed"]]
```

For an unfamiliar input, inspect the declared modality before choosing a
workflow:

```python
from sigma_spatial import inspect_input

assessment = inspect_input(adata)  # uses var['feature_type']: SM, ST, or both
assessment.print_report()
```

SM-only data are routed to the explicitly anchored weak-anchor workflow;
joint SM+ST data use SM as the target and an ST representation for auxiliary
alignment. ST-only data may be used for interface/signature validation, but
SIGMA does not label ST-only outputs as metabolic programs.

## Reproduce a reference dataset

Reference data releases contain the core AnnData, frozen feature ranking, and
frozen program assignment table. These are all required because re-clustering
a ranking is not guaranteed to preserve manuscript cluster identities.

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

adata = sc.read_h5ad("HBC515_SIGMA_core.h5ad")
report = run_reference_analysis(
    adata,
    dataset="HBC515",
    ranking_path="BC515_lambda_ranking.csv",
    assignments_path="BC515_metabolic_program_assignments.csv",
    output_dir="results/HBC515_reference",
)
```

The preset fixes the manuscript matrix source, program, distance windows, and
random seed. A frozen representative table can additionally be supplied with
`representatives_path=` when a manuscript panel used a curated final display
set.

## Generate the downstream result set

For a new user, the recommended entry point is the combined workflow:

```python
import sigma_spatial as sigma

sigma.assess_input(adata).print_report()
result = sigma.run_analysis(
    adata,
    output_dir="results/sample_01",
    prefix="sample_01",
    workflow="auto",
    evidence={"same_section_pathology": True},
    report_level="standard",
    random_state=0,
)
print(result.workflow)
print(result.downstream.leading_program)
```

For scientific safety, `workflow="auto"` reads existing provenance or requires
explicit evidence. It does not infer the annotation source from whichever
workflow gives the strongest result. Supported evidence flags are
`same_section_pathology`, `matched_st`, `adjacent_section_pathology`, and
`region_defined`.

`report_level` controls plotting without changing numerical analysis:

- `none`: tables and provenance only;
- `standard`: program patterns, profiles, lollipop, and representative metabolites;
- `complete`: standard report plus influence-range and anisotropy panels;
- `manuscript`: publication-layout report with the complete diagnostics.

After SIGMA has produced a signed-distance field, one call discovers the
metabolic programs and writes the standard figures and tables:

```python
from sigma_spatial import run_downstream_analysis

report = run_downstream_analysis(
    result,
    "results/sample_01",
    prefix="sample_01",
    selection_mode="lambda_profile",
    workflow="direct_pathology",   # one of the four evidence workflows
    signature_scores=None,           # optional matched-ST score arrays
)
print(report.leading_program)
print(report.representatives[["mz", "cluster"]])
```

The report includes spatial program maps, signed-distance profiles,
two-sided near-versus-far interface statistics, five representative metabolite
maps, and directional anisotropy. When independent ST signature scores are
provided, it additionally creates the program-signature heatmap and ST
interface-enrichment plot. The downstream call does not refit the SIGMA model.

`workflow` is selected once from `direct_pathology`, `multiomics_inferred`,
`transferred_pathology`, or `region_defined_disease`. Each workflow has one
fixed lambda-profile preset shared by its samples; users do not tune thresholds
separately for every section. For sparse signed-distance grids, SIGMA can
deterministically reduce the number of bins and records both the requested and
effective bin counts. The exact preset is saved beside every result.

For exact reproduction of a frozen manuscript analysis, set
`selection_mode="reference"` and pass its frozen final ranking table. If the
manuscript program was selected using dataset-specific biological criteria,
also pass `leading_program=<frozen cluster>`; otherwise the leading program is
selected automatically from the two-sided near-versus-far analysis. The JSON
summary records both the automatic result and any explicit reference override.

For SM-only data, use the separately validated HCC-derived entry point:

```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,
)
```

This path preserves the executed HCC P1/P4 loss without introducing an RNA
target. See `docs/input_format.md` and `docs/output_schema.md`.

## Scope

The package contains reusable SIGMA computation and standardized downstream
reporting. Manuscript-specific simulation, benchmarking, GO enrichment, and
sample-specific interpretation remain under `examples/` or the analysis
repository.
