segger 1.0.0rc1__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.
- segger-1.0.0rc1/.gitignore +153 -0
- segger-1.0.0rc1/CHANGELOG.md +111 -0
- segger-1.0.0rc1/PKG-INFO +150 -0
- segger-1.0.0rc1/README.md +99 -0
- segger-1.0.0rc1/pyproject.toml +87 -0
- segger-1.0.0rc1/src/segger/__init__.py +68 -0
- segger-1.0.0rc1/src/segger/__main__.py +4 -0
- segger-1.0.0rc1/src/segger/api.py +64 -0
- segger-1.0.0rc1/src/segger/cli/__init__.py +0 -0
- segger-1.0.0rc1/src/segger/cli/config.yaml +42 -0
- segger-1.0.0rc1/src/segger/cli/debug.py +49 -0
- segger-1.0.0rc1/src/segger/cli/export.py +433 -0
- segger-1.0.0rc1/src/segger/cli/main.py +13 -0
- segger-1.0.0rc1/src/segger/cli/registry.py +562 -0
- segger-1.0.0rc1/src/segger/cli/segment.py +569 -0
- segger-1.0.0rc1/src/segger/data/__init__.py +2 -0
- segger-1.0.0rc1/src/segger/data/csr.py +179 -0
- segger-1.0.0rc1/src/segger/data/data_module.py +503 -0
- segger-1.0.0rc1/src/segger/data/partition/__init__.py +2 -0
- segger-1.0.0rc1/src/segger/data/partition/dataset.py +618 -0
- segger-1.0.0rc1/src/segger/data/partition/sampler.py +408 -0
- segger-1.0.0rc1/src/segger/data/tile_dataset.py +402 -0
- segger-1.0.0rc1/src/segger/data/tiling.py +324 -0
- segger-1.0.0rc1/src/segger/data/utils/__init__.py +3 -0
- segger-1.0.0rc1/src/segger/data/utils/anndata.py +316 -0
- segger-1.0.0rc1/src/segger/data/utils/heterodata.py +195 -0
- segger-1.0.0rc1/src/segger/data/utils/neighbors.py +238 -0
- segger-1.0.0rc1/src/segger/data/utils/threshold.py +13 -0
- segger-1.0.0rc1/src/segger/data/writer.py +268 -0
- segger-1.0.0rc1/src/segger/debug/prediction.py +95 -0
- segger-1.0.0rc1/src/segger/debug/segmentation.py +34 -0
- segger-1.0.0rc1/src/segger/export/__init__.py +8 -0
- segger-1.0.0rc1/src/segger/export/anndata_writer.py +54 -0
- segger-1.0.0rc1/src/segger/export/boundary.py +233 -0
- segger-1.0.0rc1/src/segger/geometry/__init__.py +8 -0
- segger-1.0.0rc1/src/segger/geometry/morphology.py +43 -0
- segger-1.0.0rc1/src/segger/geometry/quadtree.py +98 -0
- segger-1.0.0rc1/src/segger/geometry/query.py +145 -0
- segger-1.0.0rc1/src/segger/io/__init__.py +7 -0
- segger-1.0.0rc1/src/segger/io/cosmx.py +170 -0
- segger-1.0.0rc1/src/segger/io/fields.py +169 -0
- segger-1.0.0rc1/src/segger/io/preprocessor.py +1420 -0
- segger-1.0.0rc1/src/segger/io/utils.py +159 -0
- segger-1.0.0rc1/src/segger/metrics/reference_contamination.py +0 -0
- segger-1.0.0rc1/src/segger/models/__init__.py +1 -0
- segger-1.0.0rc1/src/segger/models/_triplet_loss_dev.py +362 -0
- segger-1.0.0rc1/src/segger/models/ist_encoder.py +337 -0
- segger-1.0.0rc1/src/segger/models/lightning_model.py +300 -0
- segger-1.0.0rc1/src/segger/models/torch_scatter_plugin.py +48 -0
- segger-1.0.0rc1/src/segger/models/triplet_loss.py +205 -0
- segger-1.0.0rc1/src/segger/utils.py +44 -0
- segger-1.0.0rc1/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,111 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
- PyPI packaging: package metadata, sdist contents and README image links are set up for publishing `segger` to PyPI, starting with release candidates.
|
|
7
|
+
|
|
8
|
+
## [0.3.1] - 2026-10-14
|
|
9
|
+
|
|
10
|
+
Bugfixes and reader updates for the CUDA 12 install, released before the 0.4.0 move to
|
|
11
|
+
CUDA 13.
|
|
12
|
+
|
|
13
|
+
### Added
|
|
14
|
+
- `MerscopePreprocessor` reads Vizgen MERSCOPE datasets: `detected_transcripts.csv` or
|
|
15
|
+
`transcripts.parquet`, cell/nucleus assignments, and cell/nucleus boundary parquets (#60).
|
|
16
|
+
- `CosMXPreprocessor` reads real NanoString CosMX exports: CSV or parquet transcripts,
|
|
17
|
+
columns resolved by candidate names, and cell/nucleus polygons from masks (#63).
|
|
18
|
+
- `segger segment` options `--transcripts-cell-id`, `--cells-boundaries-file` and
|
|
19
|
+
`--nucleus-boundaries-file` for a custom cell-assignment column and boundary files (#98).
|
|
20
|
+
- `--segmentation-mode {nucleus,cell}` on `segger segment` selects the
|
|
21
|
+
segmentation used for training edges (#98).
|
|
22
|
+
- `imagecodecs` dependency for LZW-compressed TIFFs (#99).
|
|
23
|
+
|
|
24
|
+
### Changed
|
|
25
|
+
- `segger segment` creates the output directory if it's missing. Its parent must exist.
|
|
26
|
+
|
|
27
|
+
### Fixed
|
|
28
|
+
- Spatialdata export, which broke in 0.3.0 (#95).
|
|
29
|
+
- Export treats a missing `converged` column as True, so outputs from older versions still
|
|
30
|
+
export (#95).
|
|
31
|
+
- `segger segment` drops cells without a matching boundary, and their transcripts, with a
|
|
32
|
+
warning instead of failing an assert (#99).
|
|
33
|
+
- MultiPolygons and polygons with holes are reduced to the largest part's exterior ring
|
|
34
|
+
before conversion (#99).
|
|
35
|
+
- `edge_index` is cast to int64 for all edge types, so uint32 indices from cudf/cuspatial
|
|
36
|
+
no longer break partitioning (#99).
|
|
37
|
+
|
|
38
|
+
Thanks to @EliHei2 for the MERSCOPE and CosMX readers.
|
|
39
|
+
|
|
40
|
+
[0.3.1]: https://github.com/dpeerlab/segger/releases/tag/v0.3.1
|
|
41
|
+
|
|
42
|
+
## [0.3.0] - 2026-09-15
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
- `segger export spatialdata`: appends segger's per-transcript columns to an existing
|
|
46
|
+
SpatialData store's `transcripts` element in place, and adds `cell_boundaries_segger`
|
|
47
|
+
(shapes) and `table_segger` (table) elements. Element names are configurable with
|
|
48
|
+
`--sdata-transcripts-name`, `--sdata-cell-boundaries-name`, and `--sdata-table-name`.
|
|
49
|
+
- `-i/--source-path` is now optional on `segger export`, falling back to joining source
|
|
50
|
+
transcripts for legacy (pre-v0.2.0) segmentation outputs.
|
|
51
|
+
- `--min-counts` filter on `segger export`, enforced at `>= 3` for the `spatialdata` element
|
|
52
|
+
since boundaries need at least 3 points.
|
|
53
|
+
- An optional `z` coordinate threaded through export and the training writer.
|
|
54
|
+
- Cell-boundary generation now runs in parallel across CPUs.
|
|
55
|
+
- Sphinx documentation on ReadTheDocs: installation, quickstart, outputs, API reference,
|
|
56
|
+
and a common-issues page.
|
|
57
|
+
|
|
58
|
+
### Changed
|
|
59
|
+
- `segger segment` pins the Lightning Trainer to a single device by default, avoiding the
|
|
60
|
+
crash multi-GPU SLURM allocations used to trigger.
|
|
61
|
+
- `export.py` relies directly on the `filtered` column instead of re-deriving it.
|
|
62
|
+
|
|
63
|
+
### Fixed
|
|
64
|
+
- Quadtree leaf boundaries now match cuSpatial's actual clamped scale.
|
|
65
|
+
- Spatialdata export: pre-existing segger columns are dropped before merging transcripts,
|
|
66
|
+
and base-element transformations are propagated correctly.
|
|
67
|
+
- In-place spatialdata overwrite, and `row_index` is dropped from the written transcripts.
|
|
68
|
+
- Parallel boundary generation: fixed list unpacking and worker count.
|
|
69
|
+
- Spatialdata export elements are now written in place, avoiding a dask-expr crash.
|
|
70
|
+
|
|
71
|
+
Thanks to @enric-bazz for the initial SpatialData reader and writer code; to @EliHei2
|
|
72
|
+
for the export CLI, the boundary constructor, and the AnnData table export; to
|
|
73
|
+
@mossishahi for the initial AnnData export and boundary writers; to @MeyerBender for
|
|
74
|
+
critical feedback on the implementation design; and to @quentinblampey and
|
|
75
|
+
@alihamraoui for feedback on SOPA and dependency tracking.
|
|
76
|
+
|
|
77
|
+
[0.3.0]: https://github.com/dpeerlab/segger/releases/tag/v0.3.0
|
|
78
|
+
|
|
79
|
+
## [0.2.0] - 2026-08-21
|
|
80
|
+
|
|
81
|
+
First tagged release. Marks the current `main` state of the segger pipeline.
|
|
82
|
+
|
|
83
|
+
### Added
|
|
84
|
+
- Command-line interface (`segger`), with a `segment` entry point.
|
|
85
|
+
- `segger export` for scverse-compatible output, including a SOPA export path.
|
|
86
|
+
- `--save_anndata` option to export an AnnData object from the segmentation output
|
|
87
|
+
(written as `adata.h5ad`).
|
|
88
|
+
- Cell-boundary generation via Delaunay pruning, with a configurable `connectivity`
|
|
89
|
+
parameter; optional boundary smoothing (off by default).
|
|
90
|
+
- `--debug` mode with predict-only and segment-only stages, plus extensive debug
|
|
91
|
+
checkpoints and logging throughout prediction and segmentation.
|
|
92
|
+
- `convergence` column and `max_iter` callback for `threshold_li`; configurable
|
|
93
|
+
quantile fill for genes that fail to converge.
|
|
94
|
+
- Positional-embedding and embedding-normalization flags; morphology
|
|
95
|
+
representation option.
|
|
96
|
+
- Batched segmentation-graph construction for large inputs.
|
|
97
|
+
|
|
98
|
+
### Changed
|
|
99
|
+
- Threshold calculation reworked into an iterative loop; `group_by`-based
|
|
100
|
+
thresholding (~5x speedup); default fill changed to Q50 for non-converged genes.
|
|
101
|
+
- Lowered default cell-expansion ratio; refactored the segmentation writer and CLI.
|
|
102
|
+
- RMM/NVIDIA allocators are configured only when running the CLI.
|
|
103
|
+
|
|
104
|
+
### Fixed
|
|
105
|
+
- Handle shapely errors from invalid polygons.
|
|
106
|
+
- Tiling: fall back to a smaller margin instead of dropping tiles.
|
|
107
|
+
- CLI argument bugs; corrected the `segment --debug` default; removed
|
|
108
|
+
un-segmented transcripts from threshold calculations.
|
|
109
|
+
- `quadtree.py` max-depth handling.
|
|
110
|
+
|
|
111
|
+
[0.2.0]: https://github.com/dpeerlab/segger/releases/tag/v0.2.0
|
segger-1.0.0rc1/PKG-INFO
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: segger
|
|
3
|
+
Version: 1.0.0rc1
|
|
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
|
+
Keywords: image-analysis,segmentation,spatial-transcriptomics
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
19
|
+
Requires-Python: <3.14,>=3.13
|
|
20
|
+
Requires-Dist: anndata
|
|
21
|
+
Requires-Dist: cudf-cu13>=26
|
|
22
|
+
Requires-Dist: cugraph-cu13>=26
|
|
23
|
+
Requires-Dist: cuml-cu13>=26
|
|
24
|
+
Requires-Dist: cupy-cuda13x
|
|
25
|
+
Requires-Dist: cuspa-cu13
|
|
26
|
+
Requires-Dist: cyclopts
|
|
27
|
+
Requires-Dist: fastquadtree
|
|
28
|
+
Requires-Dist: geopandas
|
|
29
|
+
Requires-Dist: imagecodecs
|
|
30
|
+
Requires-Dist: lightning
|
|
31
|
+
Requires-Dist: numba
|
|
32
|
+
Requires-Dist: numpy
|
|
33
|
+
Requires-Dist: opencv-python
|
|
34
|
+
Requires-Dist: pandas
|
|
35
|
+
Requires-Dist: polars
|
|
36
|
+
Requires-Dist: pyarrow
|
|
37
|
+
Requires-Dist: rmm-cu13>=26
|
|
38
|
+
Requires-Dist: scanpy>=1.13
|
|
39
|
+
Requires-Dist: scikit-image
|
|
40
|
+
Requires-Dist: scikit-learn
|
|
41
|
+
Requires-Dist: scipy
|
|
42
|
+
Requires-Dist: shapely
|
|
43
|
+
Requires-Dist: tifffile
|
|
44
|
+
Requires-Dist: torch-geometric
|
|
45
|
+
Requires-Dist: torch==2.14.*
|
|
46
|
+
Requires-Dist: torchvision
|
|
47
|
+
Requires-Dist: tqdm
|
|
48
|
+
Provides-Extra: spatialdata
|
|
49
|
+
Requires-Dist: spatialdata; extra == 'spatialdata'
|
|
50
|
+
Description-Content-Type: text/markdown
|
|
51
|
+
|
|
52
|
+
# segger
|
|
53
|
+
|
|
54
|
+
GNN-based cell segmentation of spatial transcriptomics data.
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
58
|
+
> 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.
|
|
59
|
+
>
|
|
60
|
+
> — [Heidari, Moorman, et al., segger methods description](segger_methods.pdf)
|
|
61
|
+
|
|
62
|
+
> [!IMPORTANT]
|
|
63
|
+
> **Latest cuspa-accelerated segger:** the version used for the manuscript, which scales to billion-transcript
|
|
64
|
+
> whole-transcriptome datasets (e.g. Atera) using NVIDIA `cuspa`, is available as
|
|
65
|
+
> [release **v0.4.0-manuscript**](https://github.com/dpeerlab/segger/releases/tag/v0.4.0-manuscript).
|
|
66
|
+
> It requires CUDA 13 and Python 3.13 and is **not yet stable**. To install it:
|
|
67
|
+
>
|
|
68
|
+
> ```bash
|
|
69
|
+
> git clone --branch v0.4.0-manuscript https://github.com/dpeerlab/segger.git && cd segger
|
|
70
|
+
> pixi install # or: conda env create -n segger -f environment.yml
|
|
71
|
+
> ```
|
|
72
|
+
>
|
|
73
|
+
> The instructions below install the stable release on `main`.
|
|
74
|
+
|
|
75
|
+
Full documentation - installation, quickstart, outputs, API reference, etc.:
|
|
76
|
+
[segger-segmentation.readthedocs.io](https://segger-segmentation.readthedocs.io/en/latest/)
|
|
77
|
+
|
|
78
|
+
## Installation
|
|
79
|
+
|
|
80
|
+
**segger** requires CUDA 13 and Python 3.13.
|
|
81
|
+
|
|
82
|
+
Clone the repo, then use `conda` or `pixi`:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
git clone https://github.com/dpeerlab/segger.git && cd segger
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# conda
|
|
90
|
+
conda env create -n segger -f environment.yml
|
|
91
|
+
conda activate segger
|
|
92
|
+
|
|
93
|
+
# pixi
|
|
94
|
+
pixi install
|
|
95
|
+
pixi shell
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Alternatively, install directly from GitHub without cloning:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
pip install --extra-index-url https://pypi.nvidia.com --extra-index-url https://download.pytorch.org/whl/cu130 git+https://github.com/dpeerlab/segger.git
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Usage
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
segger segment \
|
|
108
|
+
-i /path/to/your/ist/data/ \
|
|
109
|
+
-o /path/to/save/outputs/
|
|
110
|
+
|
|
111
|
+
# export different data formats (e.g. boundaries, spatialdata, anndata, xeniumranger, ...)
|
|
112
|
+
segger export boundaries \
|
|
113
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
114
|
+
-o /path/to/export/
|
|
115
|
+
|
|
116
|
+
# export spatialdata. transcripts are added to the existing sdata
|
|
117
|
+
segger export spatialdata \
|
|
118
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
119
|
+
--sdata /path/to/sdata.zarr
|
|
120
|
+
|
|
121
|
+
# for Xenium data to visualise in xenium explorer
|
|
122
|
+
segger export xeniumranger \
|
|
123
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
124
|
+
-i /path/to/your/ist/data/ \
|
|
125
|
+
-o /path/to/export/
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
See [notebooks/quickstart.ipynb](notebooks/quickstart.ipynb) for an end-to-end walkthrough.
|
|
129
|
+
|
|
130
|
+
## Contributing
|
|
131
|
+
|
|
132
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
133
|
+
|
|
134
|
+
## Methods description
|
|
135
|
+
|
|
136
|
+
[Heidari, E., Moorman, A., et al. Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data. Methods description (2026).](segger_methods.pdf)
|
|
137
|
+
|
|
138
|
+
## Citation
|
|
139
|
+
|
|
140
|
+
If you use segger in your research, please cite:
|
|
141
|
+
|
|
142
|
+
```bibtex
|
|
143
|
+
@misc{heidari2026segger,
|
|
144
|
+
title={Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data},
|
|
145
|
+
author={Heidari, Elyas and Moorman, Andrew and others},
|
|
146
|
+
note={Methods description},
|
|
147
|
+
year={2026},
|
|
148
|
+
howpublished={\url{https://github.com/dpeerlab/segger/blob/main/segger_methods.pdf}}
|
|
149
|
+
}
|
|
150
|
+
```
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# segger
|
|
2
|
+
|
|
3
|
+
GNN-based cell segmentation of spatial transcriptomics data.
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
> 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.
|
|
8
|
+
>
|
|
9
|
+
> — [Heidari, Moorman, et al., segger methods description](segger_methods.pdf)
|
|
10
|
+
|
|
11
|
+
> [!IMPORTANT]
|
|
12
|
+
> **Latest cuspa-accelerated segger:** the version used for the manuscript, which scales to billion-transcript
|
|
13
|
+
> whole-transcriptome datasets (e.g. Atera) using NVIDIA `cuspa`, is available as
|
|
14
|
+
> [release **v0.4.0-manuscript**](https://github.com/dpeerlab/segger/releases/tag/v0.4.0-manuscript).
|
|
15
|
+
> It requires CUDA 13 and Python 3.13 and is **not yet stable**. To install it:
|
|
16
|
+
>
|
|
17
|
+
> ```bash
|
|
18
|
+
> git clone --branch v0.4.0-manuscript https://github.com/dpeerlab/segger.git && cd segger
|
|
19
|
+
> pixi install # or: conda env create -n segger -f environment.yml
|
|
20
|
+
> ```
|
|
21
|
+
>
|
|
22
|
+
> The instructions below install the stable release on `main`.
|
|
23
|
+
|
|
24
|
+
Full documentation - installation, quickstart, outputs, API reference, etc.:
|
|
25
|
+
[segger-segmentation.readthedocs.io](https://segger-segmentation.readthedocs.io/en/latest/)
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
**segger** requires CUDA 13 and Python 3.13.
|
|
30
|
+
|
|
31
|
+
Clone the repo, then use `conda` or `pixi`:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
git clone https://github.com/dpeerlab/segger.git && cd segger
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
# conda
|
|
39
|
+
conda env create -n segger -f environment.yml
|
|
40
|
+
conda activate segger
|
|
41
|
+
|
|
42
|
+
# pixi
|
|
43
|
+
pixi install
|
|
44
|
+
pixi shell
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Alternatively, install directly from GitHub without cloning:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install --extra-index-url https://pypi.nvidia.com --extra-index-url https://download.pytorch.org/whl/cu130 git+https://github.com/dpeerlab/segger.git
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Usage
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
segger segment \
|
|
57
|
+
-i /path/to/your/ist/data/ \
|
|
58
|
+
-o /path/to/save/outputs/
|
|
59
|
+
|
|
60
|
+
# export different data formats (e.g. boundaries, spatialdata, anndata, xeniumranger, ...)
|
|
61
|
+
segger export boundaries \
|
|
62
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
63
|
+
-o /path/to/export/
|
|
64
|
+
|
|
65
|
+
# export spatialdata. transcripts are added to the existing sdata
|
|
66
|
+
segger export spatialdata \
|
|
67
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
68
|
+
--sdata /path/to/sdata.zarr
|
|
69
|
+
|
|
70
|
+
# for Xenium data to visualise in xenium explorer
|
|
71
|
+
segger export xeniumranger \
|
|
72
|
+
-s /path/to/save/outputs/segger_segmentation.parquet \
|
|
73
|
+
-i /path/to/your/ist/data/ \
|
|
74
|
+
-o /path/to/export/
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
See [notebooks/quickstart.ipynb](notebooks/quickstart.ipynb) for an end-to-end walkthrough.
|
|
78
|
+
|
|
79
|
+
## Contributing
|
|
80
|
+
|
|
81
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
82
|
+
|
|
83
|
+
## Methods description
|
|
84
|
+
|
|
85
|
+
[Heidari, E., Moorman, A., et al. Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data. Methods description (2026).](segger_methods.pdf)
|
|
86
|
+
|
|
87
|
+
## Citation
|
|
88
|
+
|
|
89
|
+
If you use segger in your research, please cite:
|
|
90
|
+
|
|
91
|
+
```bibtex
|
|
92
|
+
@misc{heidari2026segger,
|
|
93
|
+
title={Segger: Fast and accurate cell segmentation of imaging-based spatial transcriptomics data},
|
|
94
|
+
author={Heidari, Elyas and Moorman, Andrew and others},
|
|
95
|
+
note={Methods description},
|
|
96
|
+
year={2026},
|
|
97
|
+
howpublished={\url{https://github.com/dpeerlab/segger/blob/main/segger_methods.pdf}}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "segger"
|
|
3
|
+
version = "1.0.0rc1"
|
|
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"
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import logging
|
|
2
|
+
import os
|
|
3
|
+
import warnings
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
|
|
6
|
+
# torch_geometric uses torch.jit. issue here: https://github.com/pyg-team/pytorch_geometric/issues/10697
|
|
7
|
+
warnings.filterwarnings("ignore", message=".*torch.jit.script.*is deprecated", category=FutureWarning)
|
|
8
|
+
|
|
9
|
+
# ignore lightning's pytree warning: https://github.com/Lightning-AI/pytorch-lightning/issues/21326
|
|
10
|
+
warnings.filterwarnings("ignore", message=".*isinstance\\(treespec, LeafSpec\\).*is deprecated")
|
|
11
|
+
|
|
12
|
+
# ignore batch sampler warning. it returns every tile
|
|
13
|
+
warnings.filterwarnings("ignore", message=".*custom batch sampler `DynamicBatchSamplerPatch` for prediction.*")
|
|
14
|
+
|
|
15
|
+
# the lazily built model has uninitialized parameters, so lightning's parameter count is approximate
|
|
16
|
+
warnings.filterwarnings("ignore", message=".*total number of parameters detected may be inaccurate.*`UninitializedParameter`.*")
|
|
17
|
+
|
|
18
|
+
# small datasets only have a few training batches per epoch
|
|
19
|
+
warnings.filterwarnings("ignore", message=".*number of training batches.*is smaller than the logging interval.*")
|
|
20
|
+
|
|
21
|
+
import cupy as cp
|
|
22
|
+
import torch
|
|
23
|
+
import rmm
|
|
24
|
+
from rmm.allocators.cupy import rmm_cupy_allocator
|
|
25
|
+
from rmm.allocators.torch import rmm_torch_allocator
|
|
26
|
+
from rmm.statistics import enable_statistics, get_statistics
|
|
27
|
+
|
|
28
|
+
logger = logging.getLogger(__name__)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def configure_memory(force: bool = False) -> None:
|
|
32
|
+
"""Point CuPy/cuDF/cuspa and PyTorch at a single shared RMM pool.
|
|
33
|
+
|
|
34
|
+
Must run before any CUDA tensor is created. Run by default from the CLI.
|
|
35
|
+
Importing segger as a library should not change already set allocators.
|
|
36
|
+
|
|
37
|
+
Check if cp allocators are already set to RMM's pool, if not, set them.
|
|
38
|
+
|
|
39
|
+
Note: rmm.is_initialized() is True as soon as `rmm` is imported, thus
|
|
40
|
+
we can't use this to check if memory allocators are already initialised.
|
|
41
|
+
"""
|
|
42
|
+
if not force and os.environ.get("SEGGER_SKIP_ALLOCATOR_INIT") == "1":
|
|
43
|
+
logger.info("Allocators not configured: SEGGER_SKIP_ALLOCATOR_INIT is set.")
|
|
44
|
+
return
|
|
45
|
+
if not force and cp.cuda.get_allocator() is rmm_cupy_allocator:
|
|
46
|
+
logger.info("Allocators not configured: RMM pool already active.")
|
|
47
|
+
return
|
|
48
|
+
# Note: cuspa's CUDA kernels currently reject managed-memory pointers.
|
|
49
|
+
rmm.reinitialize(pool_allocator=True, managed_memory=True)
|
|
50
|
+
cp.cuda.set_allocator(rmm_cupy_allocator)
|
|
51
|
+
torch.cuda.memory.change_current_allocator(rmm_torch_allocator)
|
|
52
|
+
enable_statistics()
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def free_mem_str() -> str:
|
|
56
|
+
stats = get_statistics()
|
|
57
|
+
if stats is None:
|
|
58
|
+
return "GPU: stats not enabled (call segger.configure_memory() first)"
|
|
59
|
+
return (
|
|
60
|
+
f"GPU: {stats.current_bytes / 1e9:.2f} GB "
|
|
61
|
+
f"(peak {stats.peak_bytes / 1e9:.2f} GB)"
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def print_free_mem():
|
|
66
|
+
print(free_mem_str())
|
|
67
|
+
|
|
68
|
+
from .api import segment
|