Add colour and palettes tutorial (#4)

Author: timtreis

.github/workflows/execute.yaml

@@ -79,8 +79,12 @@ jobs:
       - name: Re-execute selected notebooks
         if: steps.pick.outputs.files != ''
         run: |
+          # Pin kernel_name to python3 so notebooks committed with a
+          # contributor-local kernel name (e.g. from a pixi `kernel-install`
+          # task) still execute against CI's stock python3 kernel.
           while IFS= read -r nb; do
             [ -z "$nb" ] && continue
             echo "Executing $nb"
-            jupyter nbconvert --to notebook --execute --inplace "$nb"
+            jupyter nbconvert --to notebook --execute --inplace \
+              --ExecutePreprocessor.kernel_name=python3 "$nb"
           done <<< "${{ steps.pick.outputs.files }}"

.gitignore

@@ -15,6 +15,8 @@ dist/
 env/
 venv/
 ENV/
+.pixi/
+pixi.lock
 
 # Editors
 .idea/

examples/visium_mouse_brain.ipynb

@@ -16,7 +16,7 @@ authors = [{ name = "scverse" }]
 # the notebooks end-to-end.
 [project.optional-dependencies]
 exec = [
-    "spatialdata-plot>=0.3",
+    "spatialdata-plot>=0.3.4",
     "squidpy",
     "jupyter",
     "ipykernel",
@@ -35,6 +35,28 @@ Documentation = "https://spatialdata.scverse.org/projects/plot/en/latest/"
 [tool.hatch.build.targets.wheel]
 bypass-selection = true
 
+# Pixi-managed environment for running and authoring the notebooks. After
+# `pixi install`, register the Jupyter kernel once with `pixi run
+# kernel-install`; the kernel will point at the pixi env's Python, so
+# `pixi run lab` (or any external Jupyter) can execute the notebooks
+# against the exact pinned dependencies.
+[tool.pixi]
+workspace.channels = ["conda-forge"]
+workspace.platforms = ["linux-64", "osx-arm64"]
+
+dependencies.python = ">=3.11"
+dependencies.jupyterlab = "*"
+dependencies.ipykernel = "*"
+dependencies.nbconvert = "*"
+dependencies.watermark = "*"
+
+pypi-dependencies.spatialdata-plot = ">=0.3"
+pypi-dependencies.squidpy = "*"
+
+tasks.kernel-install = 'python -m ipykernel install --user --name sdata-plot-notebooks --display-name "sdata-plot-notebooks"'
+tasks.lab = "jupyter lab"
+tasks.execute = "jupyter nbconvert --to notebook --execute --inplace tutorials/*.ipynb examples/*.ipynb"
+
 [tool.ruff]
 line-length = 120
 target-version = "py311"

examples/visium_mouse_brain.png

@@ -14,11 +14,22 @@ The fluent `.pl` API, layering, and styling on the in-memory `blobs`
 dataset. Ideal first read.
 :::
 
+:::{grid-item-card} Colour and palettes
+:link: color_and_palette
+:link-type: doc
+:img-top: color_and_palette.png
+
+How `color=` resolves, the v0.3.0 `groups` behaviour, and building
+perceptually well-spaced or colourblind-safe palettes with
+`make_palette` and `make_palette_from_data`.
+:::
+
 ::::
 
 ```{toctree}
 :hidden:
 :maxdepth: 1
 
 getting_started
+color_and_palette
 ```