Troubleshooting (highlighting and selection)#

Use this page when selection/highlighting does not match your expectation.

Format: Symptom → likely causes → how to confirm → fix → prevention.

Quick triage (start here)#

These checks solve most “it’s broken” reports in under a minute:

  1. Read the line under the Tool buttons. A gesture the app consumed but could not turn into a step explains itself there, in words; the tool’s own gesture, or what it needs first, is the first line of the Selection (i). See What the app tells you below before assuming a tool is broken.

  2. Filters: are you filtering out the cells you expect to see?

  3. Active page: are you on the highlight page you think you are on?

    • Switching pages changes what is highlighted.

  4. Group enabled: is the group checkbox enabled?

    • Disabled groups do not contribute to highlighting.

  5. Visible vs total: does the highlight count say “X of Y visible”?

    • That usually means highlights exist, but are hidden by filters or LOD.

  6. View panel: are you selecting in the right panel (live vs snapshot)?

  7. Modifier keys: are you holding Alt to start a selection gesture?

    • Shift+Alt = add; Ctrl/Cmd+Alt = subtract.

    • On a touch screen there is no Alt: is Select mode on (its switch, in the Highlighting panel or on the selection bar at the bottom of the plot)? See Select mode (touch screens, or no Alt key).

  8. Tool mode: are you in the tool you think you are in (Lasso vs Proximity vs KNN vs Annotation)?

    • Annotation additionally needs a coloured field. With none, the panel replaces its Alt+click invitation with the sentence that asks for one; the other three tools never read the active field.

  9. Where you released: did the mouse come up over the plot, or over the sidebar / a notification? A release off the plot abandons the gesture on purpose.

If these do not resolve it, jump to the symptom that matches what you see.

What the app tells you#

Selection tools write one short line under the Tool buttons in the Highlighting panel. That is the only place these messages appear — they are not toasts and there is no message history, because every tool reuses the same one-line slot. Repeating a gesture that fails the same way repaints an identical line rather than stacking a second one.

Two rules hold for every message in the table below:

  • A gesture that produced no step is not a step. It does not advance the step counter and it does not consume an undo.

  • Your standing selection survives. The preview highlight is repainted from the candidate set you already had, even though the drag preview wiped it while you were gesturing. The readout above the message tells you which case you are in: Step N: … current selection if the gesture interrupted a selection that still stands, or nothing above it if nothing was in progress.

What you see

What happened

What to do

“That click did not land on a cell, so there is nothing to select. Zoom in or raise Point size to make cells easier to hit: only the cells the viewer is currently drawing can be clicked.”

Alt+click hit no point. Points draw about a pixel wide when zoomed out, so this is ordinary rather than exceptional.

Zoom in or raise Point size, then click again. A click hits the dot drawn under the pointer, at the size it is drawn, so a bigger dot is a bigger target.

“That gesture ended outside the view, so nothing was selected.”

You released the mouse somewhere other than the plot. The gesture was abandoned deliberately — see the symptom below.

Repeat the gesture and release over the plot.

“That gesture was interrupted before it ended, by a second finger or by the browser, so nothing was selected.”

Select mode: a second finger landed while a one-finger selection was still being drawn (two fingers always zoom and pan), or the browser took the touch over.

Draw with one finger only, and lift it before pinching or panning.

“That cell has no value on that panel’s field, so there is nothing to select.”

Annotation: the clicked cell is missing a value on the field of the panel you pressed, so the rule resolves to no cells.

Click a cell that has a value, or color that panel by a field that covers it.

“That panel is not colored by a field, so there is nothing to select.”

Annotation: the panel you pressed is colored by no field, whatever the focused view is colored by. The gesture is read on the panel you press.

Color that panel by a field, or select in a panel that has one.

“That gesture did not change the selection.”

The gesture resolved to exactly the set you already had.

Nothing is wrong. Draw elsewhere, or change the modifier key.

“Color by a field first (Coloring & filtering), then Alt+click a cell.” (first line of the Selection (i))

Annotation is selected but no panel on screen is colored by a field, so no press can select anything.

Choose a categorical or continuous field first.
A proximity Alt+click on empty space: the pointer is pressed above the embedding where no cell is drawn, and the ringed line in the Highlighting panel, under the tool buttons, reads "That click did not land on a cell, so there is nothing to select. Zoom in or raise Point size to make cells easier to hit: only the cells the viewer is currently drawing can be clicked."

Where to look. The pointer was pressed in empty space above the embedding; the explanation appears on the left, under the Tool buttons, where a step readout would otherwise be.#

Which tools report which:

  • “did not land on a cell” comes from Annotation, KNN drag, and Proximity drag — the tools that need a cell under the pointer to begin. Lasso does not need one, so it never reports this. Proximity reports it only when it cannot place a centre at all; with a candidate set already standing it places one anyway (see the proximity symptom below).

  • “ended outside the view” comes from all four tools, Lasso included.

Note

These lines are not cleared. A notice stays on screen until some later gesture replaces it, so a line you are reading may describe a gesture from a minute ago. Repeat the gesture you are actually debugging before you trust the line.

Symptom: “Nothing highlights (I created a group but can’t see it)”#

Likely causes (ordered)#

  1. The highlighted cells are filtered out (visibility = 0).

  2. You are on the wrong highlight page.

  3. The group exists but is disabled.

  4. The group exists, but LOD/downsampling makes it hard to see at the current zoom.

  5. You created the group on a different dataset (session/dataset mismatch) and it never restored.

How to confirm#

  • Look at the highlight count:

    • if it says “0 of N visible”, the group exists but is not visible right now.

  • Temporarily disable filters:

    • if the highlight appears, it was a visibility problem, not a highlight problem.

  • Switch pages and watch the group list:

    • if the group list changes, you were on the wrong page.

  • Check the group checkbox state:

    • disabled groups appear “inactive”.

Fix#

  • Disable/relax filters first.

  • Ensure you are on the intended page tab.

  • Re-enable the group checkbox.

  • Zoom in (and/or increase point size, if available) to make the highlight halo easier to see.

Prevention#

  • Name pages clearly (e.g., Control, Treated, Hypothesis A).

  • Save a session after creating important highlights (Session Saving, Restoring, and Sharing).

  • When selecting, avoid having “surprise filters” active (especially if using categorical selection).

Symptom: “The highlight count says cells are highlighted, but the plot looks unhighlighted”#

Likely causes (ordered)#

  1. Highlight style is subtle relative to your color-by/background/point size.

  2. Only a small fraction of points are highlighted and you are zoomed out.

  3. The highlighted cells are mostly filtered out (so only a few are visible).

How to confirm#

  • Switch to a simple color-by (or a plain-looking field) temporarily.

  • Zoom in until points are larger on screen.

  • Check whether the count says “X of Y visible”.

Fix#

  • Zoom in; highlights are easiest to see when points are not subpixel-sized.

  • Adjust display settings (point size/background) if your build exposes them.

  • Temporarily simplify filters to increase visible highlighted cells.

Prevention#

  • When validating a selection, use a plain or high-contrast coloring.

  • Capture “before/after” screenshots when documenting a workflow (Verified highlighting captures).

Symptom: “Lasso selects the wrong cells”#

Likely causes (ordered)#

  1. 3D projection ambiguity: lasso selects by screen projection; depth is ambiguous.

  2. You started the lasso in the wrong multi-view panel (grid).

  3. Filters changed between steps; visible set differs.

  4. You intended union/subtract but used intersect (or vice versa) due to modifier keys.

How to confirm#

  • If you are in 3D: rotate the camera and repeat the same lasso. If the selected set changes a lot, you are seeing projection ambiguity.

  • If you are in multi-view grid: start the lasso clearly inside the intended panel (not near borders).

  • Check the step label (it often indicates whether you are intersecting/adding/subtracting).

  • Watch the preview while you draw. The lasso preview shows the set the release would commit under the modifier you are holding, not the raw contents of the polygon. Drawing with Shift+Alt shows your existing selection plus what the polygon adds; drawing with Ctrl/Cmd+Alt shows what would be left after the removal. If the preview does not look like the outcome you want, you are holding the wrong modifier — release outside the plot to throw the gesture away rather than committing it.

Fix#

  • In 3D, use the intended workflow:

    1. lasso once,

    2. rotate substantially,

    3. lasso again with Alt to intersect.

  • If you need a true “local region” in 3D, try Proximity drag instead of lasso.

  • In grid multi-view, switch to “Edit selected view” temporarily to reduce panel ambiguity.

Prevention#

  • Treat lasso in 3D as “projected selection”, not volumetric selection.

  • Use multi-step intersection for 3D.

  • Keep lasso gestures fully inside one panel in grid view.

Symptom: “In Select mode I can’t deselect or clear”#

Tapping empty plot never clears anything in Select mode: it selects nothing, changes nothing, and the selection bar says “No cell there. Nothing changed”. What removes a selection depends on whether it is still in progress or saved:

  • In progress (the selection bar reads “N cells selected” beside Undo, Cancel and Confirm): Cancel discards it, Undo steps back once. Esc cancels it too.

  • Saved to the page (the bar reads “N cells highlighted”): Clear on the bar, or Clear under the page tabs in the Highlighting panel, removes this page’s highlights. Other pages are not touched. To remove one group, use its × in the panel’s list.

  • Leaving Select mode keeps both: turn either switch off, or press Esc with nothing in progress.

Symptom: “I can’t start lasso / nothing happens when I draw”#

Likely causes (ordered)#

  1. You are not holding Alt (lasso mode requires Alt, or Select mode on a touch screen).

  2. You are not in Lasso mode (toolbelt mismatch).

  3. You are in a navigation interaction state (dragging/rotating) and never entered lasso.

  4. Browser/OS intercepts Alt in your environment (rare but possible).

How to confirm#

  • Look under the Tool buttons first. If the app consumed the gesture and threw it away, it says so there in words. No message at all means the gesture never started, which is a different problem — one of the causes above.

  • Click the Lasso mode button again.

  • Hold Alt and look for the cursor change (crosshair) or lasso overlay.

  • Verify in a clean/private window with extensions disabled.

Fix#

  • Use Alt+drag (not plain drag).

  • On a touch screen, turn on Select mode (in the Highlighting panel or on the selection bar at the bottom of the plot) and draw with one finger.

  • If Alt/Option is captured, disable the extension or operating-system shortcut that owns the gesture, then activate Lasso and use Alt/Option+drag again.

Prevention#

  • Learn the mental split:

    • drag = navigation,

    • Alt+drag (or a drag with Select mode on) = selection tool.

Symptom: “I drew a lasso, let go, and nothing was selected”#

You released the mouse somewhere other than the plot — over the floating sidebar, over a notification toast that appeared mid-drag, or outside the browser window. The message under the Tool buttons reads:

That gesture ended outside the view, so nothing was selected.

This is deliberate, not a bug#

The render canvas fills the window and the controls float on top of it, so a drag that wanders onto the sidebar keeps appending points to the polygon behind the panel. Committing that release would select cells the sidebar was covering — cells you never saw, let alone enclosed. Cellucid therefore treats the release as belonging to whatever you released over, abandons the gesture, and says so.

The same rule applies to Proximity drag, KNN drag, and Annotation based selection, not only Lasso.

What survives#

  • Your existing candidate set, exactly as it was: no step was recorded, no undo was spent, and the preview highlight is repainted from it.

  • The readout above the message: Step N: … current selection when the gesture interrupted a selection that still stands, or nothing above it when nothing was in progress.

Fix#

  • Repeat the gesture and make sure the mouse button comes up over the plot.

  • If a toast keeps landing where you draw, wait for it to clear (or draw in a different part of the plot) before starting the gesture.

Prevention#

  • Start and finish selection gestures well inside the plot area, away from the sidebar edge and away from where notifications appear.

Symptom: “Proximity selection selects nothing / selects the wrong region”#

Likely causes (ordered)#

  1. You clicked empty space with no candidate set standing, so there was no valid centre and the gesture never started. The app says so: “That click did not land on a cell, so there is nothing to select…”

  2. You clicked empty space with a candidate set standing, so the tool placed a centre anyway — and it is not where you expected. See below.

  3. Your radius is too small (tiny drag) or too large (huge drag).

  4. Filters are hiding nearby cells; selection only considers visible cells.

  5. The camera is far out with Visualization → Performance → Level of detail (LOD) enabled. The seed Alt+click picks the cell under the pointer, and it can only land on a cell the view is actually drawing — so a zoomed-out camera can refuse a click over a region that does have cells in it. Only the seed click is affected; the drag that follows still evaluates every unfiltered cell (Highlight mental model).

  6. You expected screen-space selection; proximity is embedding-space distance.

How to confirm#

  • Read the line under the Tool buttons: a refused click names itself; a click that places a centre anyway does not.

  • Start by Alt+click directly on a clearly visible cell (zoom in).

  • Drag slowly and watch the overlay radius.

  • Temporarily disable filters and try again.

  • If a click is refused only when zoomed out, zoom in and seed again — or turn Level of detail (LOD) off for the seed click.

Clicking empty space (what the centre actually is)#

When you Alt+click empty space and a candidate set already exists, the centre is not the centroid of that selection. It is the point where your click ray crosses the plane that passes through the centroid facing the camera — in effect, where you clicked, at the selection’s depth. That is what makes “grow/shrink around the current selection” work in 3D without picking a cell first, and it is why the resulting blob is centred on your pointer rather than on the selection.

Fix#

  • Zoom in and click on a cell to set a stable center.

  • Use small drags first; increase radius gradually.

  • If you need geometric control in screen space, use lasso; if you need embedding-space locality, use proximity.

Prevention#

  • Use proximity for “local blob around a seed”, not for “draw around this shape”.

  • Avoid selecting with proximity when the view is heavily filtered unless that is your intention.

Symptom: “KNN drag says no neighbor graph is available (or does nothing)”#

Likely causes (ordered)#

  1. Your dataset holds no neighbour graph (obsp).

  2. Edges exist but are not loaded yet (often loaded when you enable “Show edges”).

  3. You are using a data loading mode that doesn’t provide connectivities.

How to confirm#

  • Look for an edges/graph toggle (e.g., “Show edges”) and enable it.

  • If there is an edges overlay, confirm you can see edges.

  • If you cannot enable edges, assume connectivities are missing.

  • If the line under the Tool buttons instead reads “That click did not land on a cell…”, the graph is not the problem: your Alt+click missed every point. Zoom in and seed the drag again.

Fix#

  • Write your dataset again including connectivities (obsp['connectivities']), if you control how it is written.

  • Use lasso/proximity/annotation-based selection if you cannot load a graph.

Prevention#

  • For KNN workflows, treat “connectivities present” as a prerequisite and document it explicitly.

Symptom: “Annotation selection selects nothing / too many / too few cells”#

Likely causes (ordered)#

  1. No panel on screen is colored by a field, so the tool has nothing to read. The panel says so in place of the usual invitation, and a press selects nothing.

  2. Filters are hiding part of the category/range (selection only considers visible cells).

  3. You are selecting on a different field than you think. In a grid of views the gesture reads the field of the panel you press, not the focused view’s.

  4. The field has missing values or extreme distribution (continuous).

  5. You expected “Alt = intersect” but on categorical fields it behaves like “replace”.

How to confirm#

  • Confirm the field of the view you click in (its legend; focus that view to see it in the field selector).

  • Temporarily disable filters and repeat the selection.

  • Try a known categorical field with obvious labels (e.g., cell_type) to validate semantics.

  • If nothing at all is selected, read the line under the Tool buttons and the first line of the Selection (i). Three states are reported and they mean different things:

    • “Color by a field first…” (in the (i)) replaces the usual Alt+click line whenever no panel on screen is colored by a field. No press can select anything in that state, so there is nothing to debug beyond choosing a field.

    • “That panel is not colored by a field…” means the panel you pressed has no field, though another panel on screen does. Press in that one, or color this one.

    • “That cell has no value on that panel’s field, so there is nothing to select.” means the field is fine but the cell you clicked is missing a value on it. Click a different cell.

Fix#

  • If the panel is asking for a field, choose a Categorical obs or Continuous obs entry under Coloring & filtering; Alt+click works from that moment on.

  • For categorical:

    • use Alt to replace,

    • Shift+Alt to add,

    • Ctrl/Cmd+Alt to subtract.

  • For continuous:

    • use Alt+drag to tune the range,

    • intersect with lasso/proximity if you need geometry constraints.

Prevention#

  • Don’t do annotation-based selection while actively changing color-by/fields; treat the active field as part of the selection “spec”.

Symptom: “Undo/redo/confirm buttons are disabled or missing”#

Likely causes (ordered)#

  1. There is no in-progress candidate set (you haven’t completed a selection step yet).

  2. You changed tools/pages and cleared the UI state (candidate set may or may not still exist).

  3. Candidate set is empty after subtracting everything.

How to confirm#

  • Perform one fresh selection step (e.g., a small lasso) and see whether step controls appear.

  • If step controls appear but Confirm is disabled, you likely have an empty candidate set.

  • Undo is enabled immediately after the first step: the empty state before that step is recorded like any other, so one undo takes you back to it. A greyed-out Undo right after a gesture landed means the gesture produced no step — read the message line to find out why.

Fix#

  • Build a non-empty candidate set, then Confirm.

  • If you got into a weird state, click Cancel and start a fresh selection.

  • Escape does the same thing as Cancel for whichever tool is active. It is only consumed when a selection is actually in progress, so it still closes a dialog or leaves a text field alone when there is nothing to abandon. The Cancel button’s tooltip advertises it.

Prevention#

  • Confirm or cancel before switching pages.

  • Save sessions if you need “checkpointing”.

Symptom: “Selection is delayed / laggy”#

Likely causes (ordered)#

  1. You are selecting on a very large dataset (CPU-heavy selection preview).

  2. You are in multi-view with many panels (more rendering/overhead).

  3. You have huge highlight groups already; toggling/recomputing is expensive.

  4. Browser/GPU constraints (integrated GPU, low memory, heavy background tabs).

How to confirm#

  • Does lag correlate with dragging (lasso/proximity/KNN preview) rather than simple clicks?

  • Does lag disappear if you disable filters and reduce to one view panel?

  • Does lag correlate with enabling/disabling groups?

Fix (safe first)#

  1. Reduce the visible set with filters (counterintuitive but effective): fewer visible cells → fewer selectable candidates.

  2. Use fewer snapshot panels (temporarily).

  3. Prefer tools that do less repeated preview scanning:

    • use shorter gestures,

    • confirm sooner,

    • avoid long “slow drags”.

  4. Reload the page and restore a session if needed.

Prevention#

  • For very large datasets, plan for performance:

    • avoid “live preview while dragging for 10 seconds” workflows,

    • keep highlight groups coarse and few,

    • save sessions at milestones.

Symptom: “Highlights disappear when switching views/pages (or after reload)”#

Likely causes (ordered)#

  1. You switched highlight pages (different groups).

  2. You are looking at a snapshot view with different filters (highlights exist but are not visible there).

  3. You reloaded without restoring a session (highlights are not auto-persisted in URLs).

  4. You restored a session on the wrong dataset and the complete operation was rejected.

How to confirm#

  • Check the active page tab and group list.

  • Check whether the highlight count says “X of Y visible”.

  • If you restored a session, check whether it reached terminal Session fully restored.

Fix#

  • Switch to the intended highlight page.

  • Disable/relax filters in the view you are looking at.

  • Restore the correct session on the correct dataset.

Prevention#

  • Treat highlights as part of the session artifact: save sessions intentionally.

  • Use clear page names and avoid “Page 1 / Page 2” once you have real work.

Symptom: “My highlights didn’t restore from a session”#

Likely causes (ordered)#

  1. Dataset identity or exact-format validation rejected and rolled back the complete restore.

  2. Session progress is still active; lazy highlight memberships are inside the same awaited operation.

  3. The exact current session was saved without those highlights.

How to confirm#

  • Require terminal Session fully restored, not merely an eager visual change.

  • If progress remains active, let it finish or press Cancel.

  • Read any identity, format, or chunk error; no partial result is committed.

Fix#

  • Load the session on the dataset it was created from.

  • Write a fresh session file with Share… if exact-format validation fails.

  • To redo the work on a changed dataset, replay the old file’s steps by name (Load… › Replay a session file here…); steps that name cells by position are flagged, not applied.

  • If you must change the dataset, you must recreate highlights (indices won’t match).

Prevention#

  • Keep dataset IDs stable and avoid reordering cells between versions of a dataset if you rely on highlights.

  • Save “milestone sessions” before heavy editing.

Symptom: “Python highlight doesn’t show in the UI” (Jupyter integration)#

Likely causes (ordered)#

  1. The page is not a viewer opened by Python (no viewer channel active).

  2. The viewer channel is not open: Python no longer knows this viewer (it was stopped, or the kernel restarted), or — for a browser-tab viewer — a proxy between the page and the server does not pass WebSockets (/_cellucid/ws). The viewer shows a Viewer stopped or Viewer disconnected notification.

  3. Dataset/index mismatch (Python indices refer to different cells than the viewer).

How to confirm#

  • Confirm you are using the viewer workflow: a notebook widget (show_anndata), or a browser tab opened at the viewer’s own URL (viewer.viewer_url, with ?viewer=true&viewerId=…&viewerToken=… in its address).

  • Run viewer.debug_connection() in a new cell and check channel_connected.

  • Try a simple action and collect its answer (e.g., request = viewer.color_by(field=...), then request.result() in a later cell) to validate communication.

  • Follow the connection checks in Troubleshooting (hooks).

Fix#

  • Run the cell that shows the viewer again (or, for a browser tab, use the viewer URL the server printed), and make any proxy in between pass WebSockets.

  • Ensure the dataset order in Python matches the dataset loaded in the viewer.

Prevention#

  • When using Python control, treat “cell index = identity” and keep ordering stable.

  • Prefer a dataset file with a stable id (prepare(dataset_id=...)) for reproducibility.

When to file a bug report#

If you believe you hit a real bug (not one of the expected edge cases), include:

  • The exact text of the line under the Tool buttons at the moment it went wrong — or “no message at all”, which is itself a useful report

  • Browser + OS (and whether you’re on a laptop with integrated GPU)

  • Dataset format and rough size (n_cells, n_genes, whether connectivities exist)

  • Whether multi-view snapshots are enabled (and how many)

  • Exact selection tool used + exact modifier keys held

  • Whether filters were active

  • A minimal reproduction recipe (click-by-click)

  • Screenshots with callouts:

On this page