Use default config.yaml instead of profiles to define .test as the working directory

.github/workflows/tests.yml

@@ -27,7 +27,7 @@ concurrency:
 jobs:
   lint-and-dryrun:
     # Fast smoke test: lints the workflow and builds the full DAG on a tiny synthetic
-    # decoupled dataset (.tests/integration). No Conda envs or Space Ranger needed — a
+    # decoupled dataset (.test). No Conda envs or Space Ranger needed — a
     # dry-run validates the graph and (via the Snakefile) the config against the schema.
     runs-on: ubuntu-latest
     steps:
@@ -41,5 +41,7 @@ jobs:
         # (or an example config pointing at generated paths) cannot break CI.
       - name: Lint workflow
         run: snakemake -s workflow/Snakefile -d .test --lint --workflow-profile none
+      - name: Catalogue rule graph
+        run: snakemake -s workflow/Snakefile -c 1 -d .test --forceall --rulegraph > /dev/null
       - name: Dry-run (decoupled smoke test)
         run: snakemake -s workflow/Snakefile -d .test --dry-run --workflow-profile none

.gitignore

@@ -23,7 +23,7 @@ __pycache__/
 Thumbs.db
 
 # Test outputs
-.test/output/
+.test/test_output/
 
 # Doc build
 site/

.snakemake-workflow-catalog.yml

@@ -4,8 +4,9 @@
 usage:
   mandatory-flags:
     desc: >
-      Configure config/config.yaml and the required sample sheets before
-      execution. Space Ranger must be installed separately when required.
+      Copy config/config.yaml.template to config/config.yaml, then configure it
+      and the required sample sheets. Space Ranger must be installed separately
+      when required.
     flags: []
 
   software-stack-deployment:

.test/config/config.yaml

@@ -12,7 +12,6 @@ precomputed_metadata_dir: ''
 core_samples: config/core_samples.tsv
 xenium5k:
   xenium_dir: "{base_dir}/xenium/{sample}"
-  zarr_dir: ''
   qupath_pyramid_level: 3
   hires_pyramid_level: 3
   pixel_size_um: 0.2125

CONTRIBUTING.md

@@ -112,8 +112,9 @@ snakemake -s workflow/Snakefile -d .test --lint --workflow-profile none
 # 3. The decoupled CoreBlock DAG builds
 snakemake -s workflow/Snakefile -d .test -n --workflow-profile none
 
-# 4. Config still validates against the schema
+# 4. Catalog fixture and user template still validate against the schema
 python -c "import yaml,jsonschema; jsonschema.validate(yaml.safe_load(open('config/config.yaml')), yaml.safe_load(open('workflow/schemas/config.schema.yaml'))); print('Configuration schema validation passed')"
+python -c "import yaml,jsonschema; jsonschema.validate(yaml.safe_load(open('config/config.yaml.template')), yaml.safe_load(open('workflow/schemas/config.schema.yaml'))); print('Configuration template schema validation passed')"
 
 # 5. Docs build cleanly (only if you touched docs/)
 # Activate the development environment
@@ -122,10 +123,11 @@ conda activate spaceblocks_dev
 mkdocs build --strict
 ```
 
-Before a catalogue release, generate the decoupled rule graph once manually:
+Before a Catalog release, run the two checks used by the Catalog:
 
 ```bash
-snakemake -s workflow/Snakefile -d .test --forceall --rulegraph --workflow-profile none > pipeline_rulegraph.dot
+snakemake --lint
+snakemake -s workflow/Snakefile -c 1 -d .test --forceall --rulegraph > pipeline_rulegraph.dot
 ```
 
 Rendering the DOT file to SVG is optional and requires Graphviz:
@@ -134,7 +136,7 @@ Rendering the DOT file to SVG is optional and requires Graphviz:
 dot -Tsvg pipeline_rulegraph.dot > images/rulegraph.svg
 ```
 
-If you modify a HeadBlock, also dry-run the affected mode using a complete platform-specific configuration and representative mock or real inputs. Changing only `mode` in the generic `config/config.yaml` is not sufficient because its input paths are placeholders. Supported modes are `visiumhd`, `xenium5k`, `atera`, `merscope`, and `decoupled`.
+If you modify a HeadBlock, also dry-run the affected mode using a complete platform-specific configuration and representative mock or real inputs. Changing only `mode` in `config/config.yaml.template` is not sufficient because its input paths are placeholders. Supported modes are `visiumhd`, `xenium5k`, `atera`, `merscope`, and `decoupled`.
 
 Quick per-file sanity checks are cheap and worth it: `python -c "import ast; ast.parse(open('file.py').read())"`
 for Python, and `yaml.safe_load` for any YAML you edit.

README.md

@@ -54,7 +54,7 @@ SpaceBlocks requires [Snakemake](https://snakemake.readthedocs.io) and Conda/Mam
 If you are not familiar with Snakemake, there are three key files to configure:
 
 1. `workflow/Snakefile` — loads the config file/s (normally, at `config/config.yaml`), and has the instructions to execute the workflow. It is normally static, so you should not modify it.
-2. The `config.yaml` — defines the parameters for your workflow run (i.e. where the input and output should be found, whether to use an external reference for cell type annotation, etc.). **It needs to be configured.** The config may require other files needed for the run (in the case of SpaceBlocks, `config/core_samples.tsv`).
+2. The `config.yaml` — defines the parameters for your workflow run (i.e. where the input and output should be found, whether to use an external reference for cell type annotation, etc.). Copy `config/config.yaml.template` to `config/config.yaml`, then configure it for your project. The config may require other files needed for the run (in the case of SpaceBlocks, `config/core_samples.tsv`).
 3. The `profiles/config.yaml` — Snakemake is a workflow manager that allows parallelization in systems with job schedulers (i.e. `slurm`), or local execution. **The profile needs to be adapted to your system.** We provide a default profile that runs the `test` pipeline locally and a slurm profile we used on our HPC.
 
 The full [configuration reference](https://cbib.github.io/SpaceBlocks/configuration/) presents a detailed explanation on how to set `config.yaml`.
@@ -73,6 +73,7 @@ In short, to run the workflow:
 git clone https://github.com/cbib/SpaceBlocks && cd SpaceBlocks
 
 # 2. Configure
+cp config/config.yaml.template config/config.yaml
 #    config/visiumhd_samples.csv   — if running mode : visiumhd
 #    config/core_samples.tsv       — one row per sample (+ any design columns)
 #    config/config.yaml            — mode: visiumhd | xenium5k | decoupled, and paths

config/README.md

@@ -1,6 +1,6 @@
 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**.
+Copy **`config/config.yaml.template`** to **`config/config.yaml`** before configuring a run. The template contains all parameters; the committed `config/config.yaml` is only the runnable fixture used by the Snakemake Workflow Catalog.
 
 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.
 
@@ -124,6 +124,9 @@ sample_colors:
   patient:
     "Patient 1": "#000000"
     "Patient 2": "#E69F00"
+  condition:
+    "Control": "#0072B2"
+    "Treatment": "#D55E00"
   batch:
     "Batch 1": "#8E44AD"
 
@@ -153,7 +156,7 @@ The rest of the configuration lives in nested blocks. Files and single parameter
 
 | Section | Condition | What it configures |
 | --- | --- | --- |
-| `xenium5k` | `mode: xenium5k` | Xenium head settings: `xenium_dir`, `zarr_dir`, pyramid levels, and `pixel_size_um`. |
+| `xenium5k` | `mode: xenium5k` | Xenium head settings: `xenium_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`. |
@@ -340,7 +343,7 @@ These files are generated during the run, and can be shared with minimum effort
 
 ## 7. Example use case configurations
 
-The commented `config/config.yaml` is the full template. The mode-specific keys that differ are:
+The commented `config/config.yaml.template` is the full template. The mode-specific keys that differ are:
 
 **Visium HD** (`mode: visiumhd`)
 ```yaml
@@ -357,7 +360,6 @@ spaceranger_processing_outdir: "{base_dir}/sr_out"
 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
@@ -368,7 +370,6 @@ xenium5k:
 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
@@ -398,15 +399,15 @@ All modes additionally set `core_samples`, `post_processing_outdir`, `logdir`, a
 ## 8. Minimal example
 
 ```yaml
-mode: "visiumhd"
-samples: "config/visiumhd_samples.csv"
+mode: "decoupled"
 core_samples: "config/core_samples.tsv"
-geojson_path: "path/to/geojson"
-precomputed_metadata_dir: "/path/to/metadata_visiumhd/"
+contract_dir: "/path/to/contract_h5ads"
+geojson_path: "/path/to/geojson"
+precomputed_metadata_dir: "/path/to/precomputed_metadata/"
 post_processing_outdir: "{base_dir}/results"
-# ... see config/config.yaml for the full, commented template.
+# ... see config/config.yaml.template 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.
+Copy `config/config.yaml.template` to `config/config.yaml`, then adjust the paths and sample sheets to your data.
 
 You may next read the [get started](https://cbib.github.io/SpaceBlocks/getting-started/) documentation and the [public data end-to-end example runs](https://cbib.github.io/SpaceBlocks/demos/).