Configuration Field Reference¶

This page documents all configuration fields that are referenced by the curated user, modality, and pipeline documentation.

Top-Level Fields¶

`dataset_path`¶

Type: string
Required: Yes
Description: Absolute path to the dataset root containing sample directories.

Example:

"dataset_path": "/data/my_tissue_cohort"

`reference_modality`¶

Type: string
Required: Yes
Description: Name of the modality that defines the shared output coordinate system.
Constraint: Must exactly match one modality name.

Example:

"reference_modality": "st"

`perform_alignment`¶

Type: boolean
Required: No
Default: true
Description: Globally enable or disable alignment.

Example:

"perform_alignment": true

`perform_registration`¶

Type: boolean
Required: No
Default: true
Description: Globally enable or disable registration.

Example:

"perform_registration": true

`huggingface_token`¶

Type: string or null
Required: No
Default: null
Description: HuggingFace token used to download Prov-GigaPath for feature_extraction.
Required when: Any modality uses registration_type: "feature_extraction".

Example:

"huggingface_token": "hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

`spatial_annotations`¶

Type: object or null
Required: No
Default: null
Description: Enable spatial annotation transfer from per-sample GeoJSON files.

Structure:

"spatial_annotations": {
  "modality_name": "microscopy",
  "file_type": "geojson"
}

Fields:

modality_name (string): Name of a declared modality whose per-sample directory contains the .geojson files. Exactly one .geojson file must be present per sample.
file_type (string): Currently only "geojson".

Alignment required for non-reference annotation modalities

If modality_name is not the reference modality, perform_alignment must be true. Transferring annotations from a non-reference modality relies on the aligned coordinates (obsm['{modality_name}_spatial']) that the alignment stage produces; validation fails otherwise.

`modalities`¶

Type: array
Required: Yes
Description: List of modality definitions.

Each modality object includes:

name
type
alignment_strategy
registration_type
processing_settings
registration_settings

Per-Modality Fields¶

`name`¶

Type: string
Required: Yes
Description: Unique modality identifier.
Constraint: Must match the modality folder name in every sample.

Example:

"name": "msi"

`type`¶

Type: string
Required: Yes
Allowed values:
"microscopy_image"
"msi"
"raman"
"st"

Example:

"type": "microscopy_image"

`alignment_strategy`¶

Type: string
Required: No
Default: "manual"
Allowed values:
"manual"
"pre_aligned"

Example:

"alignment_strategy": "manual"

`alignment_force_recomputing`¶

Type: boolean
Required: No
Default: false
Description: Re-run alignment for this modality even if cached alignment outputs are already present. Set to true to force re-alignment of this specific reference-target pair without affecting other modalities.

Example:

"alignment_force_recomputing": false

`registration_type`¶

Type: string
Required: No
Default: "none"
Allowed values:
"none" (any modality; skips registration)
"feature_extraction" (microscopy_image only, and only for H&E-stained brightfield RGB images; see Registration Settings)
"spot_interpolation" (msi, st)
"spot_aggregation" (msi, st)
"raman_pixel_interpolation" (raman)
Compatibility is enforced: an incompatible registration_type/modality-type pairing raises a validation error.

Example:

"registration_type": "spot_interpolation"

`processing_settings`¶

Type: object
Required: Yes
Description: Preprocessing parameters specific to the modality type.

`registration_settings`¶

Type: object
Required: No
Default: {}
Description: Registration-method-specific settings.

Processing Settings by Modality¶

`microscopy_image`¶

Field	Type	Default	Step
`color_enhancement`	bool	`true`	Colour enhancement
`gamma`	float	`0.45`	Colour enhancement
`contrast_saturation`	float	`0.35`	Colour enhancement
`remove_background`	bool	`true`	Background removal
`background_color`	string	`"white"`	Background removal
`clip_percentile`	int	`99`	Background removal
`min_object_coverage`	float	`0.01`	Background removal
`crop_to_tissue`	bool	`true`	Cropping
`crop_margin`	int	`250`	Cropping
`force_recomputing`	bool	`false`	All

gamma: exponent of I^gamma on the image normalised to [0, 1]. Below 1.0 it brightens midtones, above 1.0 it darkens them.
contrast_saturation: a percentage. The contrast_saturation and 100 − contrast_saturation percentiles of the non-zero pixels become the clip bounds, which are then rescaled to [0, 1]. Those percentiles are computed once over the whole image, with all channels pooled. The default 0.35 saturates 0.35% of those pixels at each end.
background_color: "white" or "black". Any other value raises ValueError when background removal runs.
clip_percentile: percentile at which the inverted grayscale is clipped before the Gaussian blur that feeds the Otsu threshold.
min_object_coverage: a tissue contour is kept when its area is at least this fraction of the detection-proxy area. The proxy is the image downscaled to at most 9 megapixels.
crop_margin: full-resolution pixels added on each side of the tissue bounding box, clamped to the image bounds.
crop_to_tissue: uses the same tissue mask as background removal, so enabling it alone still runs the full Otsu detection.
force_recomputing: microscopy keeps no intermediate caches. The only cache is the output OME-TIFF itself, which is reused whenever it exists and this flag is false.

The number of OME-TIFF pyramid levels is not a configurable field; it is computed automatically from the final image dimensions. The tissue-detection tuning is not configurable either: the 9-megapixel proxy cap, the 25 px Gaussian blur kernel and the 50 px speck-removal size are internal constants.

Except for background_color, these fields are not checked: an out-of-range value reaches the processing code, where it either raises (a clip_percentile above 100 fails inside numpy.percentile) or changes the result. The out-of-range value is never reported during configuration validation.

Example:

"processing_settings": {
  "color_enhancement": true,
  "gamma": 0.45,
  "contrast_saturation": 0.35,
  "remove_background": true,
  "background_color": "white",
  "clip_percentile": 99,
  "min_object_coverage": 0.01,
  "crop_to_tissue": true,
  "crop_margin": 250,
  "force_recomputing": false
}

`msi`¶

Field	Type	Default
`mass_tolerance`	int	`10`
`frequency_threshold`	float	`0.01`
`intensity_normalization`	string	`"none"`
`min_intensity_threshold`	float	`10000.0`
`detect_background`	bool	`false`
`sample_type`	string	`"tissue"`
`recalibration_reference`	dict or null	`null`
`lipid_annotation_db`	string or null	`null`
`force_recomputing`	bool	`false`

intensity_normalization allowed values: "none", "tic", "log", "clr", "tic_mean_scaled" (all applied per sample and per ion mode). "tic" makes each spectrum sum to 1; "tic_mean_scaled" rescales each spectrum to the mean total ion current over that sample's spots for that ion mode, preserving absolute intensity scale (values are therefore not comparable across samples).
sample_type allowed values: "tissue", "microgrid".
lipid_annotation_db: path to a CSV or JSON file with columns db_name, ionized_mass, ion_mode.
detect_background only takes effect when lipid_annotation_db is also set. Without a database the detection step is skipped and every spot is flagged foreground.
mass_tolerance must be an integer; a float value raises ValueError during processing.
min_intensity_threshold is the minimum peak intensity for a peak to count when estimating m/z recalibration offsets. It does not filter or mask spots.

The example below enables TIC normalization and background detection explicitly; these are not the defaults.

Example:

"processing_settings": {
  "mass_tolerance": 10,
  "frequency_threshold": 0.01,
  "intensity_normalization": "tic",
  "min_intensity_threshold": 10000.0,
  "detect_background": true,
  "sample_type": "tissue",
  "recalibration_reference": null,
  "lipid_annotation_db": null,
  "force_recomputing": false
}

`raman`¶

Field	Type	Default	Step
`savgol_window`	int	`7`	Spectral cleaning
`savgol_polyorder`	int	`3`	Spectral cleaning
`otsu_threshold_factor`	float	`0.7`	Background removal
`bg_min_area_fraction`	float	`0.05`	Background removal
`min_object_size`	int	`500`	Background removal
`max_workers`	int	`8`	BaSiC correction, spectral cleaning
`force_recomputing`	bool	`false`	All

savgol_window / savgol_polyorder: window length in channels and polynomial order of the Savitzky-Golay filter in the RamanSPy cleaning pipeline. SciPy raises ValueError when the order is not smaller than the window, or when the window is longer than a scan's channel block. The other three cleaning stages (Whitaker-Hayes despiking, IASLS baseline, min-max normalisation) use their library defaults and are not configurable.
otsu_threshold_factor: the Otsu threshold computed on the segmentation preview mosaic is multiplied by this value before binarisation. Below 1.0 it lowers the threshold, keeping more pixels as tissue.
bg_min_area_fraction: tissue contours are kept when their area is at least this fraction of the preview mosaic area.
min_object_size: connected components of this many pixels or fewer are removed from the mask (skimage.morphology.remove_small_objects(..., max_size=...), inclusive).
max_workers: number of threads used to correct spectral channels with BaSiC, and number of joblib workers used to clean tile × scan work units.
force_recomputing: also invalidates the per-step .npy caches (basic_corrected_tiles.npy, segmented_tiles.npy, raman_corrected_tiles.npy), which are otherwise reused whenever present.

No step of the Raman pipeline can be switched off from the configuration; these fields only change how each step behaves.

Example:

"processing_settings": {
  "savgol_window": 7,
  "savgol_polyorder": 3,
  "otsu_threshold_factor": 0.7,
  "bg_min_area_fraction": 0.05,
  "min_object_size": 500,
  "max_workers": 8,
  "force_recomputing": false
}

`st`¶

Field	Type	Default
`min_count_per_spot`	int or null	`null`
`max_count_per_spot`	int or null	`null`
`min_genes_per_spot`	int or null	`null`
`max_genes_per_spot`	int or null	`null`
`min_spots_per_gene`	float or null	`null`
`min_count_spots_ratio_per_gene`	float or null	`null`
`remove_mitochondrial_genes`	bool	`false`
`total_counts_normalize`	bool	`false`
`log1p_transform`	bool	`false`
`force_recomputing`	bool	`false`

remove_mitochondrial_genes: when true, drops mitochondrial genes (flagged by a case-insensitive MT-/MT. name prefix) from the feature set. Applied per sample, before merging, and after QC metrics are computed, so pct_counts_mt still describes the matrix before removal.
min_spots_per_gene: minimum fraction of a sample's spots that must express a gene for that sample to count as passing. Must satisfy 0 < value < 1.
min_count_spots_ratio_per_gene: minimum ratio of a gene's total counts to the number of spots expressing it, per sample. Must be > 0. Samples where the gene is unexpressed count as neither pass nor fail.
Both gene filters act on the merged matrix only, and are ignored when null. Each is evaluated per sample, and a gene is retained when it passes in at least one sample; with both set it must satisfy each in at least one sample, not necessarily the same one.
total_counts_normalize / log1p_transform: when either is enabled, the pre-normalisation counts are copied to .layers['raw']. With both off, .X holds the raw counts and no layer is written.

Example:

"processing_settings": {
  "min_count_per_spot": 200,
  "max_count_per_spot": null,
  "min_genes_per_spot": 50,
  "max_genes_per_spot": null,
  "min_spots_per_gene": null,
  "min_count_spots_ratio_per_gene": null,
  "remove_mitochondrial_genes": false,
  "total_counts_normalize": true,
  "log1p_transform": true,
  "force_recomputing": false
}

Registration Settings¶

`feature_extraction`¶

Compatible modality type: microscopy_image, and only when that image is an H&E-stained brightfield RGB section: the encoder (Prov-GigaPath) is pretrained on tiles from H&E whole-slide images. FOCUS does not verify the stain. A fluorescence or other-stain image is encoded without error and yields embeddings that carry no morphological meaning. Use "none" for those modalities. See Registration.

Field	Type	Default
`patch_size`	int	`224`
`background_color`	string	`"white"`
`force_recomputing`	bool	`false`

patch_size: side length in pixels of the patch cut around each anchor spot. Prov-GigaPath expects 224.
background_color: "white" or "black". This is the colour counted by the background test; a patch whose pixels match it in at least 99% of positions is skipped and stored as an all-zero embedding. Set it to the background_color used in the modality's processing_settings.
force_recomputing: recompute even when a valid cached registration exists.

Example:

"registration_settings": {
  "patch_size": 224,
  "background_color": "white",
  "force_recomputing": false
}

`spot_interpolation`¶

Compatible modality types: msi, st.

Field	Type	Default
`force_recomputing`	bool	`false`

Example:

"registration_settings": {
  "force_recomputing": false
}

`spot_aggregation`¶

Compatible modality types: msi, st. Sums the target spots inside each anchor footprint instead of averaging them, with no normalization. Intended for subcellular-resolution data (e.g. Visium HD). See Registration.

Field	Type	Default
`force_recomputing`	bool	`false`

Example:

"registration_settings": {
  "force_recomputing": false
}

`raman_pixel_interpolation`¶

Compatible modality type: raman. Uses the same Gaussian footprint interpolation as spot_interpolation, applied to the pixels of the hyperspectral OME-TIFF. See Registration.

Field	Type	Default
`force_recomputing`	bool	`false`

Example:

"registration_settings": {
  "force_recomputing": false
}

Consistent End-to-End Example¶

{
  "dataset_path": "/data/my_tissue_cohort",
  "reference_modality": "st",
  "perform_alignment": true,
  "perform_registration": true,
  "huggingface_token": "hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "spatial_annotations": {
    "modality_name": "microscopy",
    "file_type": "geojson"
  },
  "modalities": [
    {
      "name": "st",
      "type": "st",
      "alignment_strategy": "manual",
      "registration_type": "none",
      "processing_settings": {
        "min_count_per_spot": 200,
        "max_count_per_spot": null,
        "min_genes_per_spot": 50,
        "max_genes_per_spot": null,
        "min_spots_per_gene": null,
        "min_count_spots_ratio_per_gene": null,
        "total_counts_normalize": true,
        "log1p_transform": true,
        "force_recomputing": false
      },
      "registration_settings": {}
    },
    {
      "name": "msi",
      "type": "msi",
      "alignment_strategy": "manual",
      "alignment_force_recomputing": false,
      "registration_type": "spot_interpolation",
      "processing_settings": {
        "mass_tolerance": 10,
        "frequency_threshold": 0.01,
        "intensity_normalization": "tic",
        "min_intensity_threshold": 10000.0,
        "detect_background": true,
        "sample_type": "tissue",
        "recalibration_reference": null,
        "lipid_annotation_db": "resources/lipid_db.csv",
        "force_recomputing": false
      },
      "registration_settings": {
        "force_recomputing": false
      }
    },
    {
      "name": "raman",
      "type": "raman",
      "alignment_strategy": "manual",
      "alignment_force_recomputing": false,
      "registration_type": "raman_pixel_interpolation",
      "processing_settings": {
        "savgol_window": 7,
        "savgol_polyorder": 3,
        "otsu_threshold_factor": 0.7,
        "bg_min_area_fraction": 0.05,
        "min_object_size": 500,
        "max_workers": 8,
        "force_recomputing": false
      },
      "registration_settings": {
        "force_recomputing": false
      }
    },
    {
      "name": "microscopy",
      "type": "microscopy_image",
      "alignment_strategy": "manual",
      "alignment_force_recomputing": false,
      "registration_type": "feature_extraction",
      "processing_settings": {
        "color_enhancement": true,
        "gamma": 0.45,
        "contrast_saturation": 0.35,
        "remove_background": true,
        "background_color": "white",
        "clip_percentile": 99,
        "min_object_coverage": 0.01,
        "crop_to_tissue": true,
        "crop_margin": 250,
        "force_recomputing": false
      },
      "registration_settings": {
        "patch_size": 224,
        "background_color": "white",
        "force_recomputing": false
      }
    }
  ]
}

Validation Checklist¶

dataset_path exists and is readable/writable.
reference_modality matches one declared modality name.
Every sample directory contains every declared modality subdirectory.
If registration_type: "feature_extraction" is used, huggingface_token is set and a CUDA GPU is available.
alignment_strategy: "pre_aligned" is only used where modalities are already co-registered.
spatial_annotations.file_type is "geojson" when annotations are enabled.

Configuration Field Reference¶

Top-Level Fields¶

dataset_path¶

reference_modality¶

perform_alignment¶

perform_registration¶

huggingface_token¶

spatial_annotations¶

modalities¶

Per-Modality Fields¶

name¶

type¶

alignment_strategy¶

alignment_force_recomputing¶

registration_type¶

processing_settings¶

registration_settings¶

Processing Settings by Modality¶

microscopy_image¶

msi¶

raman¶

st¶

Registration Settings¶

feature_extraction¶

spot_interpolation¶

spot_aggregation¶

raman_pixel_interpolation¶

Consistent End-to-End Example¶

Validation Checklist¶

`dataset_path`¶

`reference_modality`¶

`perform_alignment`¶

`perform_registration`¶

`huggingface_token`¶

`spatial_annotations`¶

`modalities`¶

`name`¶

`type`¶

`alignment_strategy`¶

`alignment_force_recomputing`¶

`registration_type`¶

`processing_settings`¶

`registration_settings`¶

`microscopy_image`¶

`msi`¶

`raman`¶

`st`¶

`feature_extraction`¶

`spot_interpolation`¶

`spot_aggregation`¶

`raman_pixel_interpolation`¶