Chapter map

1. 1. Coordinate table
2. 2. Neighbor graph
3. 3. Delaunay, radius and kNN rules
4. 4. Sparse adjacency matrix
5. 5. Neighborhood enrichment count
6. 6. Permutation z score
7. 7. Co-occurrence ratio
8. 8. Distance thresholds
9. 9. Ripley K and L
10. 10. Ripley F and G
11. 11. Moran’s I
12. 12. Geary’s C
13. 13. Graph centrality
14. 14. Ligand-receptor permutation
15. 15. Image and texture features
16. 16. Governance and learning

Visit the How Mathematics Works hub for the wider series and its connections to education, reasoning, science, computing, design and careers.

---

1. Coordinate table

This step deserves a careful pause. Every cell or spot has molecular data and physical coordinates.

A concrete situation

Ten cells have micrometre x-y positions.

What the mathematics does not license

Pixel and physical units can be confused. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Store scale and origin. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

2. Neighbor graph

The useful question is not only how to calculate, but what the calculation assumes. Locations become vertices connected by a declared rule.

A concrete situation

Hexagonal spots use grid adjacency.

What the mathematics does not license

One graph does not fit every technology. Evidence becomes stronger when the limitation is tested instead of hidden.

Try it, check it, transfer it

Match graph to resolution. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

3. Delaunay, radius and kNN rules

A small example makes the mechanism visible. Alternative constructions control degree and spatial reach.

A concrete situation

A Delaunay mesh crosses the tissue.

What the mathematics does not license

Long edges can bridge holes. Keeping this boundary clear makes the result easier to audit and transfer.

Try it, check it, transfer it

Plot and trim edges. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

4. Sparse adjacency matrix

This is where modelling choices begin to affect evidence. Only present edges are stored and multiplied efficiently.

A concrete situation

One million possible pairs reduce to local edges.

What the mathematics does not license

Efficiency can hide asymmetry. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Check degrees and symmetry. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

5. Neighborhood enrichment count

The central mathematical idea is concrete. Edges between annotation pairs are counted.

A concrete situation

Pericyte-endothelial edges occur 42 times.

What the mathematics does not license

Counts depend on class abundance and graph degree. Evidence becomes stronger when the limitation is tested instead of hidden.

Try it, check it, transfer it

Preserve raw counts. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

6. Permutation z score

Here the geometry becomes operational. Label shuffles produce a null mean and standard deviation.

A concrete situation

Observed 42 is three null SDs high.

What the mathematics does not license

Exchangeability may fail across slides. Keeping this boundary clear makes the result easier to audit and transfer.

Try it, check it, transfer it

Use blocked permutations. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

7. Co-occurrence ratio

This step deserves a careful pause. Conditional cluster frequency is divided by overall frequency.

A concrete situation

A ratio above one appears at short radius.

What the mathematics does not license

Rare groups create unstable ratios. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Report counts and intervals. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

8. Distance thresholds

The useful question is not only how to calculate, but what the calculation assumes. Scores are evaluated over an ordered radius grid.

A concrete situation

Co-occurrence fades after 80 micrometres.

What the mathematics does not license

Selecting one favorable radius inflates claims. Evidence becomes stronger when the limitation is tested instead of hidden.

Try it, check it, transfer it

Plot the full curve. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

9. Ripley K and L

A small example makes the mechanism visible. Point counts within radius compare with spatial randomness.

A concrete situation

L rises above a simulated envelope.

What the mathematics does not license

Boundaries bias neighborhood area. Keeping this boundary clear makes the result easier to audit and transfer.

Try it, check it, transfer it

Use edge correction and null envelopes. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

10. Ripley F and G

This is where modelling choices begin to affect evidence. Distances from random locations and from observed points describe empty space and nearest neighbors.

A concrete situation

G shifts toward shorter distances.

What the mathematics does not license

Sampling masks alter random locations. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Use the true tissue mask. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

11. Moran’s I

The central mathematical idea is concrete. Centered feature products are averaged across spatial weights.

A concrete situation

High expression neighbors produce positive I.

What the mathematics does not license

Global I can hide local opposites. Evidence becomes stronger when the limitation is tested instead of hidden.

Try it, check it, transfer it

Map local patterns too. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

12. Geary’s C

Here the geometry becomes operational. Squared neighbor differences emphasize local dissimilarity.

A concrete situation

Smooth regions give lower C.

What the mathematics does not license

Weight normalization changes scale. Keeping this boundary clear makes the result easier to audit and transfer.

Try it, check it, transfer it

State the convention. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

13. Graph centrality

This step deserves a careful pause. Degree, clustering and closeness summarize tissue-network position.

A concrete situation

One cell type occupies high-degree regions.

What the mathematics does not license

Centrality can reflect segmentation density. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Control for degree and area. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

14. Ligand-receptor permutation

The useful question is not only how to calculate, but what the calculation assumes. Annotated pairs are tested between cell groups and corrected for multiplicity.

A concrete situation

One pair survives 1000 permutations and BH correction.

What the mathematics does not license

Expression pairing does not prove signaling. Evidence becomes stronger when the limitation is tested instead of hidden.

Try it, check it, transfer it

Add co-occurrence and orthogonal evidence. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

15. Image and texture features

A small example makes the mechanism visible. Tiles yield intensity, segmentation and gray-level co-occurrence statistics.

A concrete situation

Texture contrast differs across two regions.

What the mathematics does not license

Offset, angle, binning and tile size change values. Keeping this boundary clear makes the result easier to audit and transfer.

Try it, check it, transfer it

Version every image setting. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

16. Governance and learning

This is where modelling choices begin to affect evidence. Version coordinates, masks, graphs, radii, nulls, image transforms and features.

A concrete situation

A student counts edges and texture pairs.

What the mathematics does not license

A spatial score is scale-dependent evidence. A trustworthy workflow records the choice before seeing the final test result.

Try it, check it, transfer it

Write a Squidpy workflow card. Then explain the result to someone who has not seen the formula. If the explanation needs a hidden assumption, add that assumption to the model record.

---

A seven-day practice lab

1. Day 1: define the decision, observation unit, X variables and Y or reference condition.
2. Day 2: reproduce the smallest worked example and check every dimension, unit and sign.
3. Day 3: build a transparent baseline and write what it assumes.
4. Day 4: fit the main method inside a training-only pipeline; record every parameter.
5. Day 5: challenge one assumption with a deliberately difficult dataset or operating regime.
6. Day 6: compare validation metrics with the practical workload created by errors.
7. Day 7: present one supported conclusion, one unresolved uncertainty and one safe next experiment.

Questions for a student, parent or mentor

• Which part of the model is a mathematical definition, and which part is a choice?
• What small calculation would catch a sign, scale or dimension error?
• What evidence comes from training, validation and the untouched test?
• What benign condition could look like a fault or prediction failure?
• How would the answer change for another response, asset, school project or time period?
• What should a human review before acting on the score?

A method-specific audit before deployment

Squidpy begins with two mathematical objects: a spatial neighbor graph and, when available, a large tissue image tied to the same coordinates. Grid adjacency, fixed radius, k-nearest neighbors, Delaunay triangulation and Euclidean rules create different graphs. Sparse matrices make large analyses feasible, but sparsity is not a scientific guarantee. Overlay edges on tissue, inspect degree and distance distributions, and state whether edges are directed, symmetrized or weighted.

Neighborhood enrichment compares observed cell-type edge counts with counts obtained after permuting labels. A z-score places the observed count relative to its permutation mean and standard deviation. Co-occurrence uses a different question: across increasing radii, it compares the conditional frequency of another cluster near a chosen cluster with its overall frequency. Enrichment on one graph and co-occurrence at one distance are related views of organization, not interchangeable proof of interaction.

Ripley functions describe clustering or dispersion across distance scales. Moran’s I multiplies centered feature values across spatial weights, whereas Geary’s C emphasizes squared differences between neighbors. The same expression map can look clustered under one scale and less structured under another. Edge correction, tissue boundary, point density, weight normalization and permutation design all matter. Plot curves or score stability over a justified range instead of selecting the most favorable radius after seeing the answer.

The image side is equally mathematical. Summary intensity statistics, segmentation features and gray-level co-occurrence matrices turn pixels into quantitative spot features. Texture contrast, homogeneity and correlation depend on the grayscale discretization, pixel offset, direction and tile size. Squidpy can join these features to molecular measurements efficiently, yet any association inherits registration and segmentation error. Save coordinate transforms, image scale, masks and feature settings so a beautiful tissue map can be reproduced and challenged.

---

Frequently asked questions

What is Squidpy?

Squidpy is a Python framework that combines spatial-neighbor graph analysis, molecular measurements, images and scalable visualization in a shared spatial-omics workflow.

How is the neighbor graph built?

Depending on the technology, it can use grid adjacency, radius, nearest neighbors, Delaunay triangulation or Euclidean-distance rules.

What is neighborhood enrichment?

It compares observed cell-type edge counts with label-permuted counts and expresses the difference relative to the permutation mean and standard deviation.

What is cluster co-occurrence?

Across distance thresholds, it compares the conditional probability of another cluster near a chosen cluster with that cluster’s overall probability.

Why use Ripley and autocorrelation statistics together?

They ask different questions about discrete point patterns and continuous feature similarity, so agreement or disagreement helps describe spatial organization.

Do image features remove the need for visual review?

No. Registration, tile size, grayscale levels, segmentation and feature settings can create or erase patterns; raw images and masks remain essential.

---

Primary source and fact-check note

Giovanni Palla, Hannah Spitzer, Michal Klein et al., “Squidpy: a scalable framework for spatial omics analysis,” Nature Methods 19, 171–178 (2022), DOI 10.1038/s41592-021-01358-2. Definitions and core claims in this article were checked against this primary publication. Calculations shown here were independently recomputed. Examples are educational illustrations; they are not reported industrial performance results.

Useful next reading

• BinSpect graph enrichment
• MERINGUE Moran and local indicators
• Trendsceek point-process statistics
• How Mathematics Works

Keep the options open. Mathematics education supports clearer questions, transferable problem-solving skills and informed choices across science, engineering, computing, AI, statistics, design and many other careers. It does not guarantee intelligence, income, admission or employment; those outcomes depend on far more than one subject or model.

Extended laboratory: topic-specific validation and responsible use

Coordinate audit

Confirm scale, origin, mask and registration.

Graph audit

Overlay edges and inspect distance and degree.

Permutation audit

Preserve class counts and valid blocks.

Distance audit

Plot full co-occurrence and Ripley curves.

Autocorrelation audit

Compare Moran, Geary and local maps.

Image audit

Version tiles, gray levels, offsets and segmentation.

Replication audit

Repeat findings in independent tissue.

Final claim

Every spatial result is conditional on scale and graph.

Mechanism workshop: calculate, challenge and transfer

Workshop 1: Coordinate table

Start with the chapter mechanism: Every cell or spot has molecular data and physical coordinates. Recreate the concrete case: Ten cells have micrometre x-y positions. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Pixel and physical units can be confused. Complete the transfer task: Store scale and origin. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 2: Neighbor graph

Start with the chapter mechanism: Locations become vertices connected by a declared rule. Recreate the concrete case: Hexagonal spots use grid adjacency. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: One graph does not fit every technology. Complete the transfer task: Match graph to resolution. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 3: Delaunay, radius and kNN rules

Start with the chapter mechanism: Alternative constructions control degree and spatial reach. Recreate the concrete case: A Delaunay mesh crosses the tissue. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Long edges can bridge holes. Complete the transfer task: Plot and trim edges. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 4: Sparse adjacency matrix

Start with the chapter mechanism: Only present edges are stored and multiplied efficiently. Recreate the concrete case: One million possible pairs reduce to local edges. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Efficiency can hide asymmetry. Complete the transfer task: Check degrees and symmetry. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 5: Neighborhood enrichment count

Start with the chapter mechanism: Edges between annotation pairs are counted. Recreate the concrete case: Pericyte-endothelial edges occur 42 times. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Counts depend on class abundance and graph degree. Complete the transfer task: Preserve raw counts. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 6: Permutation z score

Start with the chapter mechanism: Label shuffles produce a null mean and standard deviation. Recreate the concrete case: Observed 42 is three null SDs high. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Exchangeability may fail across slides. Complete the transfer task: Use blocked permutations. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 7: Co-occurrence ratio

Start with the chapter mechanism: Conditional cluster frequency is divided by overall frequency. Recreate the concrete case: A ratio above one appears at short radius. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Rare groups create unstable ratios. Complete the transfer task: Report counts and intervals. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 8: Distance thresholds

Start with the chapter mechanism: Scores are evaluated over an ordered radius grid. Recreate the concrete case: Co-occurrence fades after 80 micrometres. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Selecting one favorable radius inflates claims. Complete the transfer task: Plot the full curve. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 9: Ripley K and L

Start with the chapter mechanism: Point counts within radius compare with spatial randomness. Recreate the concrete case: L rises above a simulated envelope. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Boundaries bias neighborhood area. Complete the transfer task: Use edge correction and null envelopes. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 10: Ripley F and G

Start with the chapter mechanism: Distances from random locations and from observed points describe empty space and nearest neighbors. Recreate the concrete case: G shifts toward shorter distances. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Sampling masks alter random locations. Complete the transfer task: Use the true tissue mask. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 11: Moran’s I

Start with the chapter mechanism: Centered feature products are averaged across spatial weights. Recreate the concrete case: High expression neighbors produce positive I. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Global I can hide local opposites. Complete the transfer task: Map local patterns too. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 12: Geary’s C

Start with the chapter mechanism: Squared neighbor differences emphasize local dissimilarity. Recreate the concrete case: Smooth regions give lower C. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Weight normalization changes scale. Complete the transfer task: State the convention. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 13: Graph centrality

Start with the chapter mechanism: Degree, clustering and closeness summarize tissue-network position. Recreate the concrete case: One cell type occupies high-degree regions. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Centrality can reflect segmentation density. Complete the transfer task: Control for degree and area. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 14: Ligand-receptor permutation

Start with the chapter mechanism: Annotated pairs are tested between cell groups and corrected for multiplicity. Recreate the concrete case: One pair survives 1000 permutations and BH correction. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Expression pairing does not prove signaling. Complete the transfer task: Add co-occurrence and orthogonal evidence. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 15: Image and texture features

Start with the chapter mechanism: Tiles yield intensity, segmentation and gray-level co-occurrence statistics. Recreate the concrete case: Texture contrast differs across two regions. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: Offset, angle, binning and tile size change values. Complete the transfer task: Version every image setting. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.

Workshop 16: Governance and learning

Start with the chapter mechanism: Version coordinates, masks, graphs, radii, nulls, image transforms and features. Recreate the concrete case: A student counts edges and texture pairs. Write coordinates, graph edges, annotation counts, permutation means, standard deviations, conditional frequencies, radii, weight matrices and texture co-occurrence cells with names, dimensions and physical units where they exist. Calculate the smallest non-trivial example by hand, then reproduce it in code. Challenge exactly one assumption named here: A spatial score is scale-dependent evidence. Complete the transfer task: Write a Squidpy workflow card. Compare the original result with the challenged result, explain which mathematical object changed, and mark measurement, model output, statistical evidence, biological interpretation and practical decision on separate lines. Reserve complete donors, sections or tissue regions outside tuning whenever the claim concerns transfer.