Configuration

This page explains how to fully set up the config files to run SpaceBlocks. Full documentation can be found at https://cbib.github.io/SpaceBlocks/configuration/.

SpaceBlocks is configured through config/config.yaml, which contains all the parameters needed for the run, plus one or two sample sheets.

The explanations on this page are divided by type (directory, parameter, color, and so on). In the config file, parameters are divided by Block and function.

Every key in config/config.yaml is validated against workflow/schemas/config.schema.yaml before the run starts, so a typo or a missing required field fails immediately with a clear message.

Snakemake-catalog page

The full, always-updated table of every parameter (type, default, required) is generated automatically from the schema and shown on the workflow's Snakemake-catalog page. This page covers the how and the why; the schema is the exhaustive reference.

1. Choose a mode

mode selects which Headblock builds the standardized contract h5ad (or none):

Space Ranger installation

The Visium HD HeadBlock additionally needs an external Space Ranger installation.

config["mode"]	Head that runs	Input
visiumhd	spaceranger_count_vhd → generate_qupath_vhd → prepare_input_vhd	10x Visium HD fastqs + Space Ranger
xenium5k	convert_zarr_x5k → generate_qupath_x5k → prepare_input_x5k	Xenium output bundle
atera	convert_zarr_ate → generate_qupath_ate → prepare_input_ate	Atera output bundle; optional registered H&E inputs
merscope	generate_qupath_mer → prepare_input_mer	MERSCOPE region directory
decoupled	(none)	Pre-existing contract h5ad files you provide

The analysis CoreBlocks are identical in all five cases. Atera support is currently alpha because the public preview format may change before commercial release.

2. Paths, files and sample sheets

The SpaceBlocks config/config.yaml sets the input and output directories, and gets the sample information and metadata (for integration and plotting) from one or two TSV files, depending on the config["mode"] set.

Path / File	Key	Condition	Meaning
Path	spaceranger_processing_outdir	Head modes	Directory where the head writes heavy intermediates such as Space Ranger outputs or SpatialData Zarr stores.
File	spaceranger	mode: visiumhd	Path to the Space Ranger installation.
File	probe_set	mode: visiumhd	Probe set CSV needed to run Space Ranger.
File	transcriptome	mode: visiumhd	Reference transcriptome needed to run Space Ranger.
Path	post_processing_outdir	Mandatory	Output directory root; it will contain the result folders for the run.
Path	logdir	Mandatory	Directory for per-rule logs and benchmarks.
Path	geojson_path	Optional, recommended	Directory containing the GeoJSONs that annotate spatial regions for each sample (see the QuPath tutorial).
Path	contract_dir	mode: decoupled	Directory holding the pre-existing contract h5ads to analyse.
File	per_sample_qc	Optional (per-sample filters)	TSV of sample-specific QC filters. If empty, the same analysis.* thresholds apply to every sample (default).
File	snakemake_cell_markers	Optional (pre-annotation)	TSV of canonical marker genes drawn on the Leiden diagnostic plots (leiden_analysis) to guide manual annotation.
File	gene_exploration.queries (config/gene_queries.tsv)	Exploration Coreblock	Genes / gene sets to score (AUCell) and plot in the exploration block.
File	ingest_ref	Optional (auto-annotation)	Annotated scRNA-seq reference h5ad for ingest_ref.
Path	precomputed_metadata_dir	Optional (reproducibility)	Directory of precomputed per-sample metadata TSVs. The metadata can contain precomputed clusters and/or external annotations.

core_samples.tsv is the technology-agnostic sample sheet used by the CoreBlocks in every use case. Visium HD additionally uses visiumhd_samples.csv for fastq, slide, and capture-area information.

For xenium5k, atera, and merscope, per-sample input bundles are located through the corresponding {sample} path pattern in xenium5k.xenium_dir, atera.atera_dir, or merscope.merscope_dir; no second head-specific sample sheet is required.

Color customization for result visualization

You can customize the color scale for any sample metadata in core_samples.tsv as additional columns. See section 3 and section 4 for details.

Sample sheet	Condition	Role
config/core_samples.tsv	Mandatory	The technology-agnostic anchor: one row per sample. The first column is the sample name; any further columns are design metadata (e.g. patient, condition, type) that are stamped into obs and can be surfaced downstream.
config/visiumhd_samples.csv	mode: visiumhd	The Visium HD head sheet: fastq directories (plus any re-sequencing runs), slide, and area per sample.

3. Parameters

Parameters are settings that live exclusively in config/config.yaml and determine the details of the run.

Parameter	Condition	Role
mode	Mandatory	Which headblock builds the contract (see section 1).
random_seed	Reproducibility	Seed for stochastic steps (subsampling, sketching). Note that UMAP/Leiden are not fully deterministic across systems (see section 6).
use_precomputed_clusters	Optional (reproducibility)	If true, reuse Leiden clusters/metadata from precomputed_metadata_dir instead of recomputing them.
ingest_ref_label_key	ingest_ref reference set	Column in the ingest_ref reference that holds the reference cell-type labels.
integration.integrate_key	Mandatory	Variable Harmony corrects over during integration (e.g. sample).
extra_annotations.columns	Optional	core_samples.tsv columns to carry into obs and surface in downstream plots (e.g. [patient, batch]).

4. Color scale customization

In SpaceBlocks, color scales are fully customizable and consistent across analysis plots.

Undefined variable levels are colored in grey

When customizing color palettes, levels not explicitly listed fall back to grey, so a value that renders grey usually means a missing key. If you wish to customize visualization, list all levels in a variable and assign a color for each of them.

To set a given color scale, you just need to specify the HEX color code for each level in config/config.yaml. There are three palette families, each keyed by column → level → hex:

# Sample-metadata palettes — one block per column listed in extra_annotations.columns
sample_colors:
  patient:
    "Patient 1": "#000000"
    "Patient 2": "#E69F00"
  batch:
    "Batch 1": "#8E44AD"

# Cell-type palettes — one block per annotation column (tsv / external / …)
annotation_colors:
  cell_type_tsv:
    "Tcells": "#1f77b4"
    "Fibroblasts": "#2ca02c"
  cell_type_external:          # declare explicitly; not inherited from cell_type_tsv
    "Tcells": "#1f77b4"

# Region palette — lives under analysis, keyed by the region_levels
analysis:
  region_colors:
    "Tumor area": "#46337EFF"
    "Healthy area": "#FDE725FF"

Spatial niches are coloured automatically from a deterministic palette unless you add a spatial_niche block under annotation_colors.

5. Key sections

The rest of the configuration lives in nested blocks. Files and single parameters are covered in section 2 and section 3; colour palettes in section 4.

Section	Condition	What it configures
xenium5k	mode: xenium5k	Xenium head settings: xenium_dir, zarr_dir, pyramid levels, and pixel_size_um.
atera	mode: atera	Atera head settings: atera_dir, Zarr and pyramid options, plus optional registered H&E image, alignment, and keypoint patterns.
merscope	mode: merscope	MERSCOPE head settings: merscope_dir, selected z-plane, embedded-image resolution, and image channels.
contract	Mandatory	Semantic keys of the hand-off object: sample_key, spatial_key, require_region, require_raw_counts, mito_prefix.
analysis	Mandatory	The bulk of the run: QC filters (min_counts / min_genes / min_cells / max_counts / max_pct_mt), the Leiden resolution_scan_*, the pseudobulk analysis_levels + thresholds, the region_levels, and the run_* toggles. Per-sample QC overrides come from per_sample_qc.
resources	Mandatory	Per-rule mem_mb / runtime / threads (with a default). Memory scales with the retry attempt, so an OOM-killed job is resubmitted with more RAM.
external_annotation	optional	Overlay labels from an external tool: enabled, column, keep_unannotated (see section 6).
qc_sweep	optional	Candidate-threshold QC diagnostics (never filters).
spatial_niches	optional	BANKSY niche detection across concatenated samples.
subcompartments	optional	Named cell-type subsets to re-cluster in subcluster.
gene_exploration	Exploration CoreBlock	Genes / gene sets to score (AUCell) and plot in the exploration block, plus its niche_column and rank fraction.

Note

A few one-key blocks are documented elsewhere for readability: integration (integrate_key) and extra_annotations (columns) are parameters in section 3; cluster_annotations is a file in section 2; and the colour blocks (sample_colors, annotation_colors, analysis.region_colors) are in section 4.

6. Advanced: Reproducibility and reusability

Even though we have ensured the highest reproducibility standards when creating SpaceBlocks, some steps are never 100% reproducible between systems (e.g. UMAP calculation, Leiden clustering).

We therefore provide features for minimal file sharing/storage that tighten the reproducibility gap.

SpaceBlocks allows you to input:

• Externally assembled h5ad AnnData objects — run mode: decoupled and point contract_dir at the directory of pre-built contract h5ads. The heads are skipped; the core validates and analyses them directly.
• Pre-computed clusters / annotations — set use_precomputed_clusters: true and precomputed_metadata_dir to reuse Leiden clusters and metadata; for niches, set spatial_niches.use_precomputed: true with spatial_niches.niche_dir.
• Externally annotated data — set external_annotation.enabled: true with external_annotation.column, and choose whether to keep or discard unannotated barcodes downstream via external_annotation.keep_unannotated (see section 5).

These files are generated during the run, and can be shared with minimum effort to reproduce downstream results from raw data.

7. Example use case configurations

The commented config/config.yaml is the full template. The mode-specific keys that differ are:

Visium HD (mode: visiumhd)

mode: "visiumhd"
samples: "config/visiumhd_samples.csv"          # fastq dirs / slide / area per sample
spaceranger: "/path/to/spaceranger"
probe_set: "/path/to/probe_set.csv"
transcriptome: "/path/to/refdata-gex"
spaceranger_processing_outdir: "/path/to/sr_out"

Xenium 5K (mode: xenium5k)

mode: "xenium5k"
xenium5k:
  xenium_dir: "/path/to/xenium/{sample}"   # {sample} pattern to each bundle
  zarr_dir: ""                             # "" → spaceranger_processing_outdir
  qupath_pyramid_level: 3
  hires_pyramid_level: 3
  pixel_size_um: 0.2125

Atera (mode: atera, alpha)

mode: "atera"
atera:
  atera_dir: "/path/to/atera/{sample}/outs"
  zarr_dir: ""
  qupath_pyramid_level: 3
  hires_pyramid_level: 3
  pixel_size_um: 0.2125
  he_image: ""       # optional {sample} pattern; set with he_alignment
  he_alignment: ""   # optional {sample} pattern; set with he_image
  he_keypoints: ""   # optional {sample} pattern

MERSCOPE (mode: merscope)

mode: "merscope"
merscope:
  merscope_dir: "/path/to/merscope/{sample}"
  z_index: 3
  hires_pixel_size_um: 1.0
  channels: [DAPI, PolyT, Cellbound1, Cellbound2, Cellbound3]

Externally prepared data (mode: decoupled)

mode: "decoupled"
contract_dir: "/path/to/contract_h5ads"    # one <sample>.h5ad file per sample

All modes additionally set core_samples, post_processing_outdir, logdir, and the other required common keys in config/config.yaml; geojson_path is optional but strongly recommended.

8. Minimal example

mode: "visiumhd"
samples: "config/visiumhd_samples.csv"
core_samples: "config/core_samples.tsv"
geojson_path: "/path/to/geojson"
post_processing_outdir: "/path/to/results"
# ... see config/config.yaml for the full, commented template.

Start from the commented config/config.yaml shipped with the workflow and adjust the paths and sample sheets to your data.

You may next read the get started documentation and the public data end-to-end example runs.