A first tour: one focused cell, one focused gene¶

AnnZarro shows big matrices one slice at a time. There is always one focused cell and one focused gene. The focused cell picks its row of every cells × cells matrix (obsp) and of every cells × genes layer; the focused gene picks its column of every layer and its row of every genes × genes matrix (varp). Each plot is coloured, or placed, by whichever slice its controls name. Clicking a point moves the focus, and every panel that depends on it fetches its one new slice.

This tour builds that model in the app, then uses it: it walks a diffusion kernel along haematopoiesis, filters cells with a two-condition table, and saves and shares the result. Along the way you rebuild the focus model of the paper’s overview figure as a live layout, and the screenshots of its interface figure (Overview: focus model, slots and comparison, Interface).

What you need¶

AnnZarro with bm_aging_annzarro.zarr in its data directory (Quickstart, Demo data). bm_aging_annzarro.zarr works too; it contains the same fields.
These fields:

Slot	Key	What it is	Selected by
`obsm`	`X_umap`	cell axes
`obs`	`highres_celltype`, `Age`, `kompot_da_Young_to_Old_lfc_zscore`	cell type (31 levels), age group, Kompot differential abundance z-score (Young to Old)
`obsp`	`diffusion_walk_t5`	five-step diffusion walk, dense 8,090 × 8,090	the focused cell’s row
`layers`	`kompot_de_Young_to_Old_fold_change`	Kompot fold change, Old minus Young smoothed log expression	the focused gene’s column, or the focused cell’s row
`varp`	`spearman_fold_change`	Spearman ρ of two genes’ fold changes across cells	the focused gene’s row
`var`	`kompot_de_Young_to_Old_mean_lfc`, `kompot_de_Young_to_Old_mahalanobis`	volcano axes

Cells and genes used: the old haematopoietic stem cell (HSC) HSPC_Old_1#GAAGCCCGTGGCTCTG-1 and the gene H2-Q7, the paper’s examples.

1. Open the data and set the focus¶

In the header choose bm_aging_annzarro.zarr in Dataset.
Click the Focused Gene box, type H2-Q7, press Enter. Click the Focused Cell box, type or paste HSPC_Old_1#GAAGCCCGTGGCTCTG-1, press Enter. Both lists stay open after Enter; press Esc to close them.

The arrows left of each box (“Previous cell”, “Next cell”) step through the history of the focus.

2. One cell, one row¶

In the Welcome tile, under “Create New Panel”, click Cell Plot. A new panel opens with its controls showing. Set:
- X obsm · X_umap · 0; Y obsm · X_umap · 1.
- Color obsp · diffusion_walk_t5. The third dropdown now reads “Focused cell HSPC_Old_1#…”: the colour is that cell’s row.
- Map Blues, then click Reverse, so that a cell the walk does not reach is light grey and the outline of the UMAP stays visible.
The open padlock beside the third Color dropdown means the panel follows the focused cell.¶
Click the title in the tile header and rename the panel “5-step diffusion walk from the focused cell”. Close the controls with the chevron (“Toggle Controls”) in the header.

Each cell’s colour is the probability that a five-step random walk on the diffusion kernel, started at the focused HSC, ends in that cell. The walk stays among the HSCs: the row’s largest value is 0.0126, and 90.7% of its mass is on HSCs (figures/NOTES.md of the paper).

3. Click to move the focus¶

To see where each click lands, put a cell-type map beside the walk.

Click “Split Horizontally” (the first of the two split icons in the tile header). In the new “Add New Panel” tile choose Cell Plot: UMAP axes as before, Color obs · highres_celltype, Palette “As stored in adata.uns”. Close its controls.
Hover over cells in the walk panel: the label shows the cell ID and highres_celltype. Click a GMP in the middle of the central cluster, near UMAP (12, 3). The paper clicked HSPC_Old_3#GGGTATTAGGCCGCTT-1. The header’s Focused Cell changes, and the walk panel fetches that cell’s row (8,090 numbers) and recolours.
Click a cMoP near (12.5, 8), for example Mature_Young_1#CAAGGGATCCCGTAAA-1.
Click a monocyte near (10, 7.5), for example Mature_Young_1#CAACCAAGTATACCCA-1.

Walk from the HSC, confined to the HSC cluster at the lower right of the UMAP. — 1 · HSC¶

Walk from a GMP, spread widely over the central progenitor cluster. — 2 · GMP¶

Walk from a cMoP, concentrated at the top of the central cluster. — 3 · cMoP¶

Walk from a monocyte, concentrated in the monocyte cluster at the top of the central cluster. — 4 · monocyte¶

Each colour bar is scaled to its own row: the HSC’s walk peaks at 0.0126, the GMP’s at 0.0047, because a progenitor’s walk spreads over more cells. The colour-bar title ends with the ID of the cell whose row is shown. The arrows beside Focused Cell replay the sequence.

Note

Paper, interface, panel b. These four frames are panel b of the paper figure.

How similar are these cells really? uses this panel to ask what a kernel row says that the UMAP does not.

4. The four slices of the focus model¶

The walk panel uses one of four kinds of slice. This section puts all four on screen: a 2 × 2 grid whose left column holds cell scatters and right column gene scatters, with the top row driven by the focused cell and the bottom row by the focused gene.

Close the cell-type panel (× in its header), then focus the HSC again (step 2).
Top right: the focused cell’s row of a layer. Click “Split Horizontally” on the walk tile and choose Gene Plot. Set X var · kompot_de_Young_to_Old_mean_lfc and Y var · kompot_de_Young_to_Old_mahalanobis (a volcano), Color layer · kompot_de_Young_to_Old_fold_change. The third dropdown reads “Focused cell …”. Choose Map RdBu and click Center at 0.
Bottom left: the focused gene’s column of the same layer. Click “Split Vertically” (the second split icon) on the walk tile, choose Cell Plot, UMAP axes, Color layer · kompot_de_Young_to_Old_fold_change (third dropdown “Focused gene H2-Q7”), Map RdBu, Center at 0.
Bottom right: the focused gene’s row of varp. Click “Split Vertically” on the gene plot, choose Gene Plot, volcano axes, Color varp · spearman_fold_change (third dropdown “Focused gene H2-Q7”). Choose Map RdBu, type -1 in Min and 1 in Max, and click Lock Range, so that a colour means the same ρ for every gene you focus.

Controls of the bottom-right panel.¶
Close all controls.

Four panels. Top left, UMAP with a small blue patch around the focused HSC. Top right, volcano coloured red and blue by the HSC's fold change per gene. Bottom left, UMAP coloured by H2-Q7's fold change, red in most cells. Bottom right, volcano coloured by Spearman rho with H2-Q7. — Focused cell HSC, focused gene H2-Q7. Top left: the HSC’s row of the walk. Top right: the HSC’s fold change for each gene. Bottom left: H2-Q7’s fold change in each cell. Bottom right: each gene’s ρ with H2-Q7; H2-Q7 itself is the large dot at the top right (mean log₂ fold change 0.37, Mahalanobis distance 15.2).¶

Click a monocyte in the top-left panel, near (10, 7.5). The screenshot below clicked Mature_Young_1#AGAGAATCACTTCATT-1.

After clicking a monocyte. Top left shows a blue patch around the monocyte cluster; top right shows a weaker fold-change pattern. The bottom row is unchanged. — One click on a cell recolours the top row only: the walk now spreads over the monocytes, and the gene scatter shows this monocyte’s fold changes, from −0.39 to +0.40 against −1.35 to +1.11 for the HSC. The bottom row depends only on the focused gene and did not change.¶

Click H2-Aa in the bottom-right volcano: mean log₂ fold change 0.14, Mahalanobis distance 12.6, below and left of H2-Q7. Hover to confirm the name.

After clicking H2-Aa. Bottom left shows H2-Aa's fold change, blue in the naive B cells and red in the memory B cells below them; bottom right shows H2-Aa's correlation row. The top row is unchanged. — One click on a gene recolours the bottom row only: H2-Aa’s fold change in every cell (median −0.60 in naive B cells, +1.41 in memory B cells, the two clusters at the left) and its ρ with every gene, where the MHC class II genes near it turn red (Which genes respond together? follows this module). In both gene scatters the large dot moved to H2-Aa.¶

Note

Paper, overview, panel a. The four panels are the four arrows of the focus-model diagram, each ending in a scatter.

5. Lock a panel and move the focus past it¶

A lock pins one panel’s slice to the cell or gene it shows now, while the other panels keep following the focus. This is how you compare two cells or two genes side by side (Where does a gene change, and how do two cells differ? compares two cells gene by gene this way).

Open the top-left panel’s controls and click the padlock right of the third Color dropdown. It turns blue and its tooltip reads “Unlock (follow focused element)”.
Close the controls and focus the HSC again from the header.

Focus is the HSC again. Top left still shows the monocyte's walk; top right shows the HSC's fold-change row; bottom left marks the HSC in the bottom right of the UMAP. — The header names the HSC and the top-right panel shows its fold changes again. The locked walk panel still shows the monocyte’s row; its colour-bar title names the cell it is locked to.¶

The dark dot in every cell panel, the locked one included, marks the focused cell (the HSC). While a panel is locked and the focus differs, a crosshair button (“Refocus to current selection”) appears beside the padlock. It makes the locked cell the focused cell again, so the other panels catch up with the locked one; the panel stays locked. Click the padlock again to make the panel follow the focus.

6. Four linked panels with a table¶

The paper’s overview screenshot combines a walk, a volcano, a fold-change map and a cell table. From the grid of section 4:

Unlock the walk panel, and focus H2-Q7 and the HSC again.
In the top-right gene plot (the cell’s row of the layer), change Color to varp · spearman_fold_change with Map RdBu, Min -1, Max 1 and Lock Range, as in step 12. Close the bottom-right volcano with × in its header; the top-right one now holds the same view.
Click “Split Vertically” on the top-right volcano and choose Cell Table. In its controls, under “Available Columns” on the obs tab, tick Age, highres_celltype and kompot_da_Young_to_Old_lfc_zscore (type in “Search obs…” to find them) and click Apply Changes. In “Advanced Search” click Add Condition and set highres_celltype · Equals · HSC.
Close all controls.

The AnnZarro window with four panels and the header showing Focused Gene H2-Q7 and Focused Cell HSPC_Old_1#GAAG. — The table reads “Showing 1 to 25 of 319 entries (filtered from 8,090 total entries)”: all 319 HSCs. Click a cell ID in the table and it becomes the focused cell.¶

Note

Paper, interface, panel a. This layout is panel a of the paper figure.

7. Filter cells with two conditions and mask a plot¶

A cell table’s “Advanced Search” holds any number of conditions combined with AND or OR, nested if needed. A plot can take the rows that pass as a mask (“Table filter”). The mask needs no new data from the server, because the plot already holds every cell.

Start a new layout (or split any tile) with a Cell Table: tick Age, highres_celltype and kompot_da_Young_to_Old_lfc_zscore, Apply Changes.
Add Condition: highres_celltype · Equals · HSC.
Add Condition again: kompot_da_Young_to_Old_lfc_zscore · Greater Than · type 2. The vertical AND button left of the conditions combines them; click it to switch to OR. The footer reads “Showing 1 to 25 of 290 entries (filtered from 8,090 total entries)”.

The table with its controls open (column chooser at the top) and the two conditions.¶
Click “Split Horizontally” on the table and add a Cell Plot: UMAP axes, Color obs · kompot_da_Young_to_Old_lfc_zscore, Map RdBu, Center at 0.
In the plot’s controls set Table to the table (it is listed by its title). Cells the filter removes turn grey; the eye button beside it (“Toggle between colouring non-table entries in grey or completely removing them”) hides them instead.

Left, the filtered cell table with two conditions. Right, the UMAP with only the HSC cluster coloured red and all other cells grey. — 290 cells “In table” and 7,800 “Not in table” (grey): the 290 of 319 HSCs whose abundance z-score is above 2, all in the HSC cluster. Edit a condition and the mask follows at once.¶

Note

Paper, interface, panel c. This view is panel c of the paper figure.

The search box above the table (top right) narrows the rows further, on top of the conditions.

Click .* (“Regular Expression Mode”) under the search box, so the search is a regular expression, and type (Mid|Old). The footer reads “Showing 1 to 25 of 286 entries”: the HSCs above z = 2 from Mid and Old mice. The plot follows: 286 cells “In table”, 7,804 grey.

A regular expression in the search box, combined with the two conditions.¶

Keep the parentheses. With smart search on (the wand, the default), Mid|Old without them matches only 56 rows, the Mid ones, because the search wraps the whole term in a pattern that ties Old to the start of the row. A plain word works in either mode: Old alone finds the 230 Old HSCs.
Open the table’s controls and click Export CSV. The file, named after the table title and the date, holds the 286 rows that pass, with the columns of the table: Cell ID, Age, highres_celltype, kompot_da_Young_to_Old_lfc_zscore. Close the controls and click a cell ID in the table: that cell becomes the focused cell everywhere.

8. Save and share the view¶

Save Panel Set stores the panel settings under a name on the server. Every user of the same server can load it, so a lab can keep a shared library of views (Panel sets).

Click Save Panel Set in the header, type a name, click Save.
To reopen it, click Load Panel Set and click Load on its card. Each card shows the dataset (with “available here” or “not found here”) and one icon per panel; Export downloads the set as a JSON file. Load switches to the set’s dataset and opens the panels that were open when it was saved, in their layout, as a share link would; the small icon buttons beside it load on the current dataset, or only add the panels to the closed list (Panel sets). Panels it replaces stay in the closed list under “Duplicate or Reopen Panel”.

The panel sets on the server used for these screenshots (the paper’s five protocol views).¶

Load a panel set file¶

The tutorials and paper-figure pages offer their views as panel set files. To load one:

Click Load Panel Set, then Upload file (bottom left), Browse files and pick the file. The file gets a card with the same buttons as a saved set.
The panel set names its dataset by file name (bm_aging_annzarro.zarr), and the server finds it in its data directory (“available here”). That is the dataset already open. Click Load. A notice reads “Panel set was imported and loaded successfully”, the panel set replaces the open panels, and the panels that were open before are in the closed list under “Duplicate or Reopen Panel”. Same dataset, same focused cell and gene, and the panels of the set open in their saved layout, with their settings, exactly as the share link of this view opens them (Share link). Panels that were closed when the set was saved are listed closed.

After Load: its four panels in their layout, with its focus.¶

Important

A panel set stores what a share link holds (dataset, focus, layout and panel settings), but it is stored on the server under a name. Load opens its panels as a share link would. An uploaded file also becomes a saved panel set on that server, visible to its other users.

Open the views¶

Every section with a Start here box, here and in the other tutorials, has a share link to its view, so you can start at any section. The links are written for the server of Quickstart:

http://127.0.0.1:8000/?dataset_path=bm_aging_annzarro.zarr#view=z1...
└─────────┬─────────┘               └─────┬─────┘      └─┬─┘
1. your server                      2. the store       3. the view

1. Your server address. Replace http://127.0.0.1:8000 with the address you open AnnZarro at (another port, a remote host, an SSH tunnel’s local port).
2. The store. dataset_path=bm_aging_annzarro.zarr (or bm_aging_annzarro.zarr) is a file name: the server looks for it in its data directory (--data-dir, default ~/annzarro-data). If the store is there, leave it. If it is elsewhere, replace the name with the store’s absolute path; only a local single-user server opens paths outside the data directory (Login, users and permissions).
3. The view: everything after #view= (layout, panels, focus). Copy it unchanged.

The same panels as a file: download the box’s panel set file and load it with Load Panel Set > Upload file (Load a panel set file), then Load; the link opens the layout directly. The file names its store by file name too, and does not depend on the server address.

The views of this tour:

The same panels as panel set files (Load a panel set file): overview-focus-model.json, interface-focus-sequence.json, interface-overview.json, interface-table-filter.json.

What you learned¶

The focused cell picks rows (obsp, a layer’s cell row); the focused gene picks columns and rows (a layer’s gene column, varp). Any panel can be coloured by any of them.
A click on a point moves the focus; every panel that follows it reads one new slice.
A lock pins a panel to its current cell or gene, so two states can be compared.
A table filter combines conditions with AND or OR and masks linked plots without new reads.
A share link opens the dataset, focus, layout and panels; a panel set, stored on the server under a name, opens the dataset, focus and panels in their layout with Load.

Next: How similar are these cells really? asks how similar cells really are, reading a kernel or distance row instead of trusting the UMAP.

Screenshots and views are made by docs/_tools/shoot_figs13.py, which follows the paper’s figures/screenshots.py.

A first tour: one focused cell, one focused gene¶

What you need¶

1. Open the data and set the focus¶

2. One cell, one row¶

3. Click to move the focus¶

4. The four slices of the focus model¶

5. Lock a panel and move the focus past it¶

6. Four linked panels with a table¶

7. Filter cells with two conditions and mask a plot¶

8. Save and share the view¶

Load a panel set file¶

Share link¶

Open the views¶

What you learned¶