Add order to json schema (#208)

Zethson · web-flow · commit 809df27efde6 · 2025-03-21T10:00:25.000+01:00
* Add order to schema

* Add order to schema

* Fix CI

* Add order validation

* Fix order
diff --git a/.github/workflows/make-tutorials-json.yml b/.github/workflows/make-tutorials-json.yml
@@ -24,17 +24,19 @@ jobs:
         with:
           filter: blob:none
           fetch-depth: 0
-      - uses: actions/setup-python@v4
+
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
           cache: "pip" # caching pip dependencies
       - name: Install dependencies for validation script
         run: pip install .[registry]
       - name: Execute validation script and create output directory
         run: |
           ./tutorial-registry/validate.py --outdir=build
+
       - name: Upload GitHub Pages artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: "build"
 
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -6,8 +6,8 @@ default_stages:
   - pre-push
 minimum_pre_commit_version: 2.16.0
 repos:
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.5.1
     hooks:
       - id: prettier
   - repo: https://github.com/astral-sh/ruff-pre-commit
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -3,7 +3,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
 sphinx:
   configuration: docs/conf.py
   fail_on_warning: true
diff --git a/pyproject.toml b/pyproject.toml
@@ -64,9 +64,6 @@ build = "sphinx-build -M html docs docs/_build {args}"
 [tool.hatch.build.targets.wheel]
 bypass-selection = true  # This is not a package
 
-[tool.black]
-line-length = 120
-
 [tool.ruff]
 line-length = 120
 src = ["src"]
diff --git a/tutorial-registry/schema.json b/tutorial-registry/schema.json
@@ -37,6 +37,10 @@
                 "Tips & Tricks"
             ]
         },
+        "order": {
+            "description": "Order of appearence on the website. Lower numbers mean earlier (higher priority).",
+            "type": "number"
+        },
         "modality": {
             "description": "Which modalities are used in the tutorial?",
             "type": "array",
diff --git a/tutorial-registry/tutorials/ATAC-preprocessing/meta.yaml b/tutorial-registry/tutorials/ATAC-preprocessing/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://muon-tutorials.readthedocs.io/en/latest/single-cell-rna-atac/pbmc10k/2-Chromatin-Accessibility-Processing.html
 image: icon.png
 primary_category: ATAC-seq
+order: 10
 tags:
   - preprocessing
   - multimodal
diff --git a/tutorial-registry/tutorials/CITEseq-integration/meta.yaml b/tutorial-registry/tutorials/CITEseq-integration/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://muon-tutorials.readthedocs.io/en/latest/cite-seq/1-CITE-seq-PBMC-5k.html
 image: icon.png
 primary_category: Surface proteins
+order: 10
 tags:
   - multimodal
   - data integration
diff --git a/tutorial-registry/tutorials/Joint-analysis-of-multiomic-data-with-MultiVI/meta.yaml b/tutorial-registry/tutorials/Joint-analysis-of-multiomic-data-with-MultiVI/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://docs.scvi-tools.org/en/stable/tutorials/notebooks/multimodal/MultiVI_tutorial.html
 image: icon.png
 primary_category: ATAC-seq
+order: 20
 tags:
   - preprocessing
   - visualization
diff --git a/tutorial-registry/tutorials/RNA-velocity/meta.yaml b/tutorial-registry/tutorials/RNA-velocity/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scvelo.readthedocs.io/en/stable/getting_started.html
 image: icon.png
 primary_category: scRNA-seq
+order: 50
 tags:
   - preprocessing
   - RNA velocity
diff --git a/tutorial-registry/tutorials/advanced-plotting/meta.yaml b/tutorial-registry/tutorials/advanced-plotting/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scanpy-tutorials.readthedocs.io/en/latest/plotting/advanced.html
 image: icon.png
 primary_category: Tips & Tricks
+order: 30
 tags:
   - visualization
 packages:
diff --git a/tutorial-registry/tutorials/anndata-getting-started/meta.yaml b/tutorial-registry/tutorials/anndata-getting-started/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/anndata_getting_started.html
 image: icon.svg
 primary_category: Data structures
+order: 10
 tags:
   - data structures
 packages:
diff --git a/tutorial-registry/tutorials/anndata-mudata-axes/meta.yaml b/tutorial-registry/tutorials/anndata-mudata-axes/meta.yaml
@@ -5,6 +5,7 @@ description: |
   workflows can be stored in one MuData object.
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/tutorial_axes_anndata_mudata.html
 primary_category: Data structures
+order: 20
 image: icon.svg
 tags:
   - data structures
diff --git a/tutorial-registry/tutorials/bentotools-subcellular-resolution/meta.yaml b/tutorial-registry/tutorials/bentotools-subcellular-resolution/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://squidpy.readthedocs.io/en/latest/notebooks/tutorials/tutorial_vizgen_mouse_liver.html
 image: icon.png
 primary_category: Spatial
+order: 10
 tags:
   - preprocessing
   - visualization
diff --git a/tutorial-registry/tutorials/cellcharter-spatial-transcriptomics/meta.yaml b/tutorial-registry/tutorials/cellcharter-spatial-transcriptomics/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://cellcharter.readthedocs.io/en/latest/notebooks/cosmx_human_nsclc.html
 image: icon.png
 primary_category: Spatial
+order: 20
 tags:
   - compositional analysis
 packages:
diff --git a/tutorial-registry/tutorials/compositional-analysis/meta.yaml b/tutorial-registry/tutorials/compositional-analysis/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://www.sc-best-practices.org/conditions/compositional.html
 image: icon.png
 primary_category: scRNA-seq
+order: 70
 tags:
   - compositional analysis
 packages:
diff --git a/tutorial-registry/tutorials/concatenation-of-multimodal-data/meta.yaml b/tutorial-registry/tutorials/concatenation-of-multimodal-data/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/tutorial_concatenation_anndata_mudata.html
 image: icon.png
 primary_category: Data structures
+order: 40
 tags:
   - concatenation
 packages:
diff --git a/tutorial-registry/tutorials/concatenation-of-unimodal-data/meta.yaml b/tutorial-registry/tutorials/concatenation-of-unimodal-data/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://anndata.readthedocs.io/en/latest/concatenation.html
 image: icon.png
 primary_category: Data structures
+order: 30
 tags:
   - concatenation
 packages:
diff --git a/tutorial-registry/tutorials/decoupler-pseudobulk-de/meta.yaml b/tutorial-registry/tutorials/decoupler-pseudobulk-de/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://decoupler-py.readthedocs.io/en/latest/notebooks/pseudobulk.html
 image: icon.png
 primary_category: scRNA-seq
+order: 30
 tags:
   - differential expression
   - functional analysis
diff --git a/tutorial-registry/tutorials/interoperability/meta.yaml b/tutorial-registry/tutorials/interoperability/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/scverse_data_interoperability.html
 image: icon.png
 primary_category: Tips & Tricks
+order: 20
 tags:
   - interoperability
 packages:
diff --git a/tutorial-registry/tutorials/perturbation-modeling/meta.yaml b/tutorial-registry/tutorials/perturbation-modeling/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://www.sc-best-practices.org/conditions/perturbation_modeling.html
 image: icon.png
 primary_category: scRNA-seq
+order: 60
 tags:
   - perturbation
 packages:
diff --git a/tutorial-registry/tutorials/plotting-in-scanpy/meta.yaml b/tutorial-registry/tutorials/plotting-in-scanpy/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://scanpy-tutorials.readthedocs.io/en/latest/plotting/core.html
 image: icon.png
 primary_category: Tips & Tricks
+order: 10
 tags:
   - visualization
 packages:
diff --git a/tutorial-registry/tutorials/preprocessing-and-clustering/meta.yaml b/tutorial-registry/tutorials/preprocessing-and-clustering/meta.yaml
@@ -6,6 +6,7 @@ description: |
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/basic-scrna-tutorial.html
 image: icon.webp
 primary_category: scRNA-seq
+order: 10
 tags:
   - preprocessing
   - cell-type annotation
diff --git a/tutorial-registry/tutorials/pseudotemporal-ordering/meta.yaml b/tutorial-registry/tutorials/pseudotemporal-ordering/meta.yaml
@@ -4,6 +4,7 @@ description: |
 link: https://www.sc-best-practices.org/trajectories/pseudotemporal.html#
 image: icon.png
 primary_category: scRNA-seq
+order: 40
 tags:
   - pseudotime
   - visualization
diff --git a/tutorial-registry/tutorials/scirpy-tcr/meta.yaml b/tutorial-registry/tutorials/scirpy-tcr/meta.yaml
@@ -5,6 +5,7 @@ description: |
   and compute repertoire overlaps between patients.
 link: https://scirpy.scverse.org/en/latest/tutorials/tutorial_3k_tcr.html
 primary_category: Adaptive immune cell receptor
+order: 10
 image: icon.svg
 tags:
   - quality control
diff --git a/tutorial-registry/tutorials/scverse-objects-in-backed-mode/meta.yaml b/tutorial-registry/tutorials/scverse-objects-in-backed-mode/meta.yaml
@@ -4,6 +4,7 @@ description: |
   without loading full datasets. (AnnData and MuData are saved as .h5ad and .h5mu files)
 link: https://scverse-tutorials.readthedocs.io/en/latest/notebooks/scverse_data_backed.html#working-with-scverse-objects-in-backed-mode
 primary_category: Data structures
+order: 50
 image: icon.png
 tags:
   - data structures
diff --git a/tutorial-registry/tutorials/scvi-batch-effect-removal/meta.yaml b/tutorial-registry/tutorials/scvi-batch-effect-removal/meta.yaml
@@ -4,6 +4,7 @@ description: |
   correct batch effects, and perform differential gene expression analysis.
 link: https://docs.scvi-tools.org/en/stable/tutorials/notebooks/quick_start/api_overview.html
 primary_category: scRNA-seq
+order: 20
 image: icon.svg
 tags:
   - preprocessing
diff --git a/tutorial-registry/tutorials/squidpy-spatial/meta.yaml b/tutorial-registry/tutorials/squidpy-spatial/meta.yaml
@@ -5,6 +5,7 @@ description: |
 link: https://bento-tools.readthedocs.io/en/latest/index.html
 image: icon.png
 primary_category: Spatial
+order: 30
 tags:
   - preprocessing
   - visualization
diff --git a/tutorial-registry/validate.py b/tutorial-registry/validate.py
@@ -9,7 +9,7 @@
 import sys
 from pathlib import Path
 from textwrap import dedent
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 import httpx
 import jsonschema
@@ -50,27 +50,48 @@ def _check_image(img_path: Path) -> None:
 def validate_tutorials(schema_file: Path, tutorials_dir: Path) -> Generator[dict, None, None]:
     """Find all tutorial `meta.yaml` files in the tutorials dir and yield tutorial records."""
     schema = json.loads(schema_file.read_bytes())
-
     known_links = set()
+    known_primary_to_orders: dict[str, set[int]] = {}
 
     for tmp_meta_file in tutorials_dir.rglob("meta.yaml"):
         tutorial_id = tmp_meta_file.parent.name
         with tmp_meta_file.open() as f:
             tmp_tutorial = yaml.load(f, yaml.SafeLoader)
+
         jsonschema.validate(tmp_tutorial, schema)
+
         link = tmp_tutorial["link"]
         if link in known_links:
             raise ValueError(f"When validating {tmp_meta_file}: Duplicate link: {link}")
         known_links.add(link)
+
+        # Check for duplicate orders within the same primary category
+        primary_category = tmp_tutorial.get("primary_category")
+        order = tmp_tutorial.get("order")
+
+        if primary_category and order is not None:
+            if primary_category not in known_primary_to_orders:
+                known_primary_to_orders[primary_category] = set()
+
+            if order in known_primary_to_orders[primary_category]:
+                raise ValueError(
+                    f"When validating {tmp_meta_file}: Duplicate order {order} "
+                    f"for primary category '{primary_category}'"
+                )
+
+            known_primary_to_orders[primary_category].add(order)
+
         _check_url_exists(link)
+
         # replace image path by absolute local path to image
         img_path = tutorials_dir / tutorial_id / tmp_tutorial["image"]
         _check_image(img_path)
         tmp_tutorial["image"] = str(img_path)
+
         yield tmp_tutorial
 
 
-def load_categories(categories_file: Path):
+def load_categories(categories_file: Path) -> dict[str, Any]:
     """Load the categories JSON."""
     with open(categories_file) as f:
         return yaml.load(f, yaml.SafeLoader)
