segger 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. segger-1.0.0/.gitignore +153 -0
  2. segger-1.0.0/CHANGELOG.md +162 -0
  3. segger-1.0.0/LICENSE +21 -0
  4. segger-1.0.0/PKG-INFO +132 -0
  5. segger-1.0.0/README.md +80 -0
  6. segger-1.0.0/pyproject.toml +87 -0
  7. segger-1.0.0/src/segger/__init__.py +68 -0
  8. segger-1.0.0/src/segger/__main__.py +4 -0
  9. segger-1.0.0/src/segger/api.py +64 -0
  10. segger-1.0.0/src/segger/cli/__init__.py +0 -0
  11. segger-1.0.0/src/segger/cli/config.yaml +42 -0
  12. segger-1.0.0/src/segger/cli/debug.py +49 -0
  13. segger-1.0.0/src/segger/cli/export.py +433 -0
  14. segger-1.0.0/src/segger/cli/main.py +13 -0
  15. segger-1.0.0/src/segger/cli/registry.py +562 -0
  16. segger-1.0.0/src/segger/cli/segment.py +552 -0
  17. segger-1.0.0/src/segger/data/__init__.py +2 -0
  18. segger-1.0.0/src/segger/data/csr.py +182 -0
  19. segger-1.0.0/src/segger/data/data_module.py +501 -0
  20. segger-1.0.0/src/segger/data/partition/__init__.py +2 -0
  21. segger-1.0.0/src/segger/data/partition/dataset.py +618 -0
  22. segger-1.0.0/src/segger/data/partition/sampler.py +408 -0
  23. segger-1.0.0/src/segger/data/tile_dataset.py +414 -0
  24. segger-1.0.0/src/segger/data/tiling.py +324 -0
  25. segger-1.0.0/src/segger/data/utils/__init__.py +3 -0
  26. segger-1.0.0/src/segger/data/utils/anndata.py +316 -0
  27. segger-1.0.0/src/segger/data/utils/heterodata.py +195 -0
  28. segger-1.0.0/src/segger/data/utils/neighbors.py +238 -0
  29. segger-1.0.0/src/segger/data/utils/threshold.py +13 -0
  30. segger-1.0.0/src/segger/data/writer.py +268 -0
  31. segger-1.0.0/src/segger/debug/prediction.py +95 -0
  32. segger-1.0.0/src/segger/debug/segmentation.py +34 -0
  33. segger-1.0.0/src/segger/export/__init__.py +8 -0
  34. segger-1.0.0/src/segger/export/anndata_writer.py +54 -0
  35. segger-1.0.0/src/segger/export/boundary.py +233 -0
  36. segger-1.0.0/src/segger/geometry/__init__.py +8 -0
  37. segger-1.0.0/src/segger/geometry/morphology.py +43 -0
  38. segger-1.0.0/src/segger/geometry/quadtree.py +98 -0
  39. segger-1.0.0/src/segger/geometry/query.py +145 -0
  40. segger-1.0.0/src/segger/io/__init__.py +7 -0
  41. segger-1.0.0/src/segger/io/cosmx.py +170 -0
  42. segger-1.0.0/src/segger/io/fields.py +169 -0
  43. segger-1.0.0/src/segger/io/preprocessor.py +1420 -0
  44. segger-1.0.0/src/segger/io/utils.py +159 -0
  45. segger-1.0.0/src/segger/metrics/reference_contamination.py +0 -0
  46. segger-1.0.0/src/segger/models/__init__.py +1 -0
  47. segger-1.0.0/src/segger/models/_triplet_loss_dev.py +362 -0
  48. segger-1.0.0/src/segger/models/ist_encoder.py +337 -0
  49. segger-1.0.0/src/segger/models/lightning_model.py +283 -0
  50. segger-1.0.0/src/segger/models/torch_scatter_plugin.py +48 -0
  51. segger-1.0.0/src/segger/models/triplet_loss.py +205 -0
  52. segger-1.0.0/src/segger/utils.py +44 -0
  53. segger-1.0.0/src/segger/validation/contamination.py +408 -0
@@ -0,0 +1,153 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ .pdm-python
86
+ .pdm-build/
87
+ .pixi
88
+
89
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
90
+ __pypackages__/
91
+
92
+ # Celery stuff
93
+ celerybeat-schedule
94
+ celerybeat.pid
95
+
96
+ # SageMath parsed files
97
+ *.sage.py
98
+
99
+ # Environments
100
+ .env
101
+ .envrc
102
+ .venv
103
+ env/
104
+ venv/
105
+ ENV/
106
+ env.bak/
107
+ venv.bak/
108
+
109
+ # Spyder project settings
110
+ .spyderproject
111
+ .spyproject
112
+
113
+ # Rope project settings
114
+ .ropeproject
115
+
116
+ # mkdocs documentation
117
+ /site
118
+
119
+ # mypy
120
+ .mypy_cache/
121
+ .dmypy.json
122
+ dmypy.json
123
+ .pyre/
124
+ .pytype/
125
+
126
+ # Cython debug symbols
127
+ cython_debug/
128
+ .abstra/
129
+ .ruff_cache/
130
+
131
+ # PyPI configuration file
132
+ .pypirc
133
+
134
+ # Marimo
135
+ marimo/_static/
136
+ marimo/_lsp/
137
+ __marimo__/
138
+
139
+ # Streamlit
140
+ .streamlit/secrets.toml
141
+
142
+ # Custom
143
+ .dev
144
+ .dev/*
145
+ *.pyc
146
+ *memray*
147
+ rmm_log.txt
148
+ /nvidia/
149
+ nvidia/
150
+
151
+ # xeniumranger run output (created if `xeniumranger import-segmentation` is run from here)
152
+ _invocation_*.mro
153
+ /xenium_export/
@@ -0,0 +1,162 @@
1
+ # Changelog
2
+
3
+ ## [1.0.0] - 2026-11-19
4
+
5
+ First stable release with `cuspa` acceleration, scaling to atera-scale datasets and integrating
6
+ with community tools like Sopa. It skips `v0.4.0-manuscript`: a pre-stable version used only for
7
+ the manuscript, which already included the `cuspa` acceleration that is now cleanly integrated here.
8
+
9
+ ### Added
10
+ - `standard` input format for data prepared by other tools (e.g. Sopa), `segger segment --platform`
11
+ to choose the input format, and `segger.segment()` for in-memory transcripts and boundaries (#107).
12
+ - `segger export xeniumranger`: transcript assignment CSV and boundary GeoJSON for
13
+ `xeniumranger import-segmentation` (#89).
14
+ - `segger segment --export <elements>` runs `segger export` after segmentation (default `anndata`) (#110).
15
+ - PyPI packaging: package metadata, sdist contents and README image links are set up for publishing `segger` to PyPI (`uv pip install segger`) (#113).
16
+ - MIT license (#112).
17
+ - Docs: PyData theme, restructured how-to (#112), and a common-issues entry on rebuilding `cuspa`
18
+ for multiple GPU architectures (#114).
19
+
20
+ ### Changed
21
+ - cuSpatial is replaced by `cuspa` for point-in-polygon joins and by `fastquadtree` for quadtree
22
+ tiling; tile indexing uses CSR pointers (#91).
23
+ - CUDA 13 / Python >=3.13 is the only supported install path. CUDA 12 users: use `v0.3.0` (#91).
24
+ - Lower memory: multiple meassures to lower memory footprint and support large vectors exceeding int32 (#91).
25
+ - The export element `transcripts` is renamed `transcripts-filtered` (#110).
26
+ - `segger export` smooths boundaries by default: `--chaikin-iterations` is now 2 (was 0) (#109).
27
+ - `segger segment` logs its main steps at INFO and keeps Lightning's logs for `--debug`.
28
+ `scanpy>=1.13` is required (#111).
29
+
30
+ ### Fixed
31
+ - Predict shows a progress bar with an estimated batch count and reaches 100% when done (#108, #115).
32
+ - Predict no longer crashes on empty batches and keeps the full graph off the GPU; label counting
33
+ supports more than 2^31 entries on GPU (#115).
34
+ - `segger export transcripts-filtered` writes only the `filtered` transcripts by default (#112).
35
+ - `FastTripletSelector` no longer modifies the datamodule's cluster similarity tensor (#105).
36
+ - Warnings printed by `segger segment`: AnnData views modified in place, scanpy's deprecated
37
+ `normalize_total(layer=...)`, and `torch.jit` and Lightning deprecation notices (#111).
38
+ - RAPIDS dependencies must be `>=26`, otherwise `uv` would resolve to empty placeholder wheels (#91).
39
+ - `gene_missing_strategy="remove"` and the `gene_corr_reference` raw-count and `genes_min_counts`
40
+ checks (#91).
41
+
42
+ ### Removed
43
+ - `--save-anndata` and `segger_anndata.h5ad`; use `segger export anndata` (#110).
44
+ - `--cells-boundaries-file` and `--nucleus-boundaries-file`; use `--boundaries` and `--transcripts` (#107).
45
+ - The cuda121 environment (#91).
46
+
47
+ Thanks to @Intron7 for `cuspa`, @jtetrea for the CSR tile indexing design, @alihamraoui
48
+ for the segger API, @lemonardo1 for the `FastTripletSelector` fix, and @aelhossiny for the
49
+ multi-GPU `cuspa` build.
50
+
51
+ [1.0.0]: https://github.com/dpeerlab/segger/releases/tag/v1.0.0
52
+
53
+ ## [0.4.0-manuscript] - 2026-10-30
54
+
55
+ Pre-stable precursor of 1.0.0, branched off the main history; the version used for the revised manuscript.
56
+
57
+ [0.4.0-manuscript]: https://github.com/dpeerlab/segger/releases/tag/v0.4.0-manuscript
58
+
59
+ ## [0.3.1] - 2026-10-14
60
+
61
+ Bugfixes and reader updates for the CUDA 12 install, released before the 0.4.0 move to
62
+ CUDA 13.
63
+
64
+ ### Added
65
+ - `MerscopePreprocessor` reads Vizgen MERSCOPE datasets: `detected_transcripts.csv` or
66
+ `transcripts.parquet`, cell/nucleus assignments, and cell/nucleus boundary parquets (#60).
67
+ - `CosMXPreprocessor` reads real NanoString CosMX exports: CSV or parquet transcripts,
68
+ columns resolved by candidate names, and cell/nucleus polygons from masks (#63).
69
+ - `segger segment` options `--transcripts-cell-id`, `--cells-boundaries-file` and
70
+ `--nucleus-boundaries-file` for a custom cell-assignment column and boundary files (#98).
71
+ - `--segmentation-mode {nucleus,cell}` on `segger segment` selects the
72
+ segmentation used for training edges (#98).
73
+ - `imagecodecs` dependency for LZW-compressed TIFFs (#99).
74
+
75
+ ### Changed
76
+ - `segger segment` creates the output directory if it's missing. Its parent must exist.
77
+
78
+ ### Fixed
79
+ - Spatialdata export, which broke in 0.3.0 (#95).
80
+ - Export treats a missing `converged` column as True, so outputs from older versions still
81
+ export (#95).
82
+ - `segger segment` drops cells without a matching boundary, and their transcripts, with a
83
+ warning instead of failing an assert (#99).
84
+ - MultiPolygons and polygons with holes are reduced to the largest part's exterior ring
85
+ before conversion (#99).
86
+ - `edge_index` is cast to int64 for all edge types, so uint32 indices from cudf/cuspatial
87
+ no longer break partitioning (#99).
88
+
89
+ Thanks to @EliHei2 for the MERSCOPE and CosMX readers.
90
+
91
+ [0.3.1]: https://github.com/dpeerlab/segger/releases/tag/v0.3.1
92
+
93
+ ## [0.3.0] - 2026-09-15
94
+
95
+ ### Added
96
+ - `segger export spatialdata`: appends segger's per-transcript columns to an existing
97
+ SpatialData store's `transcripts` element in place, and adds `cell_boundaries_segger`
98
+ (shapes) and `table_segger` (table) elements. Element names are configurable with
99
+ `--sdata-transcripts-name`, `--sdata-cell-boundaries-name`, and `--sdata-table-name`.
100
+ - `-i/--source-path` is now optional on `segger export`, falling back to joining source
101
+ transcripts for legacy (pre-v0.2.0) segmentation outputs.
102
+ - `--min-counts` filter on `segger export`, enforced at `>= 3` for the `spatialdata` element
103
+ since boundaries need at least 3 points.
104
+ - An optional `z` coordinate threaded through export and the training writer.
105
+ - Cell-boundary generation now runs in parallel across CPUs.
106
+ - Sphinx documentation on ReadTheDocs: installation, quickstart, outputs, API reference,
107
+ and a common-issues page.
108
+
109
+ ### Changed
110
+ - `segger segment` pins the Lightning Trainer to a single device by default, avoiding the
111
+ crash multi-GPU SLURM allocations used to trigger.
112
+ - `export.py` relies directly on the `filtered` column instead of re-deriving it.
113
+
114
+ ### Fixed
115
+ - Quadtree leaf boundaries now match cuSpatial's actual clamped scale.
116
+ - Spatialdata export: pre-existing segger columns are dropped before merging transcripts,
117
+ and base-element transformations are propagated correctly.
118
+ - In-place spatialdata overwrite, and `row_index` is dropped from the written transcripts.
119
+ - Parallel boundary generation: fixed list unpacking and worker count.
120
+ - Spatialdata export elements are now written in place, avoiding a dask-expr crash.
121
+
122
+ Thanks to @enric-bazz for the initial SpatialData reader and writer code; to @EliHei2
123
+ for the export CLI, the boundary constructor, and the AnnData table export; to
124
+ @mossishahi for the initial AnnData export and boundary writers; to @MeyerBender for
125
+ critical feedback on the implementation design; and to @quentinblampey and
126
+ @alihamraoui for feedback on SOPA and dependency tracking.
127
+
128
+ [0.3.0]: https://github.com/dpeerlab/segger/releases/tag/v0.3.0
129
+
130
+ ## [0.2.0] - 2026-08-21
131
+
132
+ First tagged release. Marks the current `main` state of the segger pipeline.
133
+
134
+ ### Added
135
+ - Command-line interface (`segger`), with a `segment` entry point.
136
+ - `segger export` for scverse-compatible output, including a SOPA export path.
137
+ - `--save_anndata` option to export an AnnData object from the segmentation output
138
+ (written as `adata.h5ad`).
139
+ - Cell-boundary generation via Delaunay pruning, with a configurable `connectivity`
140
+ parameter; optional boundary smoothing (off by default).
141
+ - `--debug` mode with predict-only and segment-only stages, plus extensive debug
142
+ checkpoints and logging throughout prediction and segmentation.
143
+ - `convergence` column and `max_iter` callback for `threshold_li`; configurable
144
+ quantile fill for genes that fail to converge.
145
+ - Positional-embedding and embedding-normalization flags; morphology
146
+ representation option.
147
+ - Batched segmentation-graph construction for large inputs.
148
+
149
+ ### Changed
150
+ - Threshold calculation reworked into an iterative loop; `group_by`-based
151
+ thresholding (~5x speedup); default fill changed to Q50 for non-converged genes.
152
+ - Lowered default cell-expansion ratio; refactored the segmentation writer and CLI.
153
+ - RMM/NVIDIA allocators are configured only when running the CLI.
154
+
155
+ ### Fixed
156
+ - Handle shapely errors from invalid polygons.
157
+ - Tiling: fall back to a smaller margin instead of dropping tiles.
158
+ - CLI argument bugs; corrected the `segment --debug` default; removed
159
+ un-segmented transcripts from threshold calculations.
160
+ - `quadtree.py` max-depth handling.
161
+
162
+ [0.2.0]: https://github.com/dpeerlab/segger/releases/tag/v0.2.0
segger-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Pe'er Lab and Stegle Lab
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
segger-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,132 @@
1
+ Metadata-Version: 2.5
2
+ Name: segger
3
+ Version: 1.0.0
4
+ Summary: Segmentation of spatial transcriptomics data
5
+ Project-URL: Homepage, https://github.com/dpeerlab/segger
6
+ Project-URL: Documentation, https://segger-segmentation.readthedocs.io/en/latest/
7
+ Project-URL: Repository, https://github.com/dpeerlab/segger
8
+ Project-URL: Changelog, https://github.com/dpeerlab/segger/blob/main/CHANGELOG.md
9
+ Project-URL: Issues, https://github.com/dpeerlab/segger/issues
10
+ Author-email: Elyas Heidari <elyas.heidari@dkfz-heidelberg.de>, Andrew Moorman <moormana@mskcc.org>
11
+ License-Expression: MIT
12
+ License-File: LICENSE
13
+ Keywords: image-analysis,segmentation,spatial-transcriptomics
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Science/Research
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
20
+ Requires-Python: <3.14,>=3.13
21
+ Requires-Dist: anndata
22
+ Requires-Dist: cudf-cu13>=26
23
+ Requires-Dist: cugraph-cu13>=26
24
+ Requires-Dist: cuml-cu13>=26
25
+ Requires-Dist: cupy-cuda13x
26
+ Requires-Dist: cuspa-cu13
27
+ Requires-Dist: cyclopts
28
+ Requires-Dist: fastquadtree
29
+ Requires-Dist: geopandas
30
+ Requires-Dist: imagecodecs
31
+ Requires-Dist: lightning
32
+ Requires-Dist: numba
33
+ Requires-Dist: numpy
34
+ Requires-Dist: opencv-python
35
+ Requires-Dist: pandas
36
+ Requires-Dist: polars
37
+ Requires-Dist: pyarrow
38
+ Requires-Dist: rmm-cu13>=26
39
+ Requires-Dist: scanpy>=1.13
40
+ Requires-Dist: scikit-image
41
+ Requires-Dist: scikit-learn
42
+ Requires-Dist: scipy
43
+ Requires-Dist: shapely
44
+ Requires-Dist: tifffile
45
+ Requires-Dist: torch-geometric
46
+ Requires-Dist: torch==2.14.*
47
+ Requires-Dist: torchvision
48
+ Requires-Dist: tqdm
49
+ Provides-Extra: spatialdata
50
+ Requires-Dist: spatialdata; extra == 'spatialdata'
51
+ Description-Content-Type: text/markdown
52
+
53
+ # segger
54
+
55
+ [![Release](https://img.shields.io/github/v/release/dpeerlab/segger)](https://github.com/dpeerlab/segger/releases)
56
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
57
+ [![Docs](https://img.shields.io/badge/docs-Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=white)](https://segger-segmentation.readthedocs.io/en/latest/)
58
+ [![Python 3.13](https://img.shields.io/badge/python-3.13-blue)](https://www.python.org/)
59
+ [![CUDA 13](https://img.shields.io/badge/CUDA-13-76B900)](https://developer.nvidia.com/cuda-toolkit)
60
+ [![Powered by cuspa](https://img.shields.io/badge/powered%20by-cuspa-76B900)](https://github.com/NVIDIA/cuspa)
61
+
62
+ Cell segmentation for imaging-based spatial transcriptomics as graph-based transcript–cell assignment.
63
+
64
+ ![segger overview](https://raw.githubusercontent.com/dpeerlab/segger/main/segger_overview.png)
65
+
66
+ > Segger is a graph neural network (GNN)-based method that formulates cell segmentation in imaging-based spatial transcriptomics (iST) as a problem of transcript–cell assignment. Rather than relying solely on geometric proximity, Segger assumes that a transcript belongs to a cell if it is consistent both with its local spatial context and with the gene expression programs that define cell identity, as captured in a shared latent representation.
67
+ >
68
+ > — [Heidari, Moorman, et al., segger methods description](segger_methods.pdf)
69
+
70
+ > [!NOTE]
71
+ > This release uses [`cuspa`](https://github.com/NVIDIA/cuspa), which we developed together with NVIDIA, to support atera-scale,
72
+ > billion-transcript whole-transcriptome datasets. It requires CUDA 13 and Python 3.13.
73
+
74
+ Full documentation - installation, quickstart, outputs, API reference, etc.:
75
+ [segger-segmentation.readthedocs.io](https://segger-segmentation.readthedocs.io/en/latest/)
76
+
77
+ ## Installation
78
+
79
+ **segger** requires CUDA 13 and Python 3.13.
80
+
81
+ ```bash
82
+ uv pip install segger
83
+ ```
84
+
85
+ For conda, pixi, installing from source and older CUDA versions, see the [installation docs](https://segger-segmentation.readthedocs.io/en/latest/installation.html).
86
+
87
+ ### Container
88
+
89
+ On HPC clusters, run the Docker image with Apptainer/Singularity. Pull it once (about 10-20 minutes), then run on a GPU node with `--nv`:
90
+
91
+ ```bash
92
+ export APPTAINER_CACHEDIR=/path/to/cachedir
93
+ apptainer pull segger.sif docker://sailmskcc/segger:latest
94
+ apptainer exec --nv segger.sif segger --help
95
+ ```
96
+
97
+ For Docker, see [Use a container](https://segger-segmentation.readthedocs.io/en/latest/installation.html#use-a-container).
98
+
99
+ ## Usage
100
+
101
+ ```bash
102
+ segger segment \
103
+ -i /path/to/your/ist/data/ \
104
+ -o /path/to/save/outputs/ \
105
+ --export anndata boundaries # optional (e.g. anndata, boundaries, xeniumranger, ...)
106
+ ```
107
+
108
+ See [notebooks/quickstart.ipynb](notebooks/quickstart.ipynb) for an end-to-end walkthrough.
109
+
110
+ If you run into a problem, first check the [GitHub issues](https://github.com/dpeerlab/segger/issues) and the [known issues](https://segger-segmentation.readthedocs.io/en/latest/common-issues.html) in the docs.
111
+
112
+ ## Contributing
113
+
114
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
115
+
116
+ ## Methods description
117
+
118
+ [Heidari, E., Moorman, A., et al. Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data. Methods description (2026).](segger_methods.pdf)
119
+
120
+ ## Citation
121
+
122
+ If you use segger in your research, please cite:
123
+
124
+ ```bibtex
125
+ @misc{heidari2026segger,
126
+ title={Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data},
127
+ author={Heidari, Elyas and Moorman, Andrew and others},
128
+ note={Methods description},
129
+ year={2026},
130
+ howpublished={\url{https://github.com/dpeerlab/segger/blob/main/segger_methods.pdf}}
131
+ }
132
+ ```
segger-1.0.0/README.md ADDED
@@ -0,0 +1,80 @@
1
+ # segger
2
+
3
+ [![Release](https://img.shields.io/github/v/release/dpeerlab/segger)](https://github.com/dpeerlab/segger/releases)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
5
+ [![Docs](https://img.shields.io/badge/docs-Read%20the%20Docs-8CA1AF?logo=readthedocs&logoColor=white)](https://segger-segmentation.readthedocs.io/en/latest/)
6
+ [![Python 3.13](https://img.shields.io/badge/python-3.13-blue)](https://www.python.org/)
7
+ [![CUDA 13](https://img.shields.io/badge/CUDA-13-76B900)](https://developer.nvidia.com/cuda-toolkit)
8
+ [![Powered by cuspa](https://img.shields.io/badge/powered%20by-cuspa-76B900)](https://github.com/NVIDIA/cuspa)
9
+
10
+ Cell segmentation for imaging-based spatial transcriptomics as graph-based transcript–cell assignment.
11
+
12
+ ![segger overview](https://raw.githubusercontent.com/dpeerlab/segger/main/segger_overview.png)
13
+
14
+ > Segger is a graph neural network (GNN)-based method that formulates cell segmentation in imaging-based spatial transcriptomics (iST) as a problem of transcript–cell assignment. Rather than relying solely on geometric proximity, Segger assumes that a transcript belongs to a cell if it is consistent both with its local spatial context and with the gene expression programs that define cell identity, as captured in a shared latent representation.
15
+ >
16
+ > — [Heidari, Moorman, et al., segger methods description](segger_methods.pdf)
17
+
18
+ > [!NOTE]
19
+ > This release uses [`cuspa`](https://github.com/NVIDIA/cuspa), which we developed together with NVIDIA, to support atera-scale,
20
+ > billion-transcript whole-transcriptome datasets. It requires CUDA 13 and Python 3.13.
21
+
22
+ Full documentation - installation, quickstart, outputs, API reference, etc.:
23
+ [segger-segmentation.readthedocs.io](https://segger-segmentation.readthedocs.io/en/latest/)
24
+
25
+ ## Installation
26
+
27
+ **segger** requires CUDA 13 and Python 3.13.
28
+
29
+ ```bash
30
+ uv pip install segger
31
+ ```
32
+
33
+ For conda, pixi, installing from source and older CUDA versions, see the [installation docs](https://segger-segmentation.readthedocs.io/en/latest/installation.html).
34
+
35
+ ### Container
36
+
37
+ On HPC clusters, run the Docker image with Apptainer/Singularity. Pull it once (about 10-20 minutes), then run on a GPU node with `--nv`:
38
+
39
+ ```bash
40
+ export APPTAINER_CACHEDIR=/path/to/cachedir
41
+ apptainer pull segger.sif docker://sailmskcc/segger:latest
42
+ apptainer exec --nv segger.sif segger --help
43
+ ```
44
+
45
+ For Docker, see [Use a container](https://segger-segmentation.readthedocs.io/en/latest/installation.html#use-a-container).
46
+
47
+ ## Usage
48
+
49
+ ```bash
50
+ segger segment \
51
+ -i /path/to/your/ist/data/ \
52
+ -o /path/to/save/outputs/ \
53
+ --export anndata boundaries # optional (e.g. anndata, boundaries, xeniumranger, ...)
54
+ ```
55
+
56
+ See [notebooks/quickstart.ipynb](notebooks/quickstart.ipynb) for an end-to-end walkthrough.
57
+
58
+ If you run into a problem, first check the [GitHub issues](https://github.com/dpeerlab/segger/issues) and the [known issues](https://segger-segmentation.readthedocs.io/en/latest/common-issues.html) in the docs.
59
+
60
+ ## Contributing
61
+
62
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
63
+
64
+ ## Methods description
65
+
66
+ [Heidari, E., Moorman, A., et al. Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data. Methods description (2026).](segger_methods.pdf)
67
+
68
+ ## Citation
69
+
70
+ If you use segger in your research, please cite:
71
+
72
+ ```bibtex
73
+ @misc{heidari2026segger,
74
+ title={Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data},
75
+ author={Heidari, Elyas and Moorman, Andrew and others},
76
+ note={Methods description},
77
+ year={2026},
78
+ howpublished={\url{https://github.com/dpeerlab/segger/blob/main/segger_methods.pdf}}
79
+ }
80
+ ```
@@ -0,0 +1,87 @@
1
+ [project]
2
+ name = "segger"
3
+ version = "1.0.0"
4
+ description = "Segmentation of spatial transcriptomics data"
5
+ authors = [
6
+ {name = "Elyas Heidari", email = "elyas.heidari@dkfz-heidelberg.de"},
7
+ {name = "Andrew Moorman", email = "moormana@mskcc.org"},
8
+ ]
9
+ keywords = ["spatial-transcriptomics", "segmentation", "image-analysis"]
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ readme = "README.md"
13
+ requires-python = ">=3.13,<3.14"
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Science/Research",
17
+ "Operating System :: POSIX :: Linux",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.13",
20
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
21
+ ]
22
+
23
+ dependencies = [
24
+ "anndata",
25
+ "cyclopts",
26
+ "fastquadtree",
27
+ "geopandas",
28
+ "imagecodecs",
29
+ "numba",
30
+ "numpy",
31
+ "opencv-python",
32
+ "pandas",
33
+ "polars",
34
+ "pyarrow",
35
+ "scanpy>=1.13",
36
+ "scipy",
37
+ "shapely",
38
+ "scikit-image",
39
+ "scikit-learn",
40
+ "tifffile",
41
+ "tqdm",
42
+ # CUDA 13 GPU stack (incl. cuspa)
43
+ "torch==2.14.*",
44
+ "torchvision",
45
+ "lightning",
46
+ "torch_geometric",
47
+ "cuspa-cu13",
48
+ # add floors to avoid resolving to placeholder wheels
49
+ "cudf-cu13>=26",
50
+ "cuml-cu13>=26",
51
+ "cugraph-cu13>=26",
52
+ "cupy-cuda13x",
53
+ "rmm-cu13>=26",
54
+ ]
55
+
56
+ [project.urls]
57
+ Homepage = "https://github.com/dpeerlab/segger"
58
+ Documentation = "https://segger-segmentation.readthedocs.io/en/latest/"
59
+ Repository = "https://github.com/dpeerlab/segger"
60
+ Changelog = "https://github.com/dpeerlab/segger/blob/main/CHANGELOG.md"
61
+ Issues = "https://github.com/dpeerlab/segger/issues"
62
+
63
+ [project.optional-dependencies]
64
+ spatialdata = ["spatialdata"]
65
+
66
+ [build-system]
67
+ requires = ["hatchling>=1.27"]
68
+ build-backend = "hatchling.build"
69
+
70
+ [tool.hatch.build.targets.wheel]
71
+ packages = ["src/segger"]
72
+
73
+ # keep notebooks, docs, scripts and large figures out of the sdist
74
+ [tool.hatch.build.targets.sdist]
75
+ include = ["/src", "/README.md", "/CHANGELOG.md", "/LICENSE", "/pyproject.toml"]
76
+
77
+ [project.scripts]
78
+ segger = "segger.cli.main:app"
79
+
80
+ [tool.uv]
81
+ index-strategy = "unsafe-best-match"
82
+
83
+ [[tool.uv.index]]
84
+ url = "https://download.pytorch.org/whl/cu130"
85
+
86
+ [[tool.uv.index]]
87
+ url = "https://pypi.nvidia.com"