Skip to content
PointillViz
PointillViz

© 2026 PointillViz

Neighborhood Composition & Mixing

by PointillViz reference tools

How mixed each cell’s neighbourhood is, and who sits next to whom.

Verifiedv1.1.0
  • cell types
  • neighbourhood
  • entropy
  • enrichment
  • summary
  • cells
  • matrix
  • table
Neighbourhood mixing
Neighbourhood mixingArtwork from the tool’s bundle

Readme

Answers the question: How mixed is each cell’s neighbourhood, and which groups occur next to one another more or less often than expected?

For each cell i, the tool finds its k nearest neighbours and records how many belong to each group.

Map. Each cell is colored by the normalized Shannon entropy of its neighbourhood:

Here, pij is the proportion of cell i’s labelled neighbours belonging to group j, and T is the number of groups present in the dataset. A score of 0 means that all labelled neighbours belong to the same group. Higher values indicate that several groups are represented more evenly.

Matrix. Both axes list all groups. Each square compares the observed number O(A,B) of A-to-B neighbour relations with the expected number E(A,B):

A score of 0 means that the observed and expected numbers match. Scores of +1 and −1 indicate approximately twice and half the expected number, respectively.

The expected number is calculated by multiplying the total number of valid neighbour positions around all A-cells (usually about n(A) × k) by the proportion of valid neighbour positions across all groups occupied by B-cells. Because the calculation counts neighbour positions rather than unique cells, the same cell may be counted multiple times, depending on its position and how many other cells include it among their k nearest neighbours.

Table. Each row summarizes one group. Cells scored is the number of its cells with a valid mixing score, while Mean mixing is their average Mi. Self log2 O/E is the group’s diagonal matrix value and indicates whether its cells cluster together or are more dispersed. Most enriched neighbour is the other group with the highest matrix score, and the accompanying log2 O/E column gives that score.

References

Shannon (1948) Bell Syst. Tech. J. 27:379-423; Pielou (1966) J. Theor. Biol. 13:131-144.

Parameters

ParameterTypeDefaultWhat it does
Neighbours (k)k int, 3–100 15 Sets how many nearest cells define each neighbourhood. Larger values measure mixing over a broader area and produce a smoother result.
Grouping columnfield categorical_field optional Selects the annotation used to define the groups. Defaults to the dataset’s cell-type column.
Minimum cells per categorymin_type_cells int, 0–5,000 25 Categories with fewer cells are not shown in the matrix or table, but are still included in each cell’s mixing score.

Outputs

  • summarywrites a summary
  • cellspaints the spatial view
  • matrixreturns a heatmap
  • tablereturns a table

Tool check

The nine gates this version passed when it was published.

Verified

Passed 9 of 9 gates

  1. bundle pass
  2. manifest pass
  3. entry pass
  4. imports pass, advisory
  5. fixture pass
  6. result pass
  7. determinism pass
  8. edge pass
  9. no_mutation pass
  1. bundle pass

    4 files, 15.3 kB packed and 56.7 kB unpacked, plugin.json at the root.

  2. manifest pass

    neighborhood-composition 1.1.0 by PointillViz reference tools; entry tool.py, outputs summary, cells, matrix, table, 300 s and 4096 MB budget.

  3. entry pass

    tool.py imported in 0.20 s and defines run(ds, params).

  4. imports advisory pass

    1 Python file, importing __future__, backend, math, numpy; no network, subprocess, filesystem-write, dynamic-exec or environment use found.

  5. fixture pass

    ran on the 600-cell fixture in 0.28 s of its 300 s budget, returning summary, cells, table, matrix and 1 log line.

  6. result pass

    returned the declared outputs: summary, cells, table, matrix.

  7. determinism pass

    two runs with identical parameters produced byte-identical results (13.3 kB of JSON).

  8. edge pass

    ran at the minimum corner (k=3, min_type_cells=0) in 0.29 s; at the maximum corner (k=100, min_type_cells=5000) it refused in words rather than crashing: No two categories have at least 5000 cells with coordinates, so there is no composition matrix to build. Lower 'Minimum cells per category'. (code: no_types_pass_floor).

  9. no_mutation pass

    the fixture dataset's 4 files are byte-identical after every run (plugin_cache/, where ds.knn caches, is excluded by design).

Passed every required gate when this version was published. That is a statement about the gates, not about whether the code is safe to run.

Versions

  1. v1.1.0 latest
  2. v1.0.0

More tools