Metadata-Version: 2.4
Name: scgeo
Version: 0.1.0
Summary: Geometric analysis of single-cell representations
Author: Yu-Chen Liu
License-Expression: MIT
Project-URL: Homepage, https://github.com/liuifrec/scgeo
Project-URL: Documentation, https://github.com/liuifrec/scgeo/blob/main/docs/OVERVIEW.md
Project-URL: Repository, https://github.com/liuifrec/scgeo
Project-URL: Issues, https://github.com/liuifrec/scgeo/issues
Project-URL: Publication, https://doi.org/10.1093/bioadv/vbag266
Project-URL: Companion workflows, https://github.com/liuifrec/scgeo-notebooks
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: anndata
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: plotly
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: census
Requires-Dist: cellxgene-census; extra == "census"
Requires-Dist: tiledbsoma; extra == "census"
Requires-Dist: pyarrow; extra == "census"
Provides-Extra: notebook
Requires-Dist: jupyterlab; extra == "notebook"
Requires-Dist: ipykernel; extra == "notebook"
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"
Provides-Extra: scanpy
Requires-Dist: scanpy; extra == "scanpy"
Provides-Extra: sklearn
Requires-Dist: scikit-learn; extra == "sklearn"
Provides-Extra: scvelo
Requires-Dist: scvelo>=0.3; extra == "scvelo"
Requires-Dist: igraph; extra == "scvelo"
Requires-Dist: leidenalg; extra == "scvelo"
Requires-Dist: scikit-misc; extra == "scvelo"
Dynamic: license-file

<p align="center">
  <img src="docs/assets/ScGeo_logo.png" width="420" alt="ScGeo logo">
</p>

<h1 align="center">ScGeo</h1>

<p align="center">Geometry-aware analysis of single-cell representations</p>

[![DOI](https://img.shields.io/badge/DOI-10.1093%2Fbioadv%2Fvbag266-blue)](https://doi.org/10.1093/bioadv/vbag266)

**Published study:** Liu Y-C, Yoshida K (2026). *Bioinformatics Advances*,
**6**(1), vbag266. [Read the paper](https://doi.org/10.1093/bioadv/vbag266).

[Quick start](docs/QUICKSTART.md) | [API reference](docs/api_reference.md) |
[Reproducibility](docs/REPRODUCIBILITY.md) |
[Companion workflows](https://github.com/liuifrec/scgeo-notebooks)

## 1. What ScGeo is

ScGeo is an installable Python library for quantifying perturbation-associated
geometry in low-dimensional single-cell representations. It organizes robust
state displacement, biological-sample uncertainty, representation stability,
local geometry, dynamics agreement, abundance, and distributional change as
separate evidence layers.

Start with the [framework overview](docs/OVERVIEW.md), then follow the
[quick start](docs/QUICKSTART.md).

## 2. What ScGeo is not

ScGeo is not a batch-correction or integration algorithm, and it does not make
cells into biological replicates. It does not make UMAP a quantitative
coordinate system, turn agreement among nested PCA dimensions into independent
confirmation, or convert descriptive geometry into causal evidence. ScGeo uses
standard geometric and statistical primitives; its contribution is the
auditable framework that connects those primitives across evidence layers.

## 3. Core analysis layers

| Layer | Main question | Typical output |
|---|---|---|
| Robust shift | How far and in what direction did a state move? | displacement, normalized effect, direction stability |
| Sample uncertainty | Is the shift stable across biological samples? | sample bootstrap interval and coverage |
| Representation stability | Does the conclusion persist across prespecified representations? | consensus status and sensitivity diagnostics |
| Local geometry | Are neighborhoods and local shapes preserved? | overlap, Jaccard, and distortion metrics |
| Dynamics agreement | Does displacement align with an available dynamics estimate? | aligned, discordant, neutral, or unavailable evidence |
| Abundance and distribution | Did composition or within-state shape also change? | separate proportions and distribution distances |

See [Analysis layers](docs/ANALYSIS_LAYERS.md) for estimands and interpretation.

## 4. Installation

Use a fresh environment (Python 3.12 recommended). Install the development
package directly from GitHub; no manual clone or Git installation is needed:

```bash
python -m pip install "scgeo @ https://github.com/liuifrec/scgeo/archive/refs/heads/main.zip"
```

For a conda-managed environment with Scanpy and an IPython kernel:

```bash
conda env create -f https://raw.githubusercontent.com/liuifrec/scgeo/main/environment-user.yml
conda activate scgeo
```

The conda environment installs ScGeo with pip after installing its scientific
stack from conda-forge. This is not yet an advertised `conda install scgeo`
channel release. A bare `pip install scgeo` requires a verified PyPI release;
the commands above deliberately identify this repository instead.

The default package includes geometry and plotting dependencies. Optional
`scanpy`, `scvelo`, `census`, and `notebook` extras install workflow-specific
packages. See [Installation](docs/INSTALLATION.md) for examples, developer
installs, smoke checks, and local native conda builds.

The frozen package checkpoint used for the major-revision evidence package is
[`9a0ed16`](https://github.com/liuifrec/scgeo/tree/9a0ed16cbaa57f935f9c9bc87d1643a25b51012c).
Use its recorded environment to reproduce the paper; a current development
installation does not replace that environment.

## 5. Minimal sample-aware example

The biological sample identifier belongs in `adata.obs`; it should identify an
independently sampled unit rather than a cell, condition, or artificial
partition.

```python
import scgeo as sg

sg.tl.robust_shift(
    adata,
    rep="X_pca",
    condition_key="condition",
    group0="control",
    group1="treated",
    by="cell_type",
    sample_key="donor",
    n_boot=500,
)

sg.tl.representation_stability(
    adata,
    reps=["X_pca", "X_scvi"],
    node_key="cell_type",
    condition_key="condition",
    group0="control",
    group1="treated",
    sample_key="donor",
)

report = sg.get.state_report(adata, node_key="cell_type")
sg.pl.state_evidence_panel(report)
```

Required fields and expected outputs are listed in
[Quick start](docs/QUICKSTART.md).

## 6. How to interpret results

Read effect size, uncertainty, representation stability, local geometry, and
coverage together. `stable_effect`, `stable_neutral`,
`representation_unstable`, and `insufficient_coverage` describe evidence under
the stored rules; they are not interchangeable with population-level causal
claims. Bootstrap magnitude intervals summarize resampling uncertainty around a
nonnegative norm and are not automatically null-hypothesis tests.

See [Result interpretation](docs/RESULT_INTERPRETATION.md) for status-specific
language and warnings.

## 7. Representation robustness

Representations must be prespecified as primary or sensitivity views. Related
PCA20, PCA30, and PCA50 views share a basis and should not be counted as three
independent confirmations. UMAP should ordinarily remain display-only.
Condition mixing is a descriptive diagnostic when condition is biological, not
an integration objective. See [Analysis layers](docs/ANALYSIS_LAYERS.md).

## 8. Synthetic validation

The `scgeo.bench` module provides controlled simulations for effect magnitude,
abundance, distributional shape, local distortion, representation stability,
uncertainty, and geometry–dynamics agreement. Calibration and held-out seeds are
kept separate, and frozen thresholds are not automatically tuned by the suite.

The `balanced_replicate_heterogeneity` scenario uses random sample offsets that
are zero-centered within condition and is intended to test uncertainty without a
systematic condition shift. The separate `batch_condition_confounding` scenario
applies a systematic sample/batch offset correlated with condition and is
non-identifiable without additional design information.

Synthetic results validate behavior under their stated perturbations and
failure modes; they do not establish biological truth. The frozen protocol is
documented in [BENCHMARK_PROTOCOL.md](docs/revision/BENCHMARK_PROTOCOL.md).

## 9. Public validation

Public-data workflows live in the companion repository. They cover the public
pancreatic-development workflow; GSE249479, a public human HSPC inflammatory
xenograft dataset with no recoverable biological-replicate identity; and
GSE211713, a public mouse-lung radiation dataset with 20 independent mouse
libraries. The GSE211713 analysis is replicate-aware and cross-sectional, not
longitudinal. Their inference scopes are not interchangeable. See
[Companion notebooks](docs/COMPANION_NOTEBOOKS.md).

## 10. Reproducibility and companion repository

The library code is maintained here. Source notebooks, execution wrappers,
figure assembly, evidence ledgers, and ignored large artifacts are maintained
in [`scgeo-notebooks`](https://github.com/liuifrec/scgeo-notebooks). Source
notebooks are kept output-free; executed review copies are generated locally.

See [Reproducibility](docs/REPRODUCIBILITY.md) and the generated
[API reference](docs/api_reference.md).

## 11. Limitations

- Geometry depends on the chosen representation and its coverage.
- Biological-sample inference requires genuine independent sample identifiers.
- Abundance, displacement, and distributional change answer different questions.
- Dynamics agreement depends on the assumptions of the supplied dynamics model.
- Weak reference support is an unsupported-state warning, not general
  out-of-distribution detection.
- Public validations cannot establish causality beyond their experimental design.

## 12. Citation

If you use ScGeo, please cite the published paper:

Liu Y-C, Yoshida K. **ScGeo reveals non-canonical trajectories beyond RNA
velocity in radiation-induced hematopoietic recovery.** *Bioinformatics Advances*.
2026;6(1):vbag266. [doi:10.1093/bioadv/vbag266](https://doi.org/10.1093/bioadv/vbag266).

```bibtex
@article{Liu2026ScGeo,
  author = {Liu, Yu-Chen and Yoshida, Kengo},
  title = {{ScGeo} reveals non-canonical trajectories beyond {RNA} velocity in radiation-induced hematopoietic recovery},
  journal = {Bioinformatics Advances},
  year = {2026},
  volume = {6},
  number = {1},
  pages = {vbag266},
  doi = {10.1093/bioadv/vbag266},
  url = {https://doi.org/10.1093/bioadv/vbag266}
}
```

Machine-readable citation metadata is provided in [CITATION.cff](CITATION.cff).

For reproducibility, also report the exact package commit or tag, analysis
configuration, and environment. The article DOI identifies the paper, not a
separately archived software release. See [Reproducibility](docs/REPRODUCIBILITY.md)
for the documented frozen analysis checkpoint and provenance requirements.
