Metadata-Version: 2.1
Name: stdetail
Version: 0.3.0rc3
Summary: Spatial evaluation of predicted gene expression
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: NOTICE.md
Requires-Dist: numpy<3,>=1.26
Requires-Dist: scipy<2,>=1.11
Requires-Dist: pandas<3,>=2.1
Requires-Dist: h5py<4,>=3.9
Requires-Dist: torch<3,>=2.2
Requires-Dist: scikit-learn>=1.3
Provides-Extra: cell
Requires-Dist: anndata<0.13,>=0.10; extra == "cell"
Requires-Dist: pyarrow>=14; extra == "cell"
Requires-Dist: shapely>=2; extra == "cell"
Requires-Dist: geopandas>=0.14; extra == "cell"
Provides-Extra: training
Requires-Dist: scikit-learn>=1.3; extra == "training"
Requires-Dist: pillow>=10; extra == "training"
Requires-Dist: pyyaml>=6; extra == "training"
Requires-Dist: lightning>=2.2; extra == "training"
Requires-Dist: torchvision>=0.17; extra == "training"
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"

# STDetail

Evaluate spatial gene expression predictions at the scale and within the biological context required by an analysis.

This Python source package contains the paper's evaluation code, neighbouring-pair training objective, model adapters and browser-export commands. It contains no study results, patient data, model weights or research run history. The hosted browser interface is distributed separately. Version 0.3.0rc3 adds a general result-export bridge without changing the scientific scoring modules.

The existing [NOTICE](NOTICE.md) applies. No repository-wide public licence has been assigned; downloading this package does not grant an open-source licence.

## Install

Python 3.10 or later:

```bash
python -m venv .venv
# Activate the environment for your operating system.
python -m pip install -e .
```

For optional workflows:

```bash
python -m pip install -e ".[cell,training,test]"
```

Use the PyTorch build appropriate for your CPU or CUDA environment. Model-specific dependencies are installed separately; see [training](docs/training.md).

## Try it

```bash
stdetail example --output outputs/synthetic
```

This generates two synthetic count matrices and predictions, constructs the graph, estimates RNA components, computes five-scale scores and exports `outputs/synthetic/analysis-bundle.json`. Every value in this example is generated. HEST specimen names are used only as protocol keys; no patient data are bundled.

## Workflows

| Workflow | Entry point | Documentation |
| --- | --- | --- |
| Context-matched local ordering | `python -m stdetail.her2` | [HER2ST](docs/her2.md) |
| HEST spatial spectra and RNA weighting | `stdetail hest` | [HEST](docs/hest.md) |
| Physical-wavelength spectra on regular grids | `stdetail fourier` | [Fourier evaluation](docs/fourier.md) |
| Cell graphs, aggregation and RNA repeatability | `python -m stdetail.cell_rna` | [Cell evaluation](docs/cell.md) |
| Cell-model scoring and proliferation hotspots | `python -m stdetail.cell_score` | [Cell evaluation](docs/cell.md) |
| Neighbouring-pair supervision | `stdetail.training` | [Training](docs/training.md) |
| Single-model / multi-model result export | `stdetail export-results` | [Export results](docs/export-results.md) |
| Paired HEST expression maps | `stdetail export` | [HEST](docs/hest.md) |

The evaluation protocols use different transforms and graph constructions for different assays. They share the principle of comparing predictions and RNA on the same eligible support. Their scores are not interchangeable.

## Browse saved results

```bash
stdetail export-results --run outputs/hest --output outputs/hest-results.json
```

Open the evaluation-results workspace at https://stdetail-spatial-evaluation.oyjr2002.chatgpt.site/ and upload the generated JSON. One prediction, multiple models and multiple specimens are supported. The older `stdetail export` paired-expression output remains supported for spatial maps. The general bridge preserves each workflow's own metrics and support, and separates RNA references from model scores.

## Tests

```bash
python -m pytest
cd web
npm test
npm run build
```

## Source and attribution

The scientific implementations were extracted from the study's original analysis and training code, with operational paths removed and shared code consolidated. The two cell-model scorers use one implementation because their numerical computations were identical. [PROVENANCE.md](PROVENANCE.md) describes the source modules and changes.

Third-party datasets, models and weights retain their respective terms. This source package does not assign a new licence to third-party work. The project authors should select the repository licence before public distribution; see [NOTICE.md](NOTICE.md).
