Skip to content

Commit 9460701

Browse files
timtreistimtreis
committed
Preview for PR #21 a42138b 
1 parent 17449da commit 9460701

24 files changed

Lines changed: 189 additions & 93 deletions

‎pr-21/_sources/notebooks/examples/datashader_reductions.ipynb‎

Lines changed: 104 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,10 @@
1818
"- Recognise the datashader contrast caveat.\n",
1919
"\n",
2020
"We use the real Xenium `cells` dataset from `squidpy` (its `transcripts` element and the\n",
21-
"`morphology_focus` image), downloaded and cached on first use."
21+
"`morphology_focus` image), downloaded and cached on first use.\n",
22+
"\n",
23+
"> **Watch out:** on the datashader backend a `PercentileNormalize` does not clip to its percentiles —\n",
24+
"> the single most common datashader-contrast surprise, covered in section 5."
2225
]
2326
},
2427
{
@@ -35,10 +38,10 @@
3538
"id": "879b4d13",
3639
"metadata": {
3740
"execution": {
38-
"iopub.execute_input": "2026-08-18T22:57:59.500527Z",
39-
"iopub.status.busy": "2026-08-18T22:57:59.499253Z",
40-
"iopub.status.idle": "2026-08-18T22:58:05.670740Z",
41-
"shell.execute_reply": "2026-08-18T22:58:05.670194Z"
41+
"iopub.execute_input": "2026-08-19T03:36:01.655642Z",
42+
"iopub.status.busy": "2026-08-19T03:36:01.655518Z",
43+
"iopub.status.idle": "2026-08-19T03:36:07.639521Z",
44+
"shell.execute_reply": "2026-08-19T03:36:07.638799Z"
4245
}
4346
},
4447
"outputs": [
@@ -97,6 +100,56 @@
97100
"sdata"
98101
]
99102
},
103+
{
104+
"cell_type": "markdown",
105+
"id": "46f63a20",
106+
"metadata": {},
107+
"source": [
108+
"The `cells` dataset is a small (~3 MB) crop of a real 10x **Xenium** section (also used in the\n",
109+
"*Colouring points* example). The reductions below aggregate its `transcripts` points, coloured by the\n",
110+
"quality column `qv`:"
111+
]
112+
},
113+
{
114+
"cell_type": "code",
115+
"execution_count": 2,
116+
"id": "2ee8a709",
117+
"metadata": {
118+
"execution": {
119+
"iopub.execute_input": "2026-08-19T03:36:07.641246Z",
120+
"iopub.status.busy": "2026-08-19T03:36:07.641106Z",
121+
"iopub.status.idle": "2026-08-19T03:36:07.644100Z",
122+
"shell.execute_reply": "2026-08-19T03:36:07.643490Z"
123+
}
124+
},
125+
"outputs": [
126+
{
127+
"data": {
128+
"text/plain": [
129+
"['x',\n",
130+
" 'y',\n",
131+
" 'z',\n",
132+
" 'feature_name',\n",
133+
" 'cell_id',\n",
134+
" 'fov_name',\n",
135+
" 'codeword_index',\n",
136+
" 'qv',\n",
137+
" 'transcript_id',\n",
138+
" 'is_gene',\n",
139+
" 'codeword_category',\n",
140+
" 'nucleus_distance',\n",
141+
" 'overlaps_nucleus']"
142+
]
143+
},
144+
"execution_count": 2,
145+
"metadata": {},
146+
"output_type": "execute_result"
147+
}
148+
],
149+
"source": [
150+
"list(sdata[\"transcripts\"].columns)"
151+
]
152+
},
100153
{
101154
"cell_type": "markdown",
102155
"id": "7a08616e",
@@ -111,14 +164,14 @@
111164
},
112165
{
113166
"cell_type": "code",
114-
"execution_count": 2,
167+
"execution_count": 3,
115168
"id": "16d596ee",
116169
"metadata": {
117170
"execution": {
118-
"iopub.execute_input": "2026-08-18T22:58:05.672268Z",
119-
"iopub.status.busy": "2026-08-18T22:58:05.672122Z",
120-
"iopub.status.idle": "2026-08-18T22:58:08.082570Z",
121-
"shell.execute_reply": "2026-08-18T22:58:08.081976Z"
171+
"iopub.execute_input": "2026-08-19T03:36:07.645952Z",
172+
"iopub.status.busy": "2026-08-19T03:36:07.645825Z",
173+
"iopub.status.idle": "2026-08-19T03:36:10.143881Z",
174+
"shell.execute_reply": "2026-08-19T03:36:10.143080Z"
122175
}
123176
},
124177
"outputs": [
@@ -148,19 +201,22 @@
148201
"\n",
149202
"The reduction changes both the picture and the colorbar scale. `max` reports the single brightest value\n",
150203
"in a pixel (bounded by the data max), `mean` averages, and `sum` accumulates — so its colorbar runs far\n",
151-
"higher wherever transcripts pile up."
204+
"higher wherever transcripts pile up.\n",
205+
"\n",
206+
"As a rule of thumb: `sum` for abundance, `mean` for a typical value, `max` for the brightest signal,\n",
207+
"and `std` (below) for heterogeneity."
152208
]
153209
},
154210
{
155211
"cell_type": "code",
156-
"execution_count": 3,
212+
"execution_count": 4,
157213
"id": "b143411e",
158214
"metadata": {
159215
"execution": {
160-
"iopub.execute_input": "2026-08-18T22:58:08.084333Z",
161-
"iopub.status.busy": "2026-08-18T22:58:08.084206Z",
162-
"iopub.status.idle": "2026-08-18T22:58:09.854305Z",
163-
"shell.execute_reply": "2026-08-18T22:58:09.853820Z"
216+
"iopub.execute_input": "2026-08-19T03:36:10.145859Z",
217+
"iopub.status.busy": "2026-08-19T03:36:10.145727Z",
218+
"iopub.status.idle": "2026-08-19T03:36:11.982901Z",
219+
"shell.execute_reply": "2026-08-19T03:36:11.982377Z"
164220
}
165221
},
166222
"outputs": [
@@ -209,21 +265,21 @@
209265
"source": [
210266
"## 3. `count` and `std` — structure without a value column\n",
211267
"\n",
212-
"`count` ignores the colour value and shows how many primitives fall in each pixel (a density, like the\n",
213-
"*Point density maps* notebook). `std` shows the spread of the values per pixel — useful for finding\n",
268+
"`count` ignores the colour value and shows how many primitives fall in each pixel (a density — equivalent to\n",
269+
"`density=True` with no `density_how`, as in the *Point density maps* notebook). `std` shows the spread of the values per pixel — useful for finding\n",
214270
"heterogeneous regions."
215271
]
216272
},
217273
{
218274
"cell_type": "code",
219-
"execution_count": 4,
275+
"execution_count": 5,
220276
"id": "26a8767f",
221277
"metadata": {
222278
"execution": {
223-
"iopub.execute_input": "2026-08-18T22:58:09.856298Z",
224-
"iopub.status.busy": "2026-08-18T22:58:09.856173Z",
225-
"iopub.status.idle": "2026-08-18T22:58:11.072022Z",
226-
"shell.execute_reply": "2026-08-18T22:58:11.071259Z"
279+
"iopub.execute_input": "2026-08-19T03:36:11.984867Z",
280+
"iopub.status.busy": "2026-08-19T03:36:11.984761Z",
281+
"iopub.status.idle": "2026-08-19T03:36:13.208799Z",
282+
"shell.execute_reply": "2026-08-19T03:36:13.208157Z"
227283
}
228284
},
229285
"outputs": [
@@ -263,19 +319,22 @@
263319
"## 4. Datashader for large images — `method=\"datashader\"`\n",
264320
"\n",
265321
"Reductions also apply to images: `method=\"datashader\"` renders large or sparse rasters by aggregating\n",
266-
"pixels, instead of handing the full array to matplotlib."
322+
"pixels, instead of handing the full array to matplotlib.\n",
323+
"\n",
324+
"The image path takes a slightly different reduction vocabulary — it adds `mode`/`first`/`last` and has\n",
325+
"no `count`/`any` — though here we leave `datashader_reduction` at its default."
267326
]
268327
},
269328
{
270329
"cell_type": "code",
271-
"execution_count": 5,
330+
"execution_count": 6,
272331
"id": "09894db6",
273332
"metadata": {
274333
"execution": {
275-
"iopub.execute_input": "2026-08-18T22:58:11.073801Z",
276-
"iopub.status.busy": "2026-08-18T22:58:11.073674Z",
277-
"iopub.status.idle": "2026-08-18T22:58:11.449224Z",
278-
"shell.execute_reply": "2026-08-18T22:58:11.448612Z"
334+
"iopub.execute_input": "2026-08-19T03:36:13.210422Z",
335+
"iopub.status.busy": "2026-08-19T03:36:13.210310Z",
336+
"iopub.status.idle": "2026-08-19T03:36:13.598089Z",
337+
"shell.execute_reply": "2026-08-19T03:36:13.597603Z"
279338
}
280339
},
281340
"outputs": [
@@ -311,14 +370,14 @@
311370
},
312371
{
313372
"cell_type": "code",
314-
"execution_count": 6,
373+
"execution_count": 7,
315374
"id": "65c8ca02",
316375
"metadata": {
317376
"execution": {
318-
"iopub.execute_input": "2026-08-18T22:58:11.450993Z",
319-
"iopub.status.busy": "2026-08-18T22:58:11.450884Z",
320-
"iopub.status.idle": "2026-08-18T22:58:11.776013Z",
321-
"shell.execute_reply": "2026-08-18T22:58:11.775507Z"
377+
"iopub.execute_input": "2026-08-19T03:36:13.599890Z",
378+
"iopub.status.busy": "2026-08-19T03:36:13.599766Z",
379+
"iopub.status.idle": "2026-08-19T03:36:13.934807Z",
380+
"shell.execute_reply": "2026-08-19T03:36:13.934204Z"
322381
}
323382
},
324383
"outputs": [
@@ -350,13 +409,14 @@
350409
"source": [
351410
"## Summary\n",
352411
"\n",
412+
"- **Contrast caveat first:** datashader contrast follows the aggregate range, not norm percentiles —\n",
413+
" use the matplotlib backend when you need percentile (or any non-`vmin`/`vmax`) contrast.\n",
353414
"- On the datashader backend, a continuous colour needs a **reduction** to combine the primitives that\n",
354415
" share a pixel; `datashader_reduction` sets it (default `max`).\n",
355-
"- `max`/`mean`/`sum` change the picture and the colorbar scale; `count` gives a density and `std` the\n",
356-
" per-pixel spread.\n",
357-
"- `method=\"datashader\"` applies to images too, for large or sparse rasters.\n",
358-
"- Datashader contrast follows the aggregate range, not norm percentiles — use the matplotlib backend\n",
359-
" for percentile contrast."
416+
"- `max`/`mean`/`sum` change the picture and the colorbar scale; `count` gives a density (same as\n",
417+
" `density=True`) and `std` the per-pixel spread.\n",
418+
"- `method=\"datashader\"` applies to images too, for large or sparse rasters (with a slightly different\n",
419+
" reduction vocabulary)."
360420
]
361421
},
362422
{
@@ -369,14 +429,14 @@
369429
},
370430
{
371431
"cell_type": "code",
372-
"execution_count": 7,
432+
"execution_count": 8,
373433
"id": "9a906bc9",
374434
"metadata": {
375435
"execution": {
376-
"iopub.execute_input": "2026-08-18T22:58:11.777869Z",
377-
"iopub.status.busy": "2026-08-18T22:58:11.777766Z",
378-
"iopub.status.idle": "2026-08-18T22:58:11.815022Z",
379-
"shell.execute_reply": "2026-08-18T22:58:11.814271Z"
436+
"iopub.execute_input": "2026-08-19T03:36:13.937167Z",
437+
"iopub.status.busy": "2026-08-19T03:36:13.937056Z",
438+
"iopub.status.idle": "2026-08-19T03:36:14.008592Z",
439+
"shell.execute_reply": "2026-08-19T03:36:14.007897Z"
380440
}
381441
},
382442
"outputs": [

‎pr-21/_static/documentation_options.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
const DOCUMENTATION_OPTIONS = {
2-
VERSION: '0.1.dev1+g375c17330.d20260818',
2+
VERSION: '0.1.dev1+g375c17330.d20260819',
33
LANGUAGE: 'en',
44
COLLAPSE_INDEX: false,
55
BUILDER: 'html',

‎pr-21/api.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
5757
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
5858

59-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
59+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
6060
<script src="_static/doctools.js?v=fd6eb6e6"></script>
6161
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
6262
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -71,7 +71,7 @@
7171
<link rel="prev" title="Datashader reductions in spatialdata-plot" href="notebooks/examples/datashader_reductions.html" />
7272
<meta name="viewport" content="width=device-width, initial-scale=1"/>
7373
<meta name="docsearch:language" content="en"/>
74-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
74+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
7575

7676

7777
<script src="_static/searchtools.js"></script>

‎pr-21/changelog.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
5757
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
5858

59-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
59+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
6060
<script src="_static/doctools.js?v=fd6eb6e6"></script>
6161
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
6262
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -71,7 +71,7 @@
7171
<link rel="prev" title="Plotting (.pl)" href="plotting.html" />
7272
<meta name="viewport" content="width=device-width, initial-scale=1"/>
7373
<meta name="docsearch:language" content="en"/>
74-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
74+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
7575

7676

7777
<script src="_static/searchtools.js"></script>

‎pr-21/contributing.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
5757
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
5858

59-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
59+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
6060
<script src="_static/doctools.js?v=fd6eb6e6"></script>
6161
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
6262
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -71,7 +71,7 @@
7171
<link rel="prev" title="Changelog" href="changelog.html" />
7272
<meta name="viewport" content="width=device-width, initial-scale=1"/>
7373
<meta name="docsearch:language" content="en"/>
74-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
74+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
7575

7676

7777
<script src="_static/searchtools.js"></script>

‎pr-21/gallery.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
5757
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
5858

59-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
59+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
6060
<script src="_static/doctools.js?v=fd6eb6e6"></script>
6161
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
6262
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -71,7 +71,7 @@
7171
<link rel="prev" title="spatialdata-plot: rich static plotting from SpatialData objects" href="index.html" />
7272
<meta name="viewport" content="width=device-width, initial-scale=1"/>
7373
<meta name="docsearch:language" content="en"/>
74-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
74+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
7575

7676

7777
<script src="_static/searchtools.js"></script>

‎pr-21/genindex.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
4545
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
4646

47-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
47+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
4848
<script src="_static/doctools.js?v=fd6eb6e6"></script>
4949
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
5050
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -57,7 +57,7 @@
5757
<link rel="search" title="Search" href="search.html" />
5858
<meta name="viewport" content="width=device-width, initial-scale=1"/>
5959
<meta name="docsearch:language" content="en"/>
60-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
60+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
6161

6262

6363
<script src="_static/searchtools.js"></script>

‎pr-21/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=90905a2f556bf617f1a9" />
5757
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=90905a2f556bf617f1a9" />
5858

59-
<script src="_static/documentation_options.js?v=6ef967b8"></script>
59+
<script src="_static/documentation_options.js?v=d505e5a5"></script>
6060
<script src="_static/doctools.js?v=fd6eb6e6"></script>
6161
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
6262
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -70,7 +70,7 @@
7070
<link rel="next" title="Gallery" href="gallery.html" />
7171
<meta name="viewport" content="width=device-width, initial-scale=1"/>
7272
<meta name="docsearch:language" content="en"/>
73-
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260818" />
73+
<meta name="docsearch:version" content="0.1.dev1+g375c17330.d20260819" />
7474

7575

7676
<script src="_static/searchtools.js"></script>

0 commit comments

Comments
 (0)