docs(colouring_by_expression): render gene_symbols/table_name demos from throwaway SpatialData (non-destructive), define region keys, table_layer gene-only

Author: timtreis

examples/colouring_by_expression.ipynb

@@ -36,10 +36,10 @@
    "id": "fcc86e1b",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:17.361016Z",
-     "iopub.status.busy": "2026-08-19T02:29:17.360908Z",
-     "iopub.status.idle": "2026-08-19T02:29:26.826290Z",
-     "shell.execute_reply": "2026-08-19T02:29:26.825597Z"
+     "iopub.execute_input": "2026-08-19T03:40:35.735050Z",
+     "iopub.status.busy": "2026-08-19T03:40:35.734947Z",
+     "iopub.status.idle": "2026-08-19T03:40:41.639318Z",
+     "shell.execute_reply": "2026-08-19T03:40:41.638786Z"
     }
    },
    "outputs": [
@@ -101,6 +101,7 @@
     "import scipy.sparse as sp\n",
     "import anndata as ad\n",
     "import squidpy as sq\n",
+    "from spatialdata import SpatialData\n",
     "from spatialdata.models import TableModel\n",
     "\n",
     "import spatialdata_plot  # noqa: F401  # registers the .pl accessor\n",
@@ -128,10 +129,10 @@
    "id": "bafdb4b8",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:26.827939Z",
-     "iopub.status.busy": "2026-08-19T02:29:26.827804Z",
-     "iopub.status.idle": "2026-08-19T02:29:27.274938Z",
-     "shell.execute_reply": "2026-08-19T02:29:27.274322Z"
+     "iopub.execute_input": "2026-08-19T03:40:41.641157Z",
+     "iopub.status.busy": "2026-08-19T03:40:41.641016Z",
+     "iopub.status.idle": "2026-08-19T03:40:41.978141Z",
+     "shell.execute_reply": "2026-08-19T03:40:41.977468Z"
     }
    },
    "outputs": [
@@ -159,7 +160,10 @@
     "\n",
     "A table can hold several matrices in `.layers` (raw counts, normalised, scaled). `table_layer=` picks\n",
     "which one to colour from. Here we add a log-normalised layer and compare it with the raw `X` above —\n",
-    "the log scale compresses the bright outliers and reveals more structure."
+    "the log scale compresses the bright outliers and reveals more structure.\n",
+    "\n",
+    "(Setup — real data often already carries such a layer.) Note `table_layer` only affects\n",
+    "gene-expression colouring, i.e. a `var_names` lookup; colouring by an `obs` column ignores it."
    ]
   },
   {
@@ -168,10 +172,10 @@
    "id": "6e0ed124",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:27.276470Z",
-     "iopub.status.busy": "2026-08-19T02:29:27.276360Z",
-     "iopub.status.idle": "2026-08-19T02:29:27.941572Z",
-     "shell.execute_reply": "2026-08-19T02:29:27.940894Z"
+     "iopub.execute_input": "2026-08-19T03:40:41.979694Z",
+     "iopub.status.busy": "2026-08-19T03:40:41.979585Z",
+     "iopub.status.idle": "2026-08-19T03:40:42.627545Z",
+     "shell.execute_reply": "2026-08-19T03:40:42.626972Z"
     }
    },
    "outputs": [
@@ -187,6 +191,7 @@
     }
    ],
    "source": [
+    "# setup: add a normalised layer (your data may already have one)\n",
     "raw = table.X.toarray() if sp.issparse(table.X) else table.X\n",
     "table.layers[\"lognorm\"] = np.log1p(raw)\n",
     "\n",
@@ -202,7 +207,8 @@
     "\n",
     "Many datasets index `var` by a stable ID (Ensembl) and keep the human-readable symbol in a column.\n",
     "`color=` then can't find a symbol directly. `gene_symbols=` names the column to map through. We\n",
-    "simulate that layout by moving the current symbols into a column and indexing `var` by `gene_ids`."
+    "simulate that layout on a **copy** of the table and render it through a throwaway `SpatialData`, so the\n",
+    "original table stays symbol-indexed and every earlier cell keeps working."
    ]
   },
   {
@@ -211,10 +217,10 @@
    "id": "9adeae30",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:27.943747Z",
-     "iopub.status.busy": "2026-08-19T02:29:27.943616Z",
-     "iopub.status.idle": "2026-08-19T02:29:28.258279Z",
-     "shell.execute_reply": "2026-08-19T02:29:28.257738Z"
+     "iopub.execute_input": "2026-08-19T03:40:42.629356Z",
+     "iopub.status.busy": "2026-08-19T03:40:42.629247Z",
+     "iopub.status.idle": "2026-08-19T03:40:43.040137Z",
+     "shell.execute_reply": "2026-08-19T03:40:43.039522Z"
     }
    },
    "outputs": [
@@ -230,11 +236,15 @@
     }
    ],
    "source": [
-    "table.var[\"symbol\"] = table.var_names\n",
-    "table.var.index = list(table.var[\"gene_ids\"].values)  # now var is indexed by Ensembl IDs\n",
+    "# setup — skip on your own data: simulate an ID-indexed table on a copy so the original is untouched\n",
+    "table_ids = table.copy()\n",
+    "table_ids.var[\"symbol\"] = table_ids.var_names\n",
+    "table_ids.var.index = list(table_ids.var[\"gene_ids\"].values)  # var now indexed by Ensembl IDs\n",
     "\n",
-    "# color= still takes the symbol; gene_symbols tells the renderer where to find it\n",
-    "sdata.pl.render_shapes(\"spots\", color=gene, gene_symbols=\"symbol\").pl.show()"
+    "# render from a lightweight SpatialData that reuses the spots and the copied, ID-indexed table\n",
+    "# color= still takes the symbol; gene_symbols tells the renderer which var column to map through\n",
+    "demo = SpatialData(shapes={\"spots\": sdata.shapes[\"spots\"]}, tables={\"adata\": table_ids})\n",
+    "demo.pl.render_shapes(\"spots\", color=gene, gene_symbols=\"symbol\").pl.show()"
    ]
   },
   {
@@ -246,7 +256,12 @@
     "\n",
     "An element can be annotated by more than one table. When there is only one, it is used automatically;\n",
     "with several you disambiguate with `table_name=`. We add a second table of per-spot QC flags and\n",
-    "colour by it."
+    "colour by it.\n",
+    "\n",
+    "A table links to its element through three keys in `table.uns['spatialdata_attrs']`: `region` (the\n",
+    "annotated element), `region_key` (the obs column naming that element for each row), and `instance_key`\n",
+    "(the obs column giving each row's id within it). We assemble the two tables into a throwaway\n",
+    "`SpatialData` so the original object is left untouched."
    ]
   },
   {
@@ -255,10 +270,10 @@
    "id": "bf5138a9",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:28.260048Z",
-     "iopub.status.busy": "2026-08-19T02:29:28.259937Z",
-     "iopub.status.idle": "2026-08-19T02:29:28.500584Z",
-     "shell.execute_reply": "2026-08-19T02:29:28.499938Z"
+     "iopub.execute_input": "2026-08-19T03:40:43.041675Z",
+     "iopub.status.busy": "2026-08-19T03:40:43.041570Z",
+     "iopub.status.idle": "2026-08-19T03:40:43.267498Z",
+     "shell.execute_reply": "2026-08-19T03:40:43.266879Z"
     }
    },
    "outputs": [
@@ -283,16 +298,19 @@
    ],
    "source": [
     "attrs = table.uns[\"spatialdata_attrs\"]\n",
-    "region_key, instance_key, region = attrs[\"region_key\"], attrs[\"instance_key\"], attrs[\"region\"]\n",
+    "region_key = attrs[\"region_key\"]      # obs column naming which element each row annotates\n",
+    "instance_key = attrs[\"instance_key\"]  # obs column giving the row id within that element\n",
+    "region = attrs[\"region\"]              # the annotated element (\"spots\")\n",
     "\n",
     "qc_obs = table.obs[[region_key, instance_key]].copy()\n",
     "qc_obs[\"qc\"] = np.where(table.obs[\"total_counts\"] > table.obs[\"total_counts\"].median(), \"high\", \"low\")\n",
     "qc_table = TableModel.parse(\n",
     "    ad.AnnData(obs=qc_obs), region=region, region_key=region_key, instance_key=instance_key\n",
     ")\n",
-    "sdata.tables[\"qc\"] = qc_table\n",
     "\n",
-    "sdata.pl.render_shapes(\"spots\", color=\"qc\", table_name=\"qc\").pl.show()"
+    "# two tables annotate the same spots; table_name picks which one to colour from\n",
+    "demo = SpatialData(shapes={\"spots\": sdata.shapes[\"spots\"]}, tables={\"adata\": table, \"qc\": qc_table})\n",
+    "demo.pl.render_shapes(\"spots\", color=\"qc\", table_name=\"qc\").pl.show()"
    ]
   },
   {
@@ -303,7 +321,8 @@
     "## Summary\n",
     "\n",
     "- Colouring by a gene reads from the **annotating table** of the element.\n",
-    "- `table_layer=` selects the matrix within that table (e.g. raw `X` vs a `lognorm` layer).\n",
+    "- `table_layer=` selects the matrix within that table (e.g. raw `X` vs a `lognorm` layer), for\n",
+    "  gene-expression colouring only — an `obs`-column colour ignores it.\n",
     "- `gene_symbols=` names the `var` column of symbols to look `color=` up in, for ID-indexed tables.\n",
     "- `table_name=` picks the table when an element has more than one; with a single table it is\n",
     "  automatic.\n",
@@ -326,10 +345,10 @@
    "id": "5519326c",
    "metadata": {
     "execution": {
-     "iopub.execute_input": "2026-08-19T02:29:28.502662Z",
-     "iopub.status.busy": "2026-08-19T02:29:28.502516Z",
-     "iopub.status.idle": "2026-08-19T02:29:28.585357Z",
-     "shell.execute_reply": "2026-08-19T02:29:28.584701Z"
+     "iopub.execute_input": "2026-08-19T03:40:43.269197Z",
+     "iopub.status.busy": "2026-08-19T03:40:43.269067Z",
+     "iopub.status.idle": "2026-08-19T03:40:43.301023Z",
+     "shell.execute_reply": "2026-08-19T03:40:43.300478Z"
     }
    },
    "outputs": [