nextflow_schema.json

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://raw.githubusercontent.com/WEHI-SODA-Hub/sp_segment/master/nextflow_schema.json",
    "title": "WEHI-SODA-Hub/sp_segment pipeline parameters",
    "description": "Cell segmentation and downstream analysis pipeline for the COMET, MIBI, and OPAL spatial platforms",
    "type": "object",
    "$defs": {
        "input_output_options": {
            "title": "Input/output options",
            "type": "object",
            "fa_icon": "fas fa-terminal",
            "description": "Define where the pipeline should find input data and save output data.",
            "required": ["input", "outdir"],
            "properties": {
                "input": {
                    "type": "string",
                    "format": "file-path",
                    "exists": true,
                    "schema": "assets/schema_input.json",
                    "mimetype": "text/csv",
                    "pattern": "^\\S+\\.(csv|y(a)?ml)$",
                    "description": "Path to comma-separated file containing information about the samples in the experiment.",
                    "help_text": "You will need to create a design file with information about the samples in your experiment before running the pipeline. Use this parameter to specify its location. It has to be a comma-separated file with 3 columns, and a header row. See [usage docs](https://github.com/WEHI-SODA-Hub/sp_segment/blob/main/docs/usage.md).",
                    "fa_icon": "fas fa-file-csv"
                },
                "outdir": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.",
                    "fa_icon": "fas fa-folder-open"
                },
                "email": {
                    "type": "string",
                    "description": "Email address for completion summary.",
                    "fa_icon": "fas fa-envelope",
                    "help_text": "Set this parameter to your e-mail address to get a summary e-mail with details of the run sent to you when the workflow exits. If set in your user config file (`~/.nextflow/config`) then you don't need to specify this on the command line for every run.",
                    "pattern": "^([a-zA-Z0-9_\\-\\.]+)@([a-zA-Z0-9_\\-\\.]+)\\.([a-zA-Z]{2,5})$"
                }
            }
        },
        "background_subtract_options": {
            "title": "Background subtraction options",
            "type": "object",
            "fa_icon": "fas fa-adjust",
            "description": "Parameters used for background subtraction.",
            "properties": {
                "remove_markers": {
                    "type": "string",
                    "description": "Comma-separated list of marker channels to remove from the background subtracted image. Note the channel name must match exactly (it is case sensitive).",
                    "fa_icon": "fas fa-eraser"
                }
            }
        },
        "cell_processing_options": {
            "title": "Cell processing options",
            "type": "object",
            "fa_icon": "fas fa-image",
            "description": "Parameters used for cell processing.",
            "properties": {
                "use_whole_cell_only": {
                    "type": "boolean",
                    "description": "Use only the whole-cell segmentation to process cells (skip nuclear segmentation).",
                    "fa_icon": "fas fa-stopwatch",
                    "help_text": "Set this to `true` to use only the whole-cell segmentation to process cells. This will skip segmentation of nuclei and associated measurements but retains cell, erosion, and expansion measurements."
                }
            }
        },
        "combine_channel_options": {
            "title": "Combine options",
            "type": "object",
            "fa_icon": "fas fa-object-group",
            "description": "Parameters used for combining membrane channels.",
            "properties": {
                "combine_method": {
                    "type": "string",
                    "description": "Method used to combine membrane channels (product or max). Using product is not recommended for large numbers of channels with large images as this may use a lot of memory.",
                    "fa_icon": "fas fa-compress-arrows-alt",
                    "enum": ["max", "prod"]
                }
            }
        },
        "sopa_options": {
            "title": "SOPA options",
            "type": "object",
            "fa_icon": "fas fa-microscope",
            "description": "Parameters used by SOPA for image patching.",
            "properties": {
                "technology": {
                    "type": "string",
                    "description": "Technology used for the imaging. Currently, only COMET is supported via the 'ome_tif' parameter.",
                    "fa_icon": "fas fa-microscope",
                    "enum": ["ome_tif"]
                },
                "patch_width_pixel": {
                    "type": "integer",
                    "description": "Width of patches in pixels.",
                    "fa_icon": "fas fa-crop"
                },
                "patch_overlap_pixel": {
                    "type": "integer",
                    "description": "Pixel overlap of patches. This should be set to at least the size of the largest cell in the image to ensure that cells are not split across patches.",
                    "fa_icon": "fas fa-crop"
                }
            }
        },
        "cellpose_options": {
            "title": "Cellpose options",
            "type": "object",
            "fa_icon": "fas fa-vial",
            "description": "Parameters used by Cellpose for the cell segmentation.",
            "properties": {
                "cellpose_diameter": {
                    "type": "integer",
                    "description": "Diameters of your cells in pixels. Cellpose rescales the image so they land at the 30 px it was trained on.",
                    "help_text": "Tells Cellpose the scale of your data. It is passed to sopa as `--diameter` and on to `model.eval`, which turns it into `rescale = 30. / diameter` — 30 being the model's target cell diameter. The image is resized by that factor before the network sees it, and the masks are resized back afterwards, so a cell you say is 60 px across is presented to the network at 30 px.\n\nThe default of 30 therefore asserts your cells are already at the trained scale, which happens to make `rescale` exactly 1.0 and skip the resampling. That is the consequence of the assertion, not the meaning of the number.\n\nCellpose-SAM tolerates a wide range of scales — trained on cell diameters from 7.5 to 120 px, mean 30 — so unlike earlier Cellpose versions this is optional for typical data, and getting it somewhat wrong is not fatal. Two cases where it still matters:\n\n- **Cells well outside 7.5-120 px.** Set the real diameter so they are brought into the range the model handles.\n- **Very large cells you want segmented faster.** Cellpose's own documented example: `--cellpose_diameter 90` downsamples 3x and speeds the run up, at the cost of resolving small objects.\n\nNote it filters nothing — no cell is ever rejected for being the wrong size. Use `--cellpose_min_area` for that.",
                    "fa_icon": "fas fa-circle"
                },
                "cellpose_min_area": {
                    "type": "number",
                    "description": "Discard cells smaller than this many square pixels. Higher keeps fewer cells; 0 keeps every mask.",
                    "help_text": "sopa's filter rather than Cellpose's: `--min-area`, \"Minimum area (in pixels^2) for a cell to be considered as valid\". It is applied per patch as that patch is segmented, before cells straddling neighbouring patches are resolved.\n\nThe units are **pixels², not microns²**, so it does not follow `--pixel_size_microns`. At COMET's 0.28 um/px the default 200 px² is 15.7 um² — roughly a 4.5 um disc. On a different pixel size the same number means a different biological size, so recompute it.\n\nRaise it to drop debris and segmentation fragments; lower it, or set 0, to keep small or partially-imaged nuclei. It cuts on area alone and knows nothing about shape or confidence — a large piece of junk passes and a genuine small nucleus does not.\n\n`--cellsam_min_area` carries the same default and the same meaning, so switching segmenter does not silently change the size floor. Mesmer's `--mesmer_min_nuclei_area` is a separate setting on nuclei rather than cells and is not aligned with these.",
                    "fa_icon": "fas fa-arrows-alt"
                },
                "cellpose_flow_threshold": {
                    "type": "number",
                    "description": "Maximum flow error allowed for a mask to be kept. Higher finds more cells, including ill-shaped ones; lower keeps fewer, better-formed ones.",
                    "fa_icon": "fas fa-tachometer-alt",
                    "help_text": "Cellpose's shape check, and the reason it exists: nothing stops the network predicting flows that correspond to no real shape, which it occasionally does where it is uncertain. So having formed the masks, Cellpose recomputes the flow gradients each one implies and takes the mean squared error against the flows the network actually predicted. Masks whose error exceeds this threshold are discarded.\n\nIt therefore rejects on *shape* — a mask has to look like something Cellpose's own flows would produce — and never on how confident the network was. That is `--cellpose_cellprob_threshold`.\n\n- Missing cells you can see in the image? **Raise** it (0.6, 0.8). More masks survive, some of them ragged.\n- Getting too many ill-shaped blobs? **Lower** it (0.2, 0.3). Fewer masks, better formed.\n- `0` turns the check off completely and keeps everything: Cellpose guards the step with `if flow_threshold > 0`.\n\nThe default 0.4 is Cellpose's own. Applies in 2D only — Cellpose skips this step for 3D data."
                },
                "cellpose_cellprob_threshold": {
                    "type": "number",
                    "description": "Cutoff on Cellpose's per-pixel cell probability. Lower finds more and larger cells; higher finds fewer and smaller ones.",
                    "fa_icon": "fas fa-check-circle",
                    "help_text": "The cutoff on the third of Cellpose's three network outputs — flows in X, flows in Y, and cell probability. Pixels above the cutoff are the ones fed into the dynamics step that forms ROIs, so this decides which pixels are eligible to be cell at all.\n\n**It is not a 0-1 probability.** The values are the inputs to a sigmoid centred at zero, so they run from roughly **-6 to +6**, and 0 is the midpoint, not the floor. Both directions are meaningful and the useful range is wide.\n\nUnlike `--cellpose_flow_threshold`, which only decides whether a finished mask survives, this moves **where each cell's boundary falls**. It therefore shifts cell areas, and every per-cell intensity measured over those masks moves with them. Treat a change here as a change to your measurements, not just to your cell count.\n\n- Missing faint or dim cells? **Lower** it (-1, -2). More cells are found, and the ones you already had grow.\n- Segmenting background or dim debris as cells? **Raise** it (1, 2). Fewer cells, and they shrink.\n\nThe default 0.0 is Cellpose's own."
                },
                "cellpose_model_type": {
                    "type": "string",
                    "description": "Retired. Cellpose 4 ignores --model-type; use cellpose_pretrained_model instead.",
                    "help_text": "Cellpose >=4.0.1 logs `model_type argument is not used in v4.0.1+. Ignoring this argument`, and sopa only reads it on the cellpose<4 code path, so it never had any effect on a v4 run. Setting it now raises an error rather than being silently discarded.",
                    "hidden": true,
                    "fa_icon": "fas fa-cogs"
                },
                "cellpose_pretrained_model": {
                    "type": "string",
                    "description": "Cellpose model to segment with: cpsam_v2 (default), cpsam, cpdino, cpdino-vitb, or a path to a custom model.",
                    "help_text": "Selects the Cellpose model. Accepts either a built-in model name or a filesystem path to your own trained model.\n\nBuilt-in models (cellpose 4.2.1.1):\n\n- `cpsam_v2` \u2014 default; the current Cellpose-SAM model.\n- `cpsam` \u2014 the previous Cellpose-SAM model. Use this to reproduce results from before this pipeline moved to cellpose 4.2.\n- `cpdino` \u2014 DINOv3-backbone model added in cellpose 4.2 (ViT-L, ~303M parameters).\n- `cpdino-vitb` \u2014 smaller ViT-B DINOv3 variant.\n\nThe DINO models need Meta's `dinov3` package, which the pinned container carries. Only its architecture code is used \u2014 Cellpose builds the backbone with `pretrained=False` and loads its own weights \u2014 so Meta's gated backbone weights are not required. Note the DINOv3 licence terms in CITATIONS.md if you redistribute the container or publish results using these models.\n\nA path is passed through untouched, so a custom model is loaded directly and no download occurs. Built-in names are fetched once per run by CELLPOSEMODEL, or read from --cellpose_models_dir if you have a pre-staged copy.",
                    "fa_icon": "fas fa-file-upload"
                },
                "cellpose_models_dir": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "Directory holding pre-staged Cellpose model weights. If set, the pipeline uses it instead of downloading them.",
                    "help_text": "Point this at a shared copy of the Cellpose model cache (the directory holding e.g. `cpsam`) to skip the download entirely. Recommended on clusters where compute nodes have no outbound network access.",
                    "fa_icon": "fas fa-folder-open"
                }
            }
        },
        "cellpose_preprocessing_options": {
            "title": "Cellpose preprocessing options",
            "type": "object",
            "fa_icon": "fas fa-sliders-h",
            "description": "Intensity preprocessing applied before Cellpose segmentation.",
            "help_text": "The defaults here make the pipeline match Cellpose's own preprocessing contract: rescale to the 1st and 99th percentiles and nothing else.\n\nsopa adds a gaussian filter and CLAHE of its own, neither of which exists in Cellpose, and both are disabled. All of this normalisation is computed per patch, so leaving sopa's stages on makes a cell's segmentation depend on what else landed in its patch and on the value of `--patch_width_pixel`. See the preprocessing section of `docs/usage.md` for the measurements behind these defaults and for how to restore sopa's behaviour.",
            "properties": {
                "cellpose_tile_norm_blocksize": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Block size in pixels for Cellpose's tile-local intensity normalisation. 0 uses Cellpose's whole-patch default.",
                    "help_text": "Segmentation always runs on patches, and normalisation is computed from the patch, so without this a cell's segmentation depends on what else landed in its patch and changing `--patch_width_pixel` changes results. Patch overlap does not help: it resolves cells straddling a boundary, not differing normalisation.\n\nThis is forwarded as `--method-kwargs '{\"normalize\": {\"tile_norm_blocksize\": N, \"percentile\": [1.0, 99.0]}}'`, which sopa passes into `model.eval`, making the percentile statistics local to each block rather than global to the patch.\n\nChoose a block that comfortably contains many nuclei. At COMET's 0.28 um/px with `--cellpose_diameter 30` (8.4 um cells), 512 px is 143 um, about 17 nuclear diameters. Small blocks are actively harmful: a 128 px (36 um) block spans roughly 4 cell diameters, so in sparse tissue it can contain no nuclei at all and its noise is stretched to the full range. Cellpose only guards a flat block when its 1-99 percentile range falls below 1e-3, which such blocks exceed.\n\nNote this does not normalise across the whole image -- nothing in the patch-parallel design ever sees it.",
                    "fa_icon": "fas fa-th"
                },
                "cellpose_clip_limit": {
                    "type": "number",
                    "minimum": 0,
                    "description": "sopa's CLAHE clip limit, applied before Cellpose. Defaults to 0 in this pipeline, disabling CLAHE; null restores sopa's default of 0.2.",
                    "help_text": "sopa runs `skimage.exposure.equalize_adapthist` on each patch before Cellpose sees it. This is sopa's addition, not part of Cellpose -- Cellpose contains no CLAHE code, and its released weights were trained on percentile-normalised input, so this preprocessing is off that contract.\n\nSetting 0 disables CLAHE. Worth testing: CLAHE is the largest single source of patch-dependence in this stack, and on an all-zero patch it expands the image to the full range, which defeats Cellpose's own empty-patch guard.",
                    "fa_icon": "fas fa-adjust"
                },
                "cellpose_clahe_kernel_size": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Kernel size in pixels for sopa's CLAHE. Unset uses skimage's default of patch.shape // 8, which scales with patch_width_pixel.",
                    "help_text": "Left unset, skimage derives the kernel from the patch: 1/8 of its height and width. The contrast-enhancement length scale therefore moves with `--patch_width_pixel` -- 187 px (52 um) at 1500, 375 px (105 um) at 3000, 750 px (210 um) at 6000 -- so the same tissue is enhanced differently purely because of a patching knob.\n\nPinning an absolute value removes that coupling. cellSAM, which also CLAHEs each block, fixes its kernel at 128 px rather than deriving it from the block size.\n\nHas no effect while `--cellpose_clip_limit` is 0.",
                    "fa_icon": "fas fa-ruler-combined"
                },
                "cellpose_gaussian_sigma": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Sigma for sopa's gaussian smoothing, applied before Cellpose. Defaults to 0 in this pipeline, disabling it; null restores sopa's default of 1.",
                    "help_text": "Like CLAHE, this is sopa's addition rather than Cellpose's: Cellpose's own smoothing and sharpening parameters (`smooth_radius`, `sharpen_radius`) both default to 0, and it applies neither unless asked.\n\nUnlike CLAHE this is not a source of patch dependence, since a small-sigma convolution is local and only edge reflection differs between patch layouts. Disabling it is therefore about matching Cellpose's preprocessing contract, not about stability. Raise it if your data is noisy enough to need denoising before segmentation.",
                    "fa_icon": "fas fa-water"
                }
            }
        },
        "mesmer_options": {
            "title": "Mesmer options",
            "type": "object",
            "fa_icon": "fas fa-vial",
            "description": "Parameters used by the MesmerSegmentation tool.",
            "properties": {
                "mesmer_segmentation_level": {
                    "type": "integer",
                    "description": "Segmentation level (legacy parameter).",
                    "fa_icon": "fas fa-layer-group",
                    "minimum": 0,
                    "maximum": 10
                },
                "mesmer_maxima_threshold": {
                    "type": "number",
                    "description": "Controls segmentation level directly in mesmer, (lower values = more cells, higher values = fewer cells). ",
                    "fa_icon": "fas fa-tachometer-alt",
                    "minimum": 0
                },
                "mesmer_interior_threshold": {
                    "type": "number",
                    "description": "Controls how conservative model is in distinguishing cell from background (higher values = more conservative interior therefore smaller nuclei & cells).",
                    "fa_icon": "fas fa-tachometer-alt"
                },
                "mesmer_maxima_smooth": {
                    "type": "number",
                    "description": "Smooths signal peaks (higher values = less irregular shapes/nuclei).",
                    "fa_icon": "fas fa-tachometer-alt",
                    "minimum": 0
                },
                "mesmer_min_nuclei_area": {
                    "type": "number",
                    "description": "Minimum area of nuclei to keep in square pixels.",
                    "fa_icon": "fas fa-arrows-alt",
                    "minimum": 0
                },
                "mesmer_remove_border_cells": {
                    "type": "boolean",
                    "description": "Remove cells that touch the image border.",
                    "fa_icon": "fas fa-border-all"
                },
                "mesmer_pixel_expansion": {
                    "type": "integer",
                    "description": "Manual pixel expansion after segmentation.",
                    "fa_icon": "fas fa-expand-arrows-alt",
                    "minimum": 0
                },
                "mesmer_padding": {
                    "type": "integer",
                    "description": "Number of pixels to crop the image by on each side before segmentation.",
                    "fa_icon": "fas fa-crop",
                    "minimum": 0
                },
                "mesmer_transpose_mask": {
                    "type": "boolean",
                    "description": "Force-transpose the Mesmer output mask. Enable this if the segmentation result appears spatially flipped relative to the input image.",
                    "fa_icon": "fas fa-exchange-alt"
                }
            }
        },
        "cellsam_options": {
            "title": "CellSAM options",
            "type": "object",
            "fa_icon": "fas fa-brain",
            "description": "Parameters used by CellSAM for foundation model cell segmentation.",
            "properties": {
                "cellsam_bbox_threshold": {
                    "type": "number",
                    "default": 0.4,
                    "description": "Confidence threshold for cell detection. Lower values (0.3-0.4) increase recall for out-of-distribution images.",
                    "fa_icon": "fas fa-tachometer-alt",
                    "minimum": 0.0,
                    "maximum": 1.0
                },
                "cellsam_block_size": {
                    "type": "integer",
                    "default": 600,
                    "description": "Tile size for large image processing. Recommended: 256-512 for dense images, 400-600 for sparse.",
                    "fa_icon": "fas fa-th",
                    "minimum": 128,
                    "maximum": 2048
                },
                "cellsam_overlap": {
                    "type": "integer",
                    "default": 250,
                    "description": "Tile overlap region in pixels. Should encompass typical cell size for proper merging.",
                    "fa_icon": "fas fa-compress-arrows-alt",
                    "minimum": 0,
                    "maximum": 256
                },
                "cellsam_iou_depth": {
                    "type": "integer",
                    "default": 250,
                    "description": "Depth for IOU-based label merging across tiles. 250 works well for COMET images.",
                    "fa_icon": "fas fa-layer-group",
                    "minimum": 0,
                    "maximum": 256
                },
                "cellsam_iou_threshold": {
                    "type": "number",
                    "default": 0.5,
                    "description": "IOU threshold for merging overlapping labels across tiles.",
                    "fa_icon": "fas fa-project-diagram",
                    "minimum": 0.0,
                    "maximum": 1.0
                },
                "cellsam_use_wsi": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enable tiling for large images. Recommended for images with >3000 cells.",
                    "fa_icon": "fas fa-th-large"
                },
                "cellsam_gauge_cell_size": {
                    "type": "boolean",
                    "description": "Perform preliminary segmentation to estimate cell sizes.",
                    "fa_icon": "fas fa-ruler-combined"
                },
                "cellsam_low_contrast_enhancement": {
                    "type": "boolean",
                    "description": "Apply contrast enhancement preprocessing for low-contrast images.",
                    "fa_icon": "fas fa-adjust"
                },
                "cellsam_model_path": {
                    "type": "string",
                    "description": "Path to custom CellSAM model weights. If not specified, uses latest generalist model (v1.2 with DEEPCELL_ACCESS_TOKEN).",
                    "fa_icon": "fas fa-file-medical",
                    "format": "file-path"
                },
                "cellsam_min_area": {
                    "type": "integer",
                    "default": 200,
                    "description": "Discard cells smaller than this many square pixels. Higher keeps fewer cells; 0 disables the filter. Matches cellpose_min_area.",
                    "help_text": "The same size floor `--cellpose_min_area` applies on the Cellpose path, so a run is not filtered differently just because of which segmenter produced it. Both are in **pixels², not microns²**, and both keep cells whose area is greater than or equal to the threshold.\n\nThe two measure that area slightly differently and are not exactly interchangeable: CellSAM counts the label's pixels, while sopa measures the vectorised polygon after smoothing. Across round and ragged cells the polygon comes out at 0.93-1.00x the pixel count (median 0.99), so 200 here cuts at an equivalent ~202 px on the Cellpose side.\n\nCellSAM applies it once, after the whole-slide tiles have been merged; Cellpose applies it per patch during segmentation. Set 0 to keep every mask, which is what this defaulted to before -- CellSAM ran with no size floor at all while Cellpose had one.",
                    "fa_icon": "fas fa-compress-arrows-alt"
                }
            }
        },
        "kronos_options": {
            "title": "KRONOS2 embedding options",
            "type": "object",
            "fa_icon": "fas fa-dna",
            "description": "Options for KRONOS2 per-cell foundation-model embeddings",
            "help_text": "KRONOS is a foundation model for multiplex spatial proteomic images. These parameters control the embedding extraction step that runs after cell measurement.",
            "properties": {
                "enable_kronos": {
                    "type": "boolean",
                    "description": "Enable KRONOS2 per-cell embedding extraction.",
                    "fa_icon": "fas fa-stopwatch",
                    "help_text": "Set this to `true` to run KRONOS embedding extraction after cell measurement. Requires kronos_model_path and kronos_marker_metadata to be set."
                },
                "kronos_model_path": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "Path to a KRONOS2 snapshot directory (or a Hugging Face repo id). The full snapshot is required - the loader imports the bundled dinov2 package - so a hand-picked subset of files will not work.",
                    "fa_icon": "fas fa-file-medical",
                    "help_text": "The directory should contain the model checkpoint (e.g. kronos_vits16_model.pt) and optionally a config.json file. Download from https://github.com/mahmoodlab/KRONOS or Hugging Face Hub (MahmoodLab/kronos)."
                },
                "kronos_patch_size": {
                    "type": "integer",
                    "default": 64,
                    "description": "Size of cell-centered patches to extract for KRONOS inference.",
                    "fa_icon": "fas fa-crop",
                    "minimum": 16,
                    "maximum": 256,
                    "help_text": "The patch size in pixels for cell-centered crops. Larger patches capture more context but increase computation. Typical values are 32-128."
                },
                "kronos_batch_size": {
                    "type": "integer",
                    "default": 16,
                    "description": "Batch size for inference. KRONOS2 runs fp32 and cuBLAS picks batch-dependent kernels, so this shifts embeddings slightly; 16 reproduces the published values.",
                    "fa_icon": "fas fa-layer-group",
                    "minimum": 1,
                    "maximum": 512,
                    "help_text": "Number of cell patches to process simultaneously. Larger batch sizes are faster but require more GPU memory."
                },
                "kronos_num_workers": {
                    "type": "integer",
                    "default": 4,
                    "description": "Number of parallel DataLoader workers for loading and preprocessing cell patches.",
                    "fa_icon": "fas fa-cogs",
                    "minimum": 0,
                    "maximum": 32,
                    "help_text": "Controls how many CPU processes load and preprocess patches in parallel while the GPU runs inference. Set to 0 for single-process loading (useful for debugging). On HPC, set this to match the number of CPUs allocated to the KRONOS job for best throughput."
                },
                "kronos_max_value": {
                    "type": "number",
                    "description": "Override the intensity divisor. Unset derives it from the image dtype (uint8=255, uint16=65535, float=400), matching KRONOS2 itself.",
                    "fa_icon": "fas fa-sliders-h"
                },
                "kronos_marker_mapping": {
                    "type": "string",
                    "description": "JSON file or inline JSON mapping this panel's channel names onto KRONOS2 vocabulary names, e.g. {\"Collagen 4\": \"COLLAGENiv\"}. KRONOS2 matches names exactly (separator-insensitive) with no alias or fuzzy step, so naming variants otherwise fall back to default normalisation stats.",
                    "fa_icon": "fas fa-exchange-alt",
                    "help_text": "Provide a JSON string like '{\"CD3e\": \"CD3E\", \"PanCK\": \"PANCK\"}' to manually resolve marker name mismatches between your image channels and the KRONOS metadata. KRONOS performs case-insensitive matching automatically, so only provide mappings for markers that truly differ in name."
                },
                "kronos_exclude_markers": {
                    "type": "string",
                    "description": "Comma-separated list of channels not to show KRONOS2, so they contribute nothing to the embedding, e.g. 'Autofluorescence'. Case sensitive, and matched against the image's own channel names before any marker mapping is applied.",
                    "fa_icon": "fas fa-eye-slash",
                    "help_text": "Scoped to the embedding step alone: the channel is simply never read, so it stays in the image, remains available to every other process, and keeps any intensity measurements CELLMEASUREMENT wrote for it. Nothing is deleted. Use it for channels that are not markers at all -- autofluorescence, blanks, empty cycles -- where no mapping can help. Contrast `kronos_allow_novel_defaults`, which still feeds an out-of-vocabulary channel to the model, normalised with default statistics. A name matching no channel fails the run and lists the channels that are present, and the nuclear channel cannot be skipped because it is the model's `preferred_dapi`. KRONOS2 attends across the whole channel set, so changing this list changes every cell's embedding -- hold it constant across a cohort."
                },
                "kronos_nuclear_marker": {
                    "type": "string",
                    "description": "Channel to treat as the nuclear stain. This is the model's only marker-alias mechanism, so a DRAQ5/Hoechst slide needs it to receive DAPI stats. Defaults to the samplesheet nuclear_channel.",
                    "fa_icon": "fas fa-circle"
                },
                "kronos_isolate_cell": {
                    "type": "boolean",
                    "default": true,
                    "description": "Zero pixels outside the target cell so each embedding describes that cell rather than its surrounding neighbourhood.",
                    "fa_icon": "fas fa-crop"
                },
                "kronos_allow_novel_defaults": {
                    "type": "boolean",
                    "default": false,
                    "description": "Proceed when markers fall outside KRONOS2's vocabulary (they take default normalisation stats). Off by default so this fails loudly.",
                    "fa_icon": "fas fa-exclamation-triangle"
                }
            }
        },
        "measurement_options": {
            "title": "Cell measurement options",
            "type": "object",
            "fa_icon": "fas fa-image",
            "description": "Parameters used for cell measurement.",
            "help_text": "These parameters controls parameters used by the cellmeasurement step of the pipeline.",
            "properties": {
                "enable_measurements": {
                    "type": "boolean",
                    "default": true,
                    "description": "Enable cell measurement step.",
                    "fa_icon": "fas fa-stopwatch",
                    "help_text": "Set this to `false` to skip the cell measurement step of the pipeline. Nuclei and whole-cells will still be merged but compartment metrics will not be calculated (this can save processing time)."
                },
                "percentiles": {
                    "type": "string",
                    "default": "70,80,90,95,99",
                    "description": "Comma-separated list of percentiles to calculate for each marker (e.g. 80,90,95,99).",
                    "fa_icon": "fas fa-percentage",
                    "pattern": "^(100|[1-9]?[0-9][\\.]?[0-9]*)(,(100|[1-9]?[0-9][\\.]?[0-9]*))*$",
                    "help_text": "A comma-separated list of percentiles to calculate for each marker. Each value must be between 0 and 100. Default: 70,80,90,95,99. Skip measurements must be set to `false` to use this parameter."
                },
                "erosion_steps": {
                    "type": "boolean",
                    "default": true,
                    "description": "Measure intensity in 5 equal-area erosion bins working inward from the cell/nucleus boundary.",
                    "fa_icon": "fas fa-ruler-combined",
                    "help_text": "Divides each cell and nucleus mask into 5 concentric zones of approximately equal area by iterative morphological erosion, then measures mean/median intensity per zone. Adapts automatically to cell size. Set to false to disable. Skip measurements must be set to false to use this parameter."
                },
                "expansion_steps": {
                    "type": "boolean",
                    "default": true,
                    "description": "Measure intensity in 5 equal-area annular bins dilated 20 \u00b5m outward from the cell boundary (distance computed from pixel_size_microns).",
                    "fa_icon": "fas fa-expand-arrows-alt",
                    "help_text": "Divides the 20 \u00b5m pericellular zone into 5 rings of approximately equal area and measures mean/median intensity per ring. The total expansion distance is computed automatically from pixel_size_microns. Set to false to disable. Skip measurements must be set to false to use this parameter."
                },
                "environment_expansion": {
                    "type": "boolean",
                    "default": true,
                    "description": "Measure a 20 \u00b5m pericellular 'Environment' compartment (distance computed automatically from pixel_size_microns).",
                    "fa_icon": "fas fa-circle-notch",
                    "help_text": "Dilates the cell mask by 20 \u00b5m (converted to pixels via pixel_size_microns) and measures mean, median, min, max, and std dev of every channel in the full zone (cell boundary to outer ring) as one region. This matches CellTune's 'Environment' compartment. Set to false to disable."
                },
                "pixel_size_microns": {
                    "type": "number",
                    "description": "Pixel size in microns.",
                    "minimum": 0.1,
                    "maximum": 10.0,
                    "fa_icon": "fas fa-ruler-combined",
                    "help_text": "COMET: 0.28 \u00b5m/px, MIBI: 0.390625 \u00b5m/px, OPAL: 0.4964 \u00b5m/px."
                },
                "estimate_cell_boundary_dist": {
                    "type": "integer",
                    "description": "Where no matching membrane ROI exists, expand the nucleus by this many pixels (default = 3.0).",
                    "fa_icon": "fas fa-expand-arrows-alt",
                    "minimum": 0
                },
                "neighbors": {
                    "type": "integer",
                    "default": 0,
                    "minimum": 0,
                    "description": "Number of nearest neighbors for neighborhood feature aggregation (0 = disabled).",
                    "fa_icon": "fas fa-project-diagram",
                    "help_text": "For each cell, the max and mean of every numeric measurement are computed across its k closest spatial neighbours (by centroid distance). This produces features like 'Neighbors: Max: CD3: Cell: Mean' and 'Neighbors: Mean: CD3: Cell: Mean'. Set to 0 to disable. Typical values: 5\u201310."
                },
                "gzip_geojson": {
                    "type": "boolean",
                    "default": true,
                    "hidden": true,
                    "description": "Gzip-compress the output GeoJSON files. Produces .geojson.gz instead of .geojson.",
                    "fa_icon": "fas fa-file-archive",
                    "help_text": "Enable this to gzip-compress the GeoJSON output from cellmeasurement. For large images with hundreds of thousands of cells, the GeoJSON can be 100+ GB uncompressed. Gzip typically achieves 10-20x compression on JSON with floating-point coordinates. The compressed files can be used directly with the import_large_geojson pipeline."
                },
                "dist_threshold": {
                    "type": "number",
                    "default": 10.0,
                    "description": "Maximum centroid distance in pixels for matching a nucleus to a whole-cell ROI.",
                    "fa_icon": "fas fa-ruler",
                    "help_text": "Nuclear and whole-cell centroids further apart than this threshold are not matched. Unmatched nuclei receive synthetic cell boundaries via watershed. Lower values enforce stricter matching; higher values tolerate more offset between segmentation models."
                },
                "downsample_factor": {
                    "type": "number",
                    "default": 1.0,
                    "description": "Downsample factor applied to the image and masks before measurement (1 = no downsampling).",
                    "fa_icon": "fas fa-compress-arrows-alt",
                    "help_text": "Integer downsample factor >= 2 to speed up measurement on very large images. The image is block-averaged; masks use block-max to preserve labels. Values < 2 are treated as 1 (no downsampling). Note that physical measurements (area, length) are scaled back to original pixel units."
                },
                "tile_size": {
                    "type": "integer",
                    "default": 2048,
                    "description": "Tile size for large image measurement calculations.",
                    "fa_icon": "fas fa-th",
                    "minimum": 128,
                    "help_text": "The tile size in pixels for cell measurement. Smaller tiles allow parallel processing but create some overhead. Aim for 2-4x more tiles than the thread count."
                },
                "tile_overlap": {
                    "type": "integer",
                    "default": 200,
                    "description": "Tile overlap region in pixels. Should encompass typical cell size.",
                    "fa_icon": "fas fa-compress-arrows-alt",
                    "minimum": 0,
                    "help_text": "The overlap between tiles. This should be set to at least the size of the largest cell in the image to ensure that measurements from cells are complete."
                },
                "geometry_checkpoint_dir": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "Directory for resumable polygon-extraction checkpoints.",
                    "fa_icon": "fas fa-save",
                    "help_text": "Polygon extraction writes each completed batch of cells to this directory, so a CELLMEASUREMENT task killed by wall-time or OOM resumes from the last completed batch instead of restarting. Must point OUTSIDE the Nextflow work directory: a retry runs in a fresh work directory, so a checkpoint written there would be discarded. Leave unset to disable checkpointing."
                },
                "geometry_batch_size": {
                    "type": "integer",
                    "default": 2000,
                    "description": "Cells per polygon-extraction batch, and the checkpoint granularity.",
                    "fa_icon": "fas fa-layer-group",
                    "minimum": 1,
                    "help_text": "Smaller batches checkpoint more often but add per-batch overhead. At most one batch of work per worker is lost when a job is killed."
                }
            }
        },
        "report_options": {
            "title": "Report options",
            "type": "object",
            "fa_icon": "fas fa-image",
            "description": "Parameters used for segmentation report generation.",
            "help_text": "These parameters controls parameters used by the segmentationreport step of the pipeline.",
            "properties": {
                "generate_report": {
                    "type": "boolean",
                    "description": "Generate segmentation report.",
                    "fa_icon": "fas fa-stopwatch",
                    "help_text": "Set this to `true` to generate a segmentation report. It is recommended that enable_measurements is set to `true` for the most comprehensive report. Skipping this step can save on processing time."
                }
            }
        },
        "mask_smoothing_options": {
            "title": "Mask smoothing options",
            "type": "object",
            "fa_icon": "fas fa-magic",
            "description": "Parameters for optional mask smoothing before cell measurement.",
            "help_text": "Enable mask smoothing to reduce polygon complexity in segmentation masks. This can prevent StackOverflowError in QuPath's GeoJSON export when cell ROIs have overly complex/jagged boundaries.",
            "properties": {
                "smooth_masks": {
                    "type": "boolean",
                    "description": "Enable mask smoothing before cell measurement.",
                    "fa_icon": "fas fa-wave-square",
                    "help_text": "When enabled, segmentation masks are smoothed to reduce polygon complexity before being passed to cellmeasurement. Choose the method with smooth_method."
                },
                "smooth_method": {
                    "type": "string",
                    "default": "morphological",
                    "description": "Smoothing algorithm: 'morphological' (disk close+open) or 'shapely' (Douglas-Peucker polygon simplification).",
                    "fa_icon": "fas fa-cogs",
                    "enum": ["morphological", "shapely"],
                    "help_text": "'morphological' applies binary close then open with a disk kernel to smooth pixel boundaries. 'shapely' extracts the polygon boundary for each label and applies Shapely's simplify (Douglas-Peucker) algorithm, which directly reduces vertex count \u2014 the main cause of StackOverflowError in QuPath GeoJSON export."
                },
                "smooth_kernel_size": {
                    "type": "integer",
                    "default": 2,
                    "minimum": 1,
                    "maximum": 10,
                    "description": "Disk radius for morphological close+open smoothing (pixels).",
                    "fa_icon": "fas fa-circle",
                    "help_text": "Larger values produce smoother boundaries but may merge nearby cells. Only used when smooth_masks is enabled."
                },
                "smooth_n_workers": {
                    "type": "integer",
                    "default": 8,
                    "minimum": 1,
                    "maximum": 64,
                    "description": "Number of parallel worker processes for smoothing.",
                    "fa_icon": "fas fa-tasks",
                    "help_text": "Set to match available CPUs for optimal performance. Should match --cpus-per-task in your resource configuration"
                },
                "smooth_chunksize": {
                    "type": "integer",
                    "default": 200,
                    "minimum": 1,
                    "maximum": 10000,
                    "description": "Number of labels per worker chunk.",
                    "fa_icon": "fas fa-layer-group",
                    "help_text": "Tune based on cell size distribution. Larger values for many small cells, smaller values for fewer large cells."
                },
                "smooth_tolerance": {
                    "type": "number",
                    "default": 1,
                    "minimum": 0.01,
                    "description": "[shapely] Douglas-Peucker simplification tolerance in pixels.",
                    "fa_icon": "fas fa-sliders-h",
                    "help_text": "Controls how aggressively polygon boundaries are simplified when smooth_method is 'shapely'. Higher values produce simpler (fewer vertex) polygons but less accurate boundaries. Important to minimise vertex count to prevent StackOverflowError in QuPath GeoJSON export. Tune based on typical cell size and boundary complexity. Start with threshold 1 and adjust as needed."
                },
                "smooth_min_area": {
                    "type": "number",
                    "default": 0,
                    "minimum": 0,
                    "description": "[shapely] Minimum polygon area in pixels\u00b2 to retain after simplification.",
                    "fa_icon": "fas fa-compress-arrows-alt",
                    "help_text": "Labels whose simplified polygon area falls below this threshold are removed from the output mask. Useful for discarding fragments created by aggressive simplification. Only used when smooth_method is 'shapely'."
                }
            }
        },
        "institutional_config_options": {
            "title": "Institutional config options",
            "type": "object",
            "fa_icon": "fas fa-university",
            "description": "Parameters used to describe centralised config profiles. These should not be edited.",
            "help_text": "The centralised nf-core configuration profiles use a handful of pipeline parameters to describe themselves. This information is then printed to the Nextflow log when you run a pipeline. You should not need to change these values when you run a pipeline.",
            "properties": {
                "custom_config_version": {
                    "type": "string",
                    "description": "Git commit id for Institutional configs.",
                    "default": "master",
                    "hidden": true,
                    "fa_icon": "fas fa-users-cog"
                },
                "custom_config_base": {
                    "type": "string",
                    "description": "Base directory for Institutional configs.",
                    "default": "https://raw.githubusercontent.com/nf-core/configs/master",
                    "hidden": true,
                    "help_text": "If you're running offline, Nextflow will not be able to fetch the institutional config files from the internet. If you don't need them, then this is not a problem. If you do need them, you should download the files from the repo and tell Nextflow where to find them with this parameter.",
                    "fa_icon": "fas fa-users-cog"
                },
                "config_profile_name": {
                    "type": "string",
                    "description": "Institutional config name.",
                    "hidden": true,
                    "fa_icon": "fas fa-users-cog"
                },
                "config_profile_description": {
                    "type": "string",
                    "description": "Institutional config description.",
                    "hidden": true,
                    "fa_icon": "fas fa-users-cog"
                },
                "config_profile_contact": {
                    "type": "string",
                    "description": "Institutional config contact information.",
                    "hidden": true,
                    "fa_icon": "fas fa-users-cog"
                },
                "config_profile_url": {
                    "type": "string",
                    "description": "Institutional config URL link.",
                    "hidden": true,
                    "fa_icon": "fas fa-users-cog"
                }
            }
        },
        "generic_options": {
            "title": "Generic options",
            "type": "object",
            "fa_icon": "fas fa-file-import",
            "description": "Less common options for the pipeline, typically set in a config file.",
            "help_text": "These options are common to all nf-core pipelines and allow you to customise some of the core preferences for how the pipeline runs.\n\nTypically these options would be set in a Nextflow config file loaded for all pipeline runs, such as `~/.nextflow/config`.",
            "properties": {
                "version": {
                    "type": "boolean",
                    "description": "Display version and exit.",
                    "fa_icon": "fas fa-question-circle",
                    "hidden": true
                },
                "publish_dir_mode": {
                    "type": "string",
                    "default": "copy",
                    "description": "Method used to save pipeline results to output directory.",
                    "help_text": "The Nextflow `publishDir` option specifies which intermediate files should be saved to the output directory. This option tells the pipeline what method should be used to move these files. See [Nextflow docs](https://www.nextflow.io/docs/latest/process.html#publishdir) for details.",
                    "fa_icon": "fas fa-copy",
                    "enum": ["symlink", "rellink", "link", "copy", "copyNoFollow", "move"],
                    "hidden": true
                },
                "email_on_fail": {
                    "type": "string",
                    "description": "Email address for completion summary, only when pipeline fails.",
                    "fa_icon": "fas fa-exclamation-triangle",
                    "pattern": "^([a-zA-Z0-9_\\-\\.]+)@([a-zA-Z0-9_\\-\\.]+)\\.([a-zA-Z]{2,5})$",
                    "help_text": "An email address to send a summary email to when the pipeline is completed - ONLY sent if the pipeline does not exit successfully.",
                    "hidden": true
                },
                "plaintext_email": {
                    "type": "boolean",
                    "description": "Send plain-text email instead of HTML.",
                    "fa_icon": "fas fa-remove-format",
                    "hidden": true
                },
                "monochrome_logs": {
                    "type": "boolean",
                    "description": "Do not use coloured log outputs.",
                    "fa_icon": "fas fa-palette",
                    "hidden": true
                },
                "hook_url": {
                    "type": "string",
                    "description": "Incoming hook URL for messaging service",
                    "fa_icon": "fas fa-people-group",
                    "help_text": "Incoming hook URL for messaging service. Currently, MS Teams and Slack are supported.",
                    "hidden": true
                },
                "validate_params": {
                    "type": "boolean",
                    "description": "Boolean whether to validate parameters against the schema at runtime",
                    "default": true,
                    "fa_icon": "fas fa-check-square",
                    "hidden": true
                },
                "pipelines_testdata_base_path": {
                    "type": "string",
                    "fa_icon": "far fa-check-circle",
                    "description": "Base URL or local path to location of pipeline test dataset files",
                    "default": "https://raw.githubusercontent.com/nf-core/test-datasets/",
                    "hidden": true
                },
                "deepcell_cache_dir": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "Base directory for caching DeepCell/CellSAM model weights. The current username is appended automatically.",
                    "fa_icon": "fas fa-database",
                    "help_text": "Set this to redirect the DeepCell model cache away from the home directory. The current username is resolved at runtime and appended, so models are cached at {deepcell_cache_dir}/{username}/.deepcell/models/. Set to null to use $HOME instead."
                },
                "container_cache_dir": {
                    "type": "string",
                    "format": "directory-path",
                    "description": "Directory for the Apptainer/Singularity image cache. Set this on any cluster where $HOME has a quota.",
                    "fa_icon": "fas fa-box",
                    "help_text": "Sets apptainer.cacheDir and singularity.cacheDir, so converted .img files are written here rather than under the work directory. This covers only half of a pull: Apptainer unpacks the OCI layers it converts from into $APPTAINER_CACHEDIR (default ~/.apptainer/cache), which Nextflow cannot set because it pulls images from its own process rather than from a task. Export APPTAINER_CACHEDIR and SINGULARITY_CACHEDIR to the same filesystem before launching; the pipeline errors at startup if this parameter is set without them."
                }
            }
        }
    },
    "allOf": [
        {
            "$ref": "#/$defs/input_output_options"
        },
        {
            "$ref": "#/$defs/background_subtract_options"
        },
        {
            "$ref": "#/$defs/combine_channel_options"
        },
        {
            "$ref": "#/$defs/cell_processing_options"
        },
        {
            "$ref": "#/$defs/sopa_options"
        },
        {
            "$ref": "#/$defs/cellpose_options"
        },
        {
            "$ref": "#/$defs/cellpose_preprocessing_options"
        },
        {
            "$ref": "#/$defs/mesmer_options"
        },
        {
            "$ref": "#/$defs/cellsam_options"
        },
        {
            "$ref": "#/$defs/kronos_options"
        },
        {
            "$ref": "#/$defs/measurement_options"
        },
        {
            "$ref": "#/$defs/report_options"
        },
        {
            "$ref": "#/$defs/mask_smoothing_options"
        },
        {
            "$ref": "#/$defs/institutional_config_options"
        },
        {
            "$ref": "#/$defs/generic_options"
        }
    ]
}