[main] Add Sphinx documentation (ReadTheDocs)

README.md

@@ -1,88 +1,31 @@
-# Installation
+# segger
 
-We recommend CUDA 12.1 with `cu*` packages version ≥24.2 and <26.0. Ensure your CUDA driver version matches or exceeds your toolkit version (≥12.1 for CUDA 12.1). 
-Adjust package versions in the environment files below if your system requires a different package versions.
+GNN-based cell segmentation of spatial transcriptomics data.
 
-## Clone the repository
-```bash
-git clone https://github.com/dpeerlab/segger.git segger && cd segger
-```
+Full documentation (installation, quickstart, outputs, API reference, notebook usage): [docs](docs/index.rst)
 
-## Using `conda`
-```bash
-conda env create -n segger -f environment_cuda121.yml
-```
+## Installation
 
-Adjust `environment_cuda121.yml` for other CUDA versions (e.g., `environment_cuda118.yml` for CUDA 11.8).
+pixi with Python 3.11 (conda and Python 3.13 support coming soon):
 
-## Using `pixi`
 ```bash
+curl -fsSL https://pixi.sh/install.sh | sh
+git clone https://github.com/dpeerlab/segger.git
+cd segger
 pixi install -e cuda121
 ```
 
-Adjust the environment name in `pixi.toml` as needed for other CUDA versions.
-
-## `pip`
-
-Install GPU-accelerated PyTorch and RAPIDS compatible with your CUDA version before installing **segger**. All CUDA-enabled packages must be compiled for the same CUDA version.
+## Usage
 
-- **PyTorch & torchvision:** [Installation guide](https://pytorch.org/get-started/locally/)
-- **torch_scatter:** [Installation guide](https://github.com/rusty1s/pytorch_scatter#installation)
-- **RAPIDS (cuDF, cuML, cuGraph):** [Installation guide](https://docs.rapids.ai/install)
-- **CuPy:** [Installation guide](https://docs.cupy.dev/en/stable/install.html)
-- **cuSpatial:** [Installation guide](https://docs.rapids.ai/api/cuspatial/stable/user_guide/cuspatial_api_examples/#Installing-cuSpatial)
-
-For example, on Linux with CUDA 12.1 and PyTorch 2.5.0:
-```bash
-# Install PyTorch and torchvision for CUDA 12.1
-pip install torch==2.5.0 torchvision==0.20.0 --index-url https://download.pytorch.org/whl/cu121
-
-# Install torch_scatter for CUDA 12.1
-pip install torch_scatter -f https://data.pyg.org/whl/torch-2.5.0+cu121.html
-
-# Install RAPIDS packages for CUDA 12.x
-pip install --extra-index-url=https://pypi.nvidia.com cuspatial-cu12 cudf-cu12 cuml-cu12 cugraph-cu12
-
-# Install CuPy for CUDA 12.x
-pip install cupy-cuda12x
-```
-**December 2025:** To stay up-to-date with new developments, we recommend installing the latest version directly from GitHub:
-
-```bash
-# Clone segger repo and install locally
-pip install -e .
-```
-
-# Usage
-
-You can run **segger** from the command line with:
 ```bash
 segger segment -i /path/to/your/ist/data/ -o /path/to/save/outputs/
+segger export  -s /path/to/save/outputs/segger_segmentation.parquet -o /path/to/export/
 ```
 
-To see all available parameter options:
-```bash
-segger segment --help
-```
+## Preprint
 
-## Exporting segmentation outputs for interoperability
+TODO: link
 
-`segger export` writes a segger segmentation to plain files from which a SpatialData object can be
-assembled. Name which elements to write: `anndata` (cell by gene table), `transcripts` (the assigned
-transcripts), or `boundaries` (one polygon per cell). With no element named it writes `anndata` and
-`boundaries`; add `transcripts` for the per-transcript assignment.
-```bash
-segger export                     -s outputs/segger_segmentation.parquet -i /path/to/ist/data/ -o export/   # anndata.h5ad + cell_boundaries.parquet
-segger export anndata transcripts -s outputs/segger_segmentation.parquet -i /path/to/ist/data/ -o export/   # select which elements to write
-```
-Boundaries are traced with `--method`: `delaunay` (the default) prunes a Delaunay triangulation into a
-concave outline, while `convex_hull` takes the convex hull; neither is smoothed by default, but
-`--chaikin-iterations` rounds them with that many rounds of Chaikin corner-cutting. The exported
-transcripts are controlled by `--include-all-transcripts`, `--min-similarity`, and `--min-transcripts`
-(see `segger export --help`).
+## Citation
 
-The column names follow SOPA's SpatialData conventions. `anndata.h5ad` and `cell_boundaries.parquet`
-share `cell_id`, the instance key SOPA uses to join a table to its shapes. `transcripts.parquet` keeps
-the segger assignment as `segger_cell_id` (plus `row_index`), a sibling column in the spirit of SOPA's
-`sopa_prior`, so it merges onto an existing transcripts dataframe by `row_index` without overwriting
-the vendor `cell_id`; its values match the `cell_id` in the other two files.
+TODO: citation

docs/Makefile

@@ -0,0 +1,15 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help clean html
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+html:
+	$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)

docs/about.rst

@@ -0,0 +1,25 @@
+About
+=====
+
+Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data
+
+`Preprint <https://www.biorxiv.org/content/10.1101/2025.03.14.643160v1.full.pdf>`_ | `GitHub <https://github.com/dpeerlab/segger>`_
+
+Segger is a graph neural network model for fast, accurate cell segmentation of imaging-based spatial transcriptomics data. It resolves transcript-to-cell assignments even in dense, overlapping tissue regions.
+
+Citation
+--------
+
+If you use segger in your research, please cite:
+
+    Heidari, E., Moorman, A., et al. Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data. *bioRxiv* (2025). https://doi.org/10.1101/2025.03.14.643160
+
+.. code-block:: bibtex
+
+   @article{heidari2025segger,
+     title={Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data},
+     author={Heidari, Elyas and Moorman, Andrew and others},
+     journal={bioRxiv},
+     year={2025},
+     doi={10.1101/2025.03.14.643160}
+   }

docs/api/export.rst

@@ -0,0 +1,42 @@
+segger export
+==============
+
+Positional arguments select which elements to write: ``anndata``, ``transcripts``,
+``boundaries``, ``spatialdata`` (default: ``anndata boundaries``). Run ``segger export --help``
+for the authoritative list.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``-s, --segmentation-path``
+     - *required*
+     - Path to ``segger_segmentation.parquet``.
+   * - ``-i, --source-path``
+     - None
+     - Source transcripts directory. Only needed for segger v0.2.0 outputs, which predate inline
+       ``x``/``y``/``feature_name`` columns.
+   * - ``-o, --output-directory``
+     - *required*
+     - Output directory.
+   * - ``--sdata``
+     - None
+     - Existing SpatialData Zarr store to copy into the output directory and add elements to
+       (required for the ``spatialdata`` element).
+   * - ``--method``
+     - delaunay
+     - Cell-polygon method for boundaries (``delaunay`` or ``convex_hull``).
+   * - ``--chaikin-iterations``
+     - 0
+     - Chaikin corner-cutting iterations to round boundaries (``0`` disables).
+   * - ``--include-all-transcripts``
+     - False
+     - Keep every cell-assigned transcript, ignoring the similarity threshold.
+   * - ``--min-similarity``
+     - None
+     - Fixed similarity threshold (0-1), overriding the per-gene threshold.
+   * - ``--min-transcripts``
+     - 10
+     - Minimum assigned transcripts a cell must have to be included.

docs/api/index.rst

@@ -0,0 +1,8 @@
+API reference
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   segment
+   export

docs/api/segment.rst

@@ -0,0 +1,183 @@
+segger segment
+===============
+
+All flags accept ``--flag value``; boolean flags accept ``--flag``/``--no-flag``. Run
+``segger segment --help`` for the authoritative list.
+
+I/O
+---
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``-i, --input-directory``
+     - *required*
+     - Standardized IST dataset directory.
+   * - ``-o, --output-directory``
+     - *required*
+     - Output directory.
+   * - ``--save-anndata``
+     - ``True``
+     - Also write ``segger_anndata.h5ad``.
+   * - ``--debug``
+     - ``False``
+     - Save additional debug info (trainer, predictions).
+
+Node representation
+--------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--node-representation-dim``
+     - 128
+     - Number of dimensions used to represent each node type.
+   * - ``--cells-representation``
+     - pca
+     - Feature representation used for cell embeddings (``pca`` or ``morphology``).
+   * - ``--cells-min-counts``
+     - 10
+     - Minimum transcript count threshold per cell.
+   * - ``--cells-clusters-n-neighbors``
+     - 10
+     - Number of neighbors for cell clustering.
+   * - ``--cells-clusters-resolution``
+     - 2.0
+     - Resolution parameter for cell clustering.
+   * - ``--genes-clusters-n-neighbors``
+     - 5
+     - Number of neighbors for gene clustering.
+   * - ``--genes-clusters-resolution``
+     - 2.0
+     - Resolution parameter for gene clustering.
+   * - ``--gene-corr-reference-path``
+     - None
+     - Reference AnnData ``.h5ad`` used to compute a shared gene-gene correlation matrix.
+   * - ``--gene-missing-strategy``
+     - error
+     - How to handle genes missing from the reference (``error``, ``remove``, ``fill``).
+
+Transcript-transcript graph
+-----------------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--transcripts-max-k``
+     - 5
+     - Maximum number of edges per transcript in the local graph.
+   * - ``--transcripts-max-dist``
+     - 5.0
+     - Maximum edge distance for transcript graph construction.
+
+Segmentation (prediction) graph
+---------------------------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--prediction-mode``
+     - cell
+     - Graph structure used during prediction (``nucleus``, ``cell``, ``uniform``).
+   * - ``--prediction-max-k``
+     - 3
+     - Maximum number of edges per transcript for prediction graphs.
+   * - ``--prediction-graph-buffer-ratio``
+     - 0.05
+     - Buffer ratio used to build the prediction graph.
+
+Tiling
+------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--tiling-margin-training``
+     - 20.0
+     - Margin width (µm) added to tiles during training.
+   * - ``--tiling-margin-prediction``
+     - 20.0
+     - Margin width (µm) added to tiles during prediction.
+   * - ``--max-nodes-per-tile``
+     - 50000
+     - Maximum number of nodes per tile.
+   * - ``--max-edges-per-batch``
+     - 1000000
+     - Maximum number of edges per DataLoader batch.
+
+Model
+-----
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--n-epochs``
+     - 20
+     - Number of training epochs.
+   * - ``--n-mid-layers``
+     - 2
+     - Number of mid layers in the encoder.
+   * - ``--n-heads``
+     - 2
+     - Number of attention heads.
+   * - ``--hidden-channels``
+     - 64
+     - Hidden channel dimension.
+   * - ``--out-channels``
+     - 64
+     - Output embedding dimension.
+   * - ``--learning-rate``
+     - 1e-3
+     - Learning rate.
+   * - ``--use-positional-embeddings``
+     - True
+     - Use positional embeddings.
+   * - ``--normalize-embeddings``
+     - True
+     - L2-normalize output embeddings.
+
+Loss
+----
+
+.. list-table::
+   :header-rows: 1
+
+   * - Flag
+     - Default
+     - Description
+   * - ``--segmentation-loss``
+     - triplet
+     - Loss type (``triplet`` or ``bce``).
+   * - ``--transcripts-margin``
+     - 0.3
+     - Triplet margin for transcript-transcript edges.
+   * - ``--segmentation-margin``
+     - 0.4
+     - Triplet margin for segmentation edges.
+   * - ``--transcripts-loss-weight-start`` / ``-end``
+     - 1.0 / 1.0
+     - Transcript loss weight at start/end of training.
+   * - ``--cells-loss-weight-start`` / ``-end``
+     - 1.0 / 1.0
+     - Cell loss weight at start/end of training.
+   * - ``--segmentation-loss-weight-start`` / ``-end``
+     - 0.0 / 0.5
+     - Segmentation loss weight at start/end of training.