Metadata-Version: 2.4
Name: nest-st
Version: 0.2.2
Summary: NEST: Native Expression reconstruction for Spatial Transcriptomics
Author-email: Tianyi Liu <1694414073@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/lty10086/NEST
Project-URL: Repository, https://github.com/lty10086/NEST
Project-URL: Issues, https://github.com/lty10086/NEST/issues
Keywords: spatial transcriptomics,gene completion,dropout recovery,graph neural network,single-cell RNA sequencing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anndata>=0.10
Requires-Dist: numpy>=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: torch>=2.1
Requires-Dist: torch-geometric>=2.5
Requires-Dist: igraph>=0.11
Requires-Dist: leidenalg>=0.10
Dynamic: license-file

# NEST

NEST (**N**ative **E**xpression reconstruction for **S**patial
**T**ranscriptomics) provides one public interface for two independent
reconstruction workflows. The `mode` argument selects a branch; model,
preprocessing, graph construction, and parameter logic remain in the
corresponding implementation file.

- `mode="missing_gene"` calls `NEST_panel.py`. It uses a matched scRNA-seq
  reference for cross-modal mapping and gene-domain correction before
  graph-guided reconstruction of unmeasured genes.
- `mode="dropout"` calls `NEST_dropout.py`. It uses only the ST expression
  matrix and spatial coordinates, performs ST-derived native anchoring, and
  reconstructs zero-valued entries through the task-specific graph workflow.

## Installation

```bash
pip install nest-st
```

For CUDA, install the PyTorch build matching the local CUDA version first.
NEST does not normalize or log-transform expression implicitly; inputs must be
non-negative and consistently transformed.

## Python API

### Panel completion

```python
import scanpy as sc
from nest_st import reconstruct

adata_st = sc.read_h5ad("st_log1p.h5ad")
adata_sc = sc.read_h5ad("scrna_log1p.h5ad")

result = reconstruct(
    adata_st,
    mode="missing_gene",
    adata_sc=adata_sc,
    device="cuda",
)
result.write_h5ad("nest_missing_gene.h5ad")
```

By default, reference genes absent from ST are reconstructed. Measured genes
can be held out explicitly for gene-wise validation:

```python
result = reconstruct(
    adata_st,
    mode="missing_gene",
    adata_sc=adata_sc,
    target_genes=["GeneA", "GeneB"],
    device="cuda",
)
```

### Zero-entry reconstruction

```python
result = reconstruct(
    adata_st,
    mode="dropout",
    device="cuda",
)
result.write_h5ad("nest_dropout.h5ad")
```

The default output preserves observed non-zero values and replaces input zeros
with the dropout-branch predictions. A boolean `fill_mask` can restrict the
replaced entries. Set `fill_zeros_only=False` to return the complete predicted
matrix.

### Optional training overrides

Branch defaults are defined in `NEST_panel.py` and `NEST_dropout.py`. Selected
settings can be overridden through the shared interface:

```python
result = reconstruct(
    adata_st,
    mode="dropout",
    learning_rate=1e-3,
    ae_epochs=1000,
    gae_epochs=2000,
    device="cuda",
)
```

## Command line

```bash
nest-st --mode missing_gene --st st.h5ad --sc scrna.h5ad --output result.h5ad
nest-st --mode dropout --st st.h5ad --output result.h5ad
```

Run `nest-st --help` for available overrides.

## Input requirements

- Inputs are `AnnData` objects with unique observation and gene names.
- `adata_st.obsm["spatial"]` contains finite two-dimensional coordinates.
- Expression values are finite, non-negative, and consistently transformed.
- Panel completion requires a matched scRNA-seq reference and at least two
  shared training genes.

## Source layout

```text
src/nest_st/nest.py          public dispatcher and result adapter
src/nest_st/NEST_panel.py    missing-gene implementation
src/nest_st/NEST_dropout.py  zero-entry implementation
```

## Development build

```bash
python -m pip install --upgrade build twine pytest
python -m compileall -q src/nest_st
python -m build
python -m twine check dist/*
```
