diff --git a/docs/howto/segmentation.md b/docs/howto/segmentation.md index 1a68c1e..84bcbf2 100644 --- a/docs/howto/segmentation.md +++ b/docs/howto/segmentation.md @@ -1,38 +1,123 @@ # Segmentation Methods - +SPIMquant provides two built-in segmentation methods for detecting pathology signals in SPIM data, plus support for intensity correction pre-processing. The method and correction are configured independently per stain via the `snakebids.yml` config file. -Learn about different segmentation methods in SPIMquant. +## Overview -## Available Methods +```mermaid +flowchart LR + A[Raw SPIM] --> B[Intensity Correction] + B --> C{seg_method} + C -->|threshold| D[Threshold] + C -->|otsu+k3i2| E[Multi-Otsu + k-means] + D --> F[Binary Mask] + E --> F + F --> G[Clean: remove edge / small objects] + G --> H[Segmentation Output] +``` -### Threshold +After segmentation the binary mask is used to compute [field fraction](../reference/outputs.md#field-fraction-map-seg), [object count](../reference/outputs.md#object-count-map-seg), and [per-object region properties](../reference/outputs.md#region-properties-statistics-table-tabular). -Simple intensity thresholding. +--- - +## Intensity Correction -### Otsu + K-means (otsu+k3i2) +Bias-field correction is applied before segmentation to compensate for the spatially varying illumination typical of lightsheet microscopy. -Otsu thresholding combined with k-means clustering. +### Gaussian (`correction_method: gaussian`) - +A Gaussian blur is applied to the raw image at a coarse downsampled level to estimate the low-frequency illumination profile, which is then divided out. This is fast and requires no extra memory, making it suitable for quick iteration or large datasets. -## Intensity Correction +**Config key:** `correction_method: gaussian` + +### N4 (`correction_method: n4`) + +ANTs N4BiasFieldCorrection is applied. N4 fits a smooth B-spline model of the bias field and is more accurate than Gaussian correction, especially for thicker sections or strong illumination gradients. + +**Config key:** `correction_method: n4` + +!!! tip + Use `n4` when high quantitative accuracy is required. Use `gaussian` for faster exploratory runs or when the illumination gradient is mild. + +--- + +## Segmentation Methods + +### Threshold (`seg_method: threshold`) + +A fixed intensity threshold is applied to the (corrected) image. Voxels above the threshold are classified as positive; all others are negative. + +The threshold value is configured per-stain: + +```yaml +stain_defaults: + abeta: + seg_method: threshold + seg_threshold: 500 # intensity value; adjust to your data +``` + +**When to use:** Works well when the pathology signal is clearly brighter than background and the intensity scale is stable across subjects. Simple to interpret and debug. + +**Limitations:** Sensitive to residual intensity non-uniformities and to between-subject intensity variation. May require manual threshold tuning per dataset. + +### Multi-Otsu (`seg_method: otsu+k3i2`) + +An unsupervised thresholding method that adapts to the intensity distribution of each image. + +The method string encodes two parameters: `k` — the number of Otsu classes, and `i` — the threshold index to use for the binary classification. For `otsu+k3i2`: + +1. **Multi-Otsu thresholding** — Otsu's method is extended to find `k-1` thresholds that minimise within-class variance, splitting the histogram into `k` classes. With `k=3` the image is divided into background, low-signal, and high-signal classes (2 thresholds). +2. **Binary classification** — the threshold at index `i` (1-based) is applied to produce the final binary mask. With `i=2` this selects the second (higher) threshold, classifying only the brightest voxels as positive. + +**Config key:** + +```yaml +stain_defaults: + abeta: + seg_method: otsu+k3i2 +``` + +**When to use:** Preferred when the staining intensity varies across subjects or imaging sessions, because the threshold adapts automatically to each image. Also more robust to residual illumination gradients. + +**Limitations:** Can fail on images with unusual histograms (e.g. very sparse pathology that does not form a distinct peak) or when the background is very noisy. + +--- + +## Post-Segmentation Cleaning + +After the initial binary mask is produced, a cleaning step removes two classes of artefact: + +1. **Edge objects** — connected components that touch the border of the field of view are removed, as these are typically cut-off tissue or slide artefacts rather than true pathology. +2. **Small objects** — objects below a minimum volume threshold (configured via `regionprop_filters`) are discarded, eliminating small noise specks. + +!!! note "Scale convention" + The output mask is stored on a **0–100 scale** (not 0–1). This is deliberate: when the mask is spatially downsampled to compute field fraction, the resulting values are directly interpretable as a percentage (0–100 %). -### Gaussian +--- - +## Per-Stain Configuration -### N4 +Each stain is configured independently. A typical `snakebids.yml` block looks like: - +```yaml +stain_defaults: + abeta: + seg_method: otsu+k3i2 + correction_method: n4 + regionprop_filters: + min_area: 50 # voxels; objects smaller than this are discarded + Iba1: + seg_method: threshold + seg_threshold: 300 + correction_method: gaussian +``` -## Custom Segmentation +Stains not listed in `stain_defaults` fall back to the top-level `seg_method` and `correction_method` keys. - +--- -## Next Steps +## Further Reading -- [Imaris Crops](imaris_crops.md) -- [Examples](../examples/workflows.md) \ No newline at end of file +- [Output Files Reference](../reference/outputs.md) — description of segmentation output files +- [How SPIMquant Works Under the Hood](../workflow_overview.md#stage-7--segmentation) — pipeline context for segmentation +- [Imaris Crops](imaris_crops.md) — export patches for visual inspection \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 4d522ab..ee9e3a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,9 +28,11 @@ SPIMquant supports multiple brain templates for registration: ## Quick Links +- **[How It Works](workflow_overview.md)**: Narrative overview of the full pipeline - **[Installation](getting_started/installation.md)**: Get started with SPIMquant - **[Quick Start](getting_started/quickstart.md)**: Run your first workflow - **[CLI Reference](usage/cli.md)**: Command-line interface documentation +- **[Output Files](reference/outputs.md)**: Description of all output types - **[Examples](examples/workflows.md)**: See SPIMquant in action - **[Contributing](contributing.md)**: Help improve SPIMquant diff --git a/docs/reference/outputs.md b/docs/reference/outputs.md index dbb3892..4c27879 100644 --- a/docs/reference/outputs.md +++ b/docs/reference/outputs.md @@ -1,122 +1,250 @@ # Output Files Reference - - -Reference for SPIMquant output files and formats. +This page describes every output type produced by SPIMquant, what it contains, and where it fits in the processing pipeline. For a narrative explanation of how each output is generated see [How SPIMquant Works Under the Hood](../workflow_overview.md). ## Directory Structure +All outputs follow [BIDS Derivatives](https://bids-specification.readthedocs.io/en/stable/05-derivatives/01-introduction.html) naming conventions and are written into the `output/spimquant/` root by default. + ``` output/spimquant/ -├── sub-01/ -│ ├── micr/ -│ │ ├── *_space-{template}_SPIM.nii.gz -│ │ ├── *_space-{template}_regqc.html -│ │ └── *_mask.nii.gz -│ ├── seg/ -│ │ └── *_SPIM.ome.zarr -│ ├── parc/ -│ │ └── *_from-{template}_dseg.nii.gz -│ ├── tabular/ -│ │ ├── *_segstats.tsv -│ │ ├── *_regionpropstats.tsv -│ │ ├── *_fieldfracstats.tsv -│ │ └── *_countstats.tsv -│ └── xfm/ -│ └── *_xfm.{txt,nii.gz} -└── group/ - ├── *_groupstats.tsv - ├── *_groupstats.png - └── *_groupstats.nii.gz +├── sub-