Highlight UI (modes, pages, groups)#

This page is the “UI map” for highlighting:

  • which buttons exist,

  • what state they change,

  • and what the app will do when you click Confirm, Clear, or switch pages.

At A Glance#

Audience

  • Wet lab / beginner: learn where highlighting lives and how to “save a selection”.

  • Computational users: learn how pages/groups interact with filters, multi-view, and analysis.

  • Developers: learn which UI actions mutate page/group state and what persists in sessions.

Time

  • ~15–25 minutes

Prerequisites

What you’ll learn

  • What the Selection tools, the highlight pages, and the highlighted groups each control

  • How to create/rename/recolor/delete pages

  • How to enable/disable/remove groups (and what “Clear” clears)

  • How to interpret the highlighted cell count (“visible” vs “total”)

  • How to turn your pages into a real categorical obs column with Create categorical

Where the highlight UI lives#

In the left sidebar, open the accordion section labeled Highlighting.

Inside this section you will see four sub-areas, top to bottom:

  1. Selection — the Tool buttons (the four selection tools), then the Select mode switch below them — an input setting, not a fifth tool

  2. Highlights — the highlight page tabs

  3. the highlighted groups of the active page (the list + count + Clear)

  4. Create categorical (a collapsed accordion that turns pages into an obs column)

On the plot itself, the selection bar repeats Select mode’s switch and combine choice, the active tool’s step controls, and the page’s count and Clear (see The selection bar (on the plot)).

1) Selection tools (choose how you build a selection)#

The Tool buttons control which selection tool is active:

  • Annotation

  • KNN drag

  • Proximity drag

  • Lasso

All of these tools create a temporary candidate set and then let you Confirm it into a new highlight group.

Step controls appear after you start selecting#

Once you perform a selection gesture (e.g., finish a lasso), the UI shows “step controls” under the mode description:

  • Confirm: create a new group from the current candidate set

  • Undo / Redo: roll back steps (limited history)

  • Cancel: discard the candidate set

These controls are tool-specific but behave consistently across tools.

Modifier keys (all tools)#

  • Alt starts the selection gesture.

  • Shift+Alt usually means “add” (union).

  • Ctrl+Alt or Cmd+Alt usually means “remove” (subtract).

For the annotation-based tool on categorical fields, Alt acts like “replace” (details in Selection tools (annotation, lasso, proximity, KNN)).

Select mode (touch screens, or no Alt key)#

A touch screen has no Alt key, so the Select mode switch below the four Tool buttons stands in for holding it. It is drawn as a switch, not as another tool button, because it changes how every tool is triggered rather than choosing one:

  • While Select mode is on, a plain primary press runs the active tool exactly as an Alt press does: a one-finger tap (or a plain click) is an Alt+click, and a one-finger drag is an Alt+drag — a lasso, a proximity radius, a KNN degree, or a continuous range, whichever tool is active. It works in every navigation mode and, in multiview, selects in the pane the finger lands on without moving view focus, as Alt+click does.

  • Turning it on shows a Combine choice of Intersect, Add and Subtract (one segmented control), which stands in for the modifiers a finger cannot press: Intersect is a plain Alt gesture (and is the “replace” behaviour of the annotation tool on categorical fields), Add is Shift+Alt, Subtract is Ctrl/Cmd+Alt. A held Shift or Ctrl/Cmd key still wins over the button.

  • Two fingers always navigate: pinch to zoom, move both to pan. A second finger that lands while a one-finger selection is still being drawn abandons that gesture without selecting anything, and the panel says it was interrupted.

  • A tap or click on empty plot selects nothing and changes nothing: it never clears what you have. The panel (and the selection bar) say so, so a miss does not look like a broken tool.

  • To leave Select mode, turn either switch off, or press Esc when no selection is in progress (the first Esc cancels a selection in progress).

Select mode is an input setting, like holding Alt: it is not saved in sessions.

The selection bar (on the plot)#

The selection bar is a small card at the bottom of the plot that carries Select mode’s controls, so you can select, combine, confirm, discard, clear and leave the mode without opening the menu — which on a phone, once opened, covers the whole screen. Every control on it is the Highlighting panel’s own control shown a second time: both show the same state and do exactly the same thing.

From top to bottom it shows:

  1. What a tap or drag will do, for the active tool (for example “Lasso: draw around cells to select them.”), or, while a selection is in progress, how many cells it holds with that tool’s Undo, Cancel and Confirm. Cancel discards the selection in progress (as Esc does); Confirm saves it to the active highlight page.

  2. A one-line note when your last gesture changed nothing (for example “No cell there. Nothing changed; zoom in to hit cells.”).

  3. What is saved on the active highlight page (“40 cells highlighted”), with Clear, which removes this page’s highlights exactly as the panel’s Clear does. It sits on its own row, below Confirm, so a second tap after confirming cannot clear what you just saved.

  4. The Select mode switch and the Intersect / Add / Subtract choice.

When the bar shows:

  • On a touch screen (any device with a touch pointer, including a laptop with a touch screen) it is always there. While Select mode is off it is only the switch, plus a selection still in progress, so you can turn the mode off to rotate with one finger and still confirm or cancel what you drew.

  • With a mouse it appears while Select mode is on, and goes away when you turn it off.

  • On a phone it hides while the full-screen menu is open.

It is centred in the part of the plot the sidebar leaves uncovered (the same area the multiview grid is laid out in, so the bar and the panels always agree), and notifications stack above it rather than covering it. A finger on the bar never reaches the plot, so tapping or dragging on it never starts a selection or moves the camera.

2) Highlight pages (tabs = alternative “workspaces”)#

Highlight pages are the top-level organization unit.

Each page contains its own list of highlight groups. Only one page is active for highlight rendering at a time.

Create a new page#

Click the + button next to the page tabs.

Expected behavior:

  • a new page is created,

  • the app switches to it immediately,

  • the group list becomes empty (because the new page has no groups yet).

Rename a page#

Double-click the page name in the tab strip.

Typical editing behavior:

  • press Enter to commit,

  • press Escape to cancel,

  • clicking away (blur) commits the current text.

Recolor a page#

Each page tab has a color indicator (a small color swatch).

Click it to open a color picker and choose a new color.

The page color is used for:

  • quick visual identification of pages,

  • some analysis/UI components that reference pages.

Delete a page#

If you have more than one page, an × delete control appears on tabs.

Rules:

  • you cannot delete the last remaining page,

  • if you delete the currently active page, the UI switches to another page automatically,

  • the page goes at once, and a notification offers Undo for a few seconds: it puts the very page back (its groups, its place, its id, so analyses naming it find it again), unless the open cells changed since.

Combine pages (union / intersection)#

You can create a derived page by dragging one page tab onto another, or by pressing the ⋈ control on a tab.

On drop, the UI offers:

  • Intersection (∩): cells that are in both pages (enabled groups only)

  • Union (∪): cells that are in either page (enabled groups only)

This creates a new page whose name reflects the operation (e.g. Page A ∩ Page B).

The Highlighting panel with two page tabs ringed, their names shortened — Page 1 with a blue swatch carrying 826, and the active Page 2 with a red swatch carrying 267, each with a combine (⋈) and a delete (×) control — the list reading 267 cells highlighted with one Proximity (267 cells) (267) group, and the pointer on the button that adds another page.

Two pages. Each tab carries a colour swatch, the page name, and that page’s total membership. Only the active tab’s groups are listed below and only they are rendered — which is why “Clear did nothing” is almost always “Clear worked, on the other page”.#

Note

If the intersection is empty, the derived page can be created with zero groups (an “empty result”). This is expected.

3) Highlighted groups (the actual persistent selections)#

Highlight groups live inside the currently active page.

Create a group (the normal way)#

To create a new highlight group:

  1. choose a highlight mode (lasso/proximity/KNN/annotation)

  2. build a candidate set (possibly multi-step)

  3. click Confirm

Result:

  • a new group appears in the list

  • highlighted cells are emphasized in the canvas

Enable/disable a group#

Each group has a checkbox:

  • checked = group contributes to highlighting and analysis

  • unchecked = group is ignored (but kept)

This is the safest way to temporarily remove a group from consideration without deleting it.

Remove a group#

Click the × next to a group to remove it from the page.

The group goes at once, and a notification offers Undo for a few seconds, putting it back in its place on its page (unless the open cells changed since). A session keeps your work across reloads.

After a reload#

Highlights are kept as a draft in this browser while you work (per dataset, each group’s cells by their row in the file). When the same dataset opens again with nothing highlighted, a notification offers them back: 3 highlights from 14:32 on this dataset were not saved in a session (1 highlight … was not saved for one) with Restore. Highlights you saved in a session, or loaded from one, are not offered: the session file holds them, so their draft is removed until you change them. Restore puts the pages and groups back (a group made from a category or a value range comes back as a selection of the same cells and name); on another subsample of the dataset, the cells not open are left out and counted. Nothing is restored unless you press it, and a private window keeps no draft. A saved session is still the way to keep work for good or share it.

Clear all groups (what “Clear” clears)#

The Clear button clears all groups on the active page.

It does not delete other pages.

Keyboard shortcut:

  • press x (when you are not typing in a text field) to clear highlights.

Important

If you have multiple highlight pages, “Clear” can feel like it “didn’t work” because you may be looking at a different page. Always confirm the active page tab.

Export the highlighted cells (CSV, .h5ad)#

Beside Clear, while cells are highlighted:

  • CSV writes the active page’s groups for every open cell by obs name, one true/false column per group (cellucid_highlight__<group id>).

  • .h5ad writes the highlighted cells as an AnnData subset: their obs names and every obs field (your own fields included; continuous ones as float32 or float64, as Cellucid holds them; a categorical keeps whether its categories are ordered, its labels in their own type – integers stay integers, True/False stay booleans – and the colours shown, as Scanpy’s uns['<field>_colors']), each group as a boolean column, the genes, the expression rows of the matrix the data mapping reads, and the embeddings shown, as stored. Only the highlighted cells’ names and embedding rows are read, and a field read for the export is let go again once written, so a few cells of a very large dataset cost their own rows. Before it reads, its card says how many bytes the expression rows take to read and, over a link, about how long on this connection (the price the gene sample and Read for all cells are given; the parts are under Details), and Cancel on the card stops it with nothing saved. The rows are one read of every highlighted cell, written to this browser’s storage part by part as they arrive, so the export holds one part at a time while the next is downloaded. Its genes are their identifiers (the var index, as adata.var_names holds them), with the names Cellucid shows in var['symbol'] when they differ. A field name an HDF5 file cannot hold (one with / in it, or .) is written renamed, and Cellucid says which. anndata, Scanpy, h5py, cellucid-python and Cellucid itself read it.

Both list the cells in the dataset’s own order (ascending original position), whatever order the file stores them in or the viewer opened them in: the order viewer.subset() (R: cellucid_subset()) gives.

An export shows a progress card with Cancel, which stops it where it is: nothing is downloaded, and nothing is reported as failed. A CSV names every open cell, so on a large dataset it is large whatever is highlighted (10 million cells: a few hundred MB). Its card says about how large it will be once its first rows are written (Export the highlighted cells (CSV) · about 312 MB…), and the finished card says its size. Its rows are written a batch at a time into this browser’s storage, so the page never holds the file. While one export is being written, another click says so instead of starting a second.

Each obs field’s Export button (beside Duplicate) writes that field as a CSV of obs names and values; a gene set editor’s Export writes its sets as GMT, genes by identifier. A Cellucid CSV declares each column in its second row – kind, then highlight, categorical or continuous – so labels such as 0, 10 or True come back as labels, never as numbers or groups, and a cell the file does not list comes back unknown. cellucid.pull(adata, path) in Python and cellucid_pull(object, path) in R read any of these files back onto the object in one call (Round trip (results back from the viewer, columns and gene sets into it)).

Reading the highlighted cell count (“visible” vs “total”)#

Above the group list, Cellucid displays a summary like:

  • “No cells highlighted”

  • “12,345 cells highlighted”

  • “1,234 of 12,345 highlighted cells visible”

Interpretation:

  • total = membership in enabled groups on the active page

  • visible = how many of those highlighted cells are currently visible in the current view (after filters and, for very large datasets, LOD/downsampling)

Common reasons “visible < total”:

4) Create categorical (turn pages into a real obs column)#

At the bottom of the Highlighting section there is a collapsed accordion headed Create categorical. It turns the pages you have built into an ordinary categorical observation field — one you can then colour by, filter on, and use as the field for annotation-based selection.

It is always present. It is greyed out only until a dataset is loaded.

The short version#

  1. Expand Create categorical.

  2. Drag page tabs into the Drop pages here box (or pick one in Add page and press Add). Each page becomes one category, named after the page.

  3. Type a name in Column name.

  4. Press Create.

A notification confirms it: Created "<your name>" (<N> categories), and the new field appears alongside the dataset’s own obs fields. Colour by it and Show centroids / Show labels mark each category at the mean position of its cells, in whichever dimension the view shows; switching the dimension moves the labels with the embedding.

The two questions it asks you#

The builder only shows these when they actually apply, so a set of non-overlapping pages that covers every cell will show neither.

  • Cells in more than one page. A section appears headed Overlapping cells with four choices: First page (the default), Last page, New label — one shared category, Overlap unless you rename it — and Each intersection, which makes a separate category per overlap combination and asks you to name each one. Only enabled groups count towards a page’s membership here, exactly as for page combine.

  • Cells in no page at all. A section reports <n> cells not in any page and offers Label for uncovered cells, Unassigned by default. Clear that box if you would rather those cells carry no label.

Note

Limits and refusals (the Create button stays disabled and prints the reason):

  • at least one page must be added — Add at least one highlight page

  • the column name must be non-empty, free of leading and trailing whitespace, and must not contain :

  • the name must not collide with a visible obs field — A visible observation field named "<name>" already exists

  • Each intersection supports at most 32 pages: a cell’s combination of pages is one bit per page in a 32-bit mask, and the session stores each intersection’s label under that mask. The other strategies take any number of pages.

Fields made this way are saved in a .cellucid-session and restored with it, so a collaborator opening your session on the same dataset gets the same column.

What you cannot (yet) do in the highlight UI#

Depending on what you’ve used in other tools, you might look for these features:

  • rename highlight groups

  • recolor highlight groups

  • “add selection to an existing group” after confirming

In the current UI, group membership is edited by:

  • rebuilding the candidate set (union/subtract/intersect), then confirming a new group, and optionally removing the old one.

To take highlights out of Cellucid, use the CSV and .h5ad exports above, viewer.pull() / cellucid_pull() from a notebook, or a session bundle (Session Saving, Restoring, and Sharing), which keeps every page and group for Cellucid itself.

Edge cases and troubleshooting#