Pre-commit hooks to enforce snakemake formatting

.github/workflows/tests.yml

@@ -43,4 +43,3 @@ jobs:
         run: snakemake -s workflow/Snakefile -d .test --lint --workflow-profile none
       - name: Dry-run (decoupled smoke test)
         run: snakemake -s workflow/Snakefile -d .test --dry-run --workflow-profile none
-

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+exclude: ^(demos/|config/.*\.(tsv|csv)|.*\.svg$)
+repos:
+  - repo: https://github.com/snakemake/snakefmt
+    rev: v2.0.3 # Replace by any tag/version ≥v0.6.0 : https://github.com/snakemake/snakefmt/releases
+    hooks:
+      - id: snakefmt
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+        exclude: ^mkdocs\.yml$
+      - id: end-of-file-fixer
+      - id: trailing-whitespace

CONTRIBUTING.md

@@ -28,19 +28,38 @@ workflow/
 └── schemas/*.yaml    config + sample-sheet validation
 config/               config.yaml, README.md (config reference), sample sheets
 docs/                 the MkDocs site
-.test/               tiny synthetic decoupled fixture for CI
+.test/                tiny synthetic decoupled fixture for CI
 reproduction/         public-data worked examples
 ```
 
 ## Development setup
 
+Snakemake >= 8 and Conda/Mamba are the only host requirements. We also use snakefmt
+and pre-commit hooks to ensure clean diffs and comply with Snakemake linting and formatting
+standards.
+
 ```bash
 git clone https://github.com/cbib/SpaceBlocks && cd SpaceBlocks
-# Snakemake >= 8 and Conda/Mamba are the only host requirements.
+# Install the development environment
+conda create workflow/envs/dev.yaml
+conda activate spaceblocks_dev
 snakemake -n --sdm conda      # dry-run: builds the DAG, validates the config, provisions envs
 snakemake -s workflow/Snakefile -d .test -n --workflow-profile none  # decoupled smoke test
 ```
 
+Install the pre-commit hooks (`pre-commit` is included in `dev.yaml`) so snakefmt and the
+formatting checks run automatically on every commit:
+
+```bash
+pre-commit install
+```
+
+To run them on demand without committing (e.g. against the whole repo):
+
+```bash
+pre-commit run --all-files
+```
+
 Each rule group has its own Conda env, provisioned by `--sdm conda`. Keep the loose `envs/*.yaml`
 as the maintainable surface; the `*_linux-64.lock` files are the exact-reproducibility surface (see
 [Environments](https://cbib.github.io/SpaceBlocks/environments/)).
@@ -55,7 +74,7 @@ These are load-bearing, and most past bugs we experienced during development cam
   `params:`; the script reads `snakemake.params`, **never `config` directly**. After any change,
   cross-check that every param name matches between the `.smk` and its script.
 - **Resources scale with retries.** Don't   hardcode resources in a rule. Every compute rule draws `mem_mb`/`runtime`/`threads` from
-  `config["resources"]` (with a `default`), and `mem_mb` grows with the attempt number. 
+  `config["resources"]` (with a `default`), and `mem_mb` grows with the attempt number.
 - **The contract convention.** `obs["cell_id"]` must equal `obs_names` (as strings); downstream
   joins key on it. Head-produced contracts live at `SAMPLES_DIR/{sample}/{sample}_unfiltered.h5ad`
   (nested); decoupled contracts live at `contract_dir/{sample}.h5ad` (flat).
@@ -65,7 +84,7 @@ These are load-bearing, and most past bugs we experienced during development cam
 - **Guard plotting.** Wrap plot generation in `try/except` (Python) / `tryCatch` (R) so one failed
   figure doesn't crash the rule.
 - **Palettes.** SpaceBlocks allows color palette customization directly from the config. Levels not referenced in config fall back to grey.
-  When no palette is configured for a column, leave colours to scanpy and drop any stale `*_colors` from `uns`. 
+  When no palette is configured for a column, leave colours to scanpy and drop any stale `*_colors` from `uns`.
 
 ## Adding things
 
@@ -94,7 +113,9 @@ snakemake -s workflow/Snakefile -d .test -n --workflow-profile none
 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')"
 
 # 4. Docs build cleanly (only if you touched docs/)
+# If you did not install the development environment, run:
 pip install mkdocs-material pymdown-extensions
+# Build the docs
 mkdocs build --strict
 ```
 

LICENSE.md

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -34,7 +34,7 @@ Its modular architecture supports both public and in-house ST datasets while rem
 The workflow is divided into (optional) technology-specific **HeadBlocks** and common **CoreBlocks** that streamline pre-, post-processing, and informative exploration of results.
 
 <p align="center"><img src="images/main.png" alt="SpaceBlocks workflow overview"><figcaption>Workflow overview and partial output from Xenium 5K demo example.</figcaption><width="700"></p>
- 
+
 A full SpaceBlocks run takes three inputs:
 
 1. **ST formatted AnnData objects**. Either generated from the HeadBlocks, or manually formatted as a standardized h5ad AnnData object. For brevity, **we refer to each of these objects as THE CONTRACT**. Their structure (count matrix, spatial coordinates and optional region annotations) is validated (`validate_input`) before downstream analyses.

config/config.yaml

@@ -9,7 +9,7 @@ post_processing_outdir: /scratch/CBiB/soterino/smk_visiumhd_results
 logdir: /scratch/CBiB/soterino/smk_logs
 spaceranger_processing_outdir: /scratch/CBiB/soterino/smk_spaceranger_results
 # dir with region annotation GeoJSONs (optional, recommended)
-geojson_path: /scratch/CBiB/soterino/geojson 
+geojson_path: /scratch/CBiB/soterino/geojson
 # only when using "mode: decoupled" — dir of pre-built contract h5ads
 contract_dir: ''
 
@@ -128,9 +128,9 @@ analysis:
 
 # ─── Annotation ──────────────────────────────────────────────────────────────
 # (optional, recommended) predefined cell type markers, screened during leiden to ease annotation
-snakemake_cell_markers: config/snakemake_cell_markers.tsv 
+snakemake_cell_markers: config/snakemake_cell_markers.tsv
 # (default) cluster → cell-type TSV (fill template from generate_annotation_template)
-cluster_annotations: config/cluster_annotations.tsv 
+cluster_annotations: config/cluster_annotations.tsv
 # (optional) use external tsv with annotations
 external_annotation:
   enabled: false

docs/getting-started.md

@@ -87,7 +87,7 @@ The output (see [Outputs](outputs.md) for what every file is, and [the output tr
 
 Annotation is the most limiting step in every high-throughput single cell pipeline. It conditions downstream analysis and, thus, it is a breakpoint between CoreBlocks within the SpaceBlocks workflow.
 
-Through the development of SpaceBlocks, we have tested several automatic annotation tools in Visium HD data. The results in our own data had very limited accuracy and, thus, manual annotation is the default option. 
+Through the development of SpaceBlocks, we have tested several automatic annotation tools in Visium HD data. The results in our own data had very limited accuracy and, thus, manual annotation is the default option.
 
 ### 5.1 Manual annotation