Neighborhoods
Celldega helps you identify neighborhoods of cells, both in physical space, such as a structure in the tissue, and in data space, such as an island in a UMAP or a population in a two-gene XY plot. You can draw them in a Landscape or create them in Python, for example with alpha shapes around a cell type. Drawn neighborhoods keep their state: they are saved with the widget, available in Python as a GeoDataFrame, and can be saved to a file and loaded again.
Neighborhoods then connect to Celldega's neighborhood analysis. The
nbhd functions summarize the cells inside each
neighborhood, such as their cell-type composition or gene expression; a
NeighborhoodCollection keeps the geometry and summaries together; and a
Clustergram compares neighborhoods by those summaries.
Drawing a neighborhood
Create the Landscape with nbhd_edit=True, then:
- Click NBHD to turn on editing.
- Click SKTCH, or press S with the pointer over the view.
- Drag around the cells you want; releasing the mouse closes the shape.
- Name the neighborhood, choose a color, and click Apply (or press Enter).
Drawing a neighborhood around a glomerulus and naming it "glomerulus". It appears in the NBHD bars, and its cells become the Landscape's selected cells.
Press Esc to stop sketching. While sketching, tooltips and cell clicks are
paused. New neighborhoods get unique default names, such as nbhd_spatial_1;
the editor checks custom names for duplicates.
Drawing in UMAP and XY
The same tools work in a UMAP or XY view, where a neighborhood acts as a gate around a population of cells. Each neighborhood belongs to the view in which it was drawn, and only the neighborhoods of the current view are shown. An XY neighborhood also records its genes and scale.
Pressing S over a PBMC UMAP and drawing a gate around the monocytes.
A gate drawn in a UMAP selects cells by their expression profile rather than their location. With spatial data, switch to SPATIAL to see where those cells are in the tissue.
Editing neighborhoods
With editing on:
- Click a neighborhood to edit its shape: drag a vertex, or drag along an edge to add a vertex. A red DEL button deletes the neighborhood. Click the neighborhood again to finish.
- Double-click a neighborhood to rename it or change its color.
- Click a neighborhood's bar to select it and its cells.
Viewing supplied neighborhoods
Neighborhoods made in Python, such as
alpha shapes around each cell type, are passed with
nbhd= as a GeoDataFrame. The NBHD button shows or hides them, its slider
sets their opacity, and the bars list them by area; click a bar or a shape to
select it. Start in this view with landscape_state="nbhd".
gdf_alpha = dega.nbhd.alpha_shape_cell_clusters(adata, cat="leiden")
landscape = dega.viz.Landscape(
base_url="https://your-landscape-files-url",
adata=adata,
nbhd=gdf_alpha,
landscape_state="nbhd",
)
See the alpha-shape and gradient example for building neighborhoods from cell types.
Using neighborhoods in Python
As a notebook widget, a Landscape keeps every neighborhood available to Python:
landscape.nbhd: a GeoDataFrame of neighborhoods from all views, withname,space,coordinate_space, geometry, and, for drawn neighborhoods,cell_idsandcell_count.landscape.nbhd_polygonsholds the same polygons.landscape.get_selected_cells(adata): an AnnData of the currently selected cells, such as those in the last drawn or selected neighborhood.landscape.save_nbhds("neighborhoods.geojson")andlandscape.load_nbhds("neighborhoods.geojson")save and restore them;landscape.select_nbhd("nbhd_xy_1")selects one, restoring its view.- Passing
nbhd=landscape.nbhdto another Landscape of the same dataset shows them there too.
Spatial geometry uses the tissue's coordinates, while UMAP and XY neighborhoods
keep their display coordinates. Filter to the space you need before calculating
areas or distances, then summarize the cells inside with the nbhd functions:
tissue_nbhds = landscape.nbhd.loc[landscape.nbhd["space"] == "spatial"]
# Cell-type composition of each drawn neighborhood.
composition = dega.nbhd.calc_nbhd_by_pop(adata, tissue_nbhds, category="cell_type")
mat = dega.clust.Matrix(composition)
mat.cluster()
dega.viz.Clustergram(matrix=mat)
adata.obsm["spatial"] must use the same coordinates as the DegaFiles. The
Atera breast cancer neighborhoods tutorial
compares neighborhoods by their composition, and the
pancreas islet gradients example
stores geometry, summaries, and relationships in a NeighborhoodCollection.
How saved neighborhoods stay tied to their data
A fingerprint of ordered cell IDs and coordinates (or expression, for XY)
keeps saved gates tied to their original data, even if a local server URL
changes. UMAP and XY geometry is stored in display coordinates with Y
increasing downward; UMAP records axes.y.reversed=True because increasing
X_umap[:, 1] is displayed upward. Matching saved UMAP polygons from the
previous orientation migrate automatically, and cell IDs remain unchanged.
Source code
- Neighborhood coordinate spaces, drawing layer, and neighborhood editor.
- Python selection and neighborhood methods.
Screenshot sources
Animations show the
Atera kidney
DegaFiles and the PBMC 3k AnnData Zarr store from the
Chromium PBMC tutorial,
captured with Celldega 0.28.0 using
scripts/docs_screenshots/capture.py.

