Edit on GitHub

starplast.lod

Level of detail: what a point stands for at each of the three tiers.

The galaxy tier used to draw one centroid per compartment, and it was wrong in a way that looked merely ugly. A compartment's genes are scattered across the whole map -- measured on the shipped embedding, the median compartment's members spread 0.37 of the map radius from their own mean, while the median compartment centroid sits only 0.17 of the radius from the centre of the map. Averaging points that are spread out lands you near the middle, so all 27 compartments collapsed into a central blob. The picture was not a rendering fault; it was an honest average of a quantity that has no spatial meaning, drawn as though it did.

That the collapse happens at all is the same fact the held-out search reports from the other direction: compartment is the worst-recovered target, below even the study-effort control. The map is not organised by localization, so localization centroids cannot organise the map.

So the galaxy tier is computed from the embedding itself instead, which is what HANDOFF means by "data-driven, not invented tiers". Coarse spatial structure is found by connected components over an occupancy grid: bin the cloud, keep cells with enough genes in them, and join cells that touch. No clustering library is involved, so the browser still opens without scikit-learn, and the result is deterministic -- a galaxy that moves between runs is not a landmark.

GRID = 10

MIN_CELL = 3

MIN_MEMBERS = 40

def galaxies( xyz: numpy.ndarray, grid: int = 10, min_cell: int = 3, min_members: int = 40) -> numpy.ndarray:

Label each gene with a coarse spatial component, or -1 for none.

Labels are assigned in descending order of size, so galaxy 0 is always the largest structure in the map. That keeps the numbering stable when the embedding is rebuilt slightly differently, which matters because these are the things a user learns the names of.

def centroids(xyz: numpy.ndarray, labels: numpy.ndarray):

Centroid, membership and mean spread per label, ordered by label. Ignores -1.

spread travels with the centroid because it is what says whether the centroid means anything. A tight component's mean is a landmark; a diffuse one's mean is the middle of the map, and the caller can then decline to draw it rather than drawing a dot that implies a structure.

def dominant(values, labels: numpy.ndarray, min_frac: float = 0.0, ignore=None):

The most common value within each component, and the fraction of the component holding it.

Returned as a fraction rather than as a bare name so a caller can refuse to label a component that has no majority. "40% cytosol" is a description; "cytosol" would be a claim.

ignore drops absence labels before counting, and without it every galaxy in this map is named "unassigned" -- true, since most of the proteome has no measured call, and useless as a landmark. The fraction is then of the named members, so "cytosol 45%" means 45% of the genes in that galaxy that have any call at all, not 45% of the galaxy.