Analysis UI overview#

Audience: everyone (wet lab + computational + power users)
Time: 15–25 minutes
What you’ll learn:

  • Where Analysis lives and what it depends on (highlight pages)

  • How the mode accordion behaves (open/close; one mode at a time)

  • How an analysis form is laid out (essentials, More options, Run)

  • Which modes auto-run and which wait for Run

  • How “Copy” creates floating analysis windows (what is copied vs recomputed)

  • Where exports live (CSV) and where plot options live (modal/expanded view)

Prerequisites:

  • A dataset loaded in the web app

  • At least one highlight page (recommended for nearly all modes)

Where Analysis lives (UI map)#

In the left sidebar, Analysis is a dedicated accordion section:

  • Sidebar → Analysis (directly below the Highlighting panel and its highlight pages).

Analysis is intentionally placed right after highlighting because:

  • you define groups with highlight pages, and

  • you analyze/compare those pages here.

If Analysis looks empty, the first thing to check is whether you have highlight pages: see Highlighting and Selection (Groups, Pages, Tools).

The Analysis mode accordion (how it behaves)#

Inside the Analysis section you’ll see the analyses in three groups:

  • Genes

    • Marker genes (the markers of every category of a field)

    • Differential expression (compare two groups of cells; volcano plot + gene table)

    • Dot plot (mean expression and % expressing of genes per group)

    • Gene signature (score gene sets across selected pages)

  • Cells

    • Composition (cell-type proportions across samples and conditions)

  • Explore

    • Quick (automatic composition + stats summaries)

    • Detailed (choose a variable + plot type + options)

    • Correlation (choose X and Y variables; scatter plot + stats)

The Analysis panel with every analysis collapsed, in three groups: Genes (Marker genes, Differential expression, Dot plot, Gene signature), Cells (Composition) and Explore (Quick, Detailed, Correlation); each row carries a chevron, an (i) and a copy-window button.

Every analysis, collapsed. Each row shows its name, an (i) that says what it does, a copy button that opens it in a floating window, and a chevron that opens it in place.#

Accordion behavior:

  • Only one mode can be open at a time.

  • Clicking an already-open mode closes it.

  • Closing the mode hides results in the sidebar; reopening triggers a refresh if inputs changed.

Auto-run vs “Run” button (important)#

Quick and Detailed recompute as soon as their inputs are valid: selecting pages or a variable, changing plot options, or editing a page’s cells.

Every other analysis — Marker genes, Differential expression, Dot plot, Gene signature, Composition and Correlation — is a form that ends in Run, and nothing is computed until you press it.

The Detailed panel holding a finished result — Variable set to Categorical obs then cell_type, two pages selected, Bar Plot chosen and a grouped bar plot drawn beneath — with no Run button anywhere in the panel.

Auto-run (Detailed). The result sits directly under the controls. Change a control and it redraws.#

The Differential expression form before a run: Compare set to Pages, Group A Page 1 and Group B Rest of Page 1, the Swap A and B link, More options collapsed, and the Run button under the pointer; no result yet.

Run (Differential expression). Nothing is computed until the button is pressed.#

The analysis form#

Every analysis with Run lays its form out the same way, so it stays short however many options it has:

  1. Essentials — the two or three choices that define the analysis (Group by, Group A and Group B, the gene sets), each with its (i). A mode that compares pages shows its page selector here too.

  2. More options — one collapsed disclosure holding a collapsed group per topic (Cells, Test, Filters, Display, …). Each header counts the options changed from their defaults (2 changed), and Reset to defaults puts them back. An option that does not apply (the reference group while comparing against the rest) is hidden.

  3. Run — with a muted line above it when the analysis cannot run, saying why (Choose two pages, Add genes to a set). Run is disabled until then.

Every default is stated in a Defaults table on the mode’s page. Which groups you left open is remembered with the session.

After a run. Changing an option that would change the numbers leaves the result in place, dimmed, with a Stale · Run chip: press it (or Run) to run again. Options that only change what is shown — the filters and labels of a volcano, the ranking and number of markers, a signature’s plot and rescaling — redraw the result at once, without computing again. Changing pages or page contents marks a result stale the same way.

Running, cancelling and running again#

Every analysis that reads genes or computes for more than a moment runs as one job you can stop: Differential expression, Marker genes, Dot plot, Composition, Correlation, Gene signature, Quick and Detailed (a gene’s values, a box, violin, histogram or density plot).

While it runs. Run reads Running…, and a box under the form (in Quick Insights and Detailed, where the result appears) shows, once the job has run for a quarter of a second:

  • the mode’s name and, when it is known, what the run covers (3,753 genes in Alpha (1,234 cells) vs Beta (5,678 cells));

  • what it is doing: the step (Preparing groups, Testing genes, Correcting for multiple testing, Reading genes, Scoring cells, Computing the correlation, Reading <variable>, Drawing the result), how many genes are done of how many, how much it has read and how fast, and how long is left;

  • a progress bar, and Cancel.

A job that takes longer than a second also shows one progress notification with the same line and its own Cancel button. It is the run’s only notification: the gene reads it makes are not announced again by the general read notifications – neither is a gene a view started reading before the run needed it too, which the run takes as its own read from then on – and it closes with the outcome (Differential expression: 412 significant genes).

First answer on a sample. Differential expression, Marker genes, Gene signature, Correlation, Composition, Dot plot, Detailed and Quick Insights can answer twice: a first pass on a uniform random sample of the open cells, then the same run on every cell, whose result replaces the first in place. The sample is the first cells of the open cells’ priority order (the same cells the coarsest levels of detail draw; Performance considerations (what gets slow and why)), and each page or group is taken as its cells in it, so the first pass is an unbiased preview of the final answer. A line under the progress box says which cells the shown result used: First pass: each group's cells in a uniform sample of 4.2% of the open cells (about 420,000 of 10,000,000) · refining on every cell…, then Every cell: computed on all cells of its groups (10,000,000 open cells). When genes are read for a sample of the open cells (below), the line never says every cell: a result on every cell genes are read for has no such line (the gene sample’s own line says it), and a first pass says … · refining on the cells genes are read for…. The final result is exactly what a single run on every cell gives, bit for bit; it is the one saved in sessions and exported.

A first pass is taken only when it pays, judged from what earlier runs of the same analysis measured on this device. With nothing measured yet, when the whole run is predicted to take under a second, or when a first pass would not answer at least twice as soon (most of the time goes to work a sample does not shorten), the analysis runs once. Reading genes shortens with the sample where the file allows: the sample is the first cells, so an analysis that reads its groups’ cells (Differential expression, Marker genes) reads only those cells’ part of each gene from a file Cellucid wrote (each gene’s values are stored by priority order, so the sample’s are the first ones) and from a matrix stored cell by cell whose index is built in parts (only the parts the sample’s cells lie in); the final pass then reads the rest. Otherwise the first pass takes as many cells as fit in about a second, and never fewer than the square root of the number of open cells. A first pass the sample cannot carry (a group with fewer than two of its cells in the sample) is skipped. The measurements are kept in this browser (they are a convenience, never needed).

Genes on a sample of the open cells. A large dataset stored cell by cell opens every cell on the map and reads a gene for a sample of them, the first cells of their order (Genes on a sample of the cells); the other cells have no gene value yet, which is not 0. An analysis that reads genes (Differential expression, Marker genes, Gene signature, Dot plot, and Detailed or Correlation on a gene) then computes on each group’s cells among that sample, and one warning line under the result says so in compact counts that fit the narrowest panel (Genes read for 3.8K of 2.3M cells; under a subsample’s own chip when a subsample is open). Its (i) holds the exact words: the counts, how many of its groups’ cells that is and each group’s share (Genes are read for 3,769 of the 2,282,447 open cells … 3,769 of its groups’ 2,282,447 cells). The line is a link: it opens Session › Subsampling at Genes read for and puts the focus on its slider, the one place that changes how many cells genes are read for (there is no size control inside an analysis). A group with fewer than two cells among the sample is named with how many it has. Marker genes counts each group among the sample: a group with fewer than Min cells per group of its cells there is skipped, and the chip says why (15 skipped: too few sampled cells, each group’s cells among the sample of its cells in its tooltip). Per-cell gene scores have no value on the other cells, and the gene means a module score bins and a z-score divides by are over the sample’s cells. Genes read for reads genes for more cells (up to every open cell, Genes read for); results that read genes are then marked Stale · Run, and run again use the cells now read; a Detailed view of a gene draws itself again on them.

Cancel. Cancelling stops the job where it is: its gene reads stop in the file reader (a remote file stops downloading), and its computations stop in the analysis workers (a worker still busy a quarter of a second after the cancel is replaced by a fresh one, so nothing keeps running for a cancelled job). Nothing of the cancelled pass is kept: no partial result is shown, cached or exported. A first pass already on screen stays, and its line says so: … Stopped before every cell; run again for all of them.; it is not saved in sessions or exported as the analysis’s result. A read that something else also waits for, the gene the embedding is coloured by, or the same gene another analysis window reads, goes on for it.

The same happens, without asking, when you close the analysis window or switch to another dataset. Changing an option while a run goes does not stop it: the result arrives and is marked Stale · Run if the form no longer matches it. So is a result when the open cells change (a larger or smaller share applied in place, a large dataset’s progressive opening growing; Subsampled loading: open a share of the cells): the window stays, the chip’s tooltip says the open cells changed (with the counts then and now), and Run computes on the cells open now. A run under way when the cells are to change finishes first, on the cells it started on (the change waits for it), and its result is then marked stale; a run started while they change starts on the new cells. A stale result is never passed on as current: it is not saved in a session, its exports (CSV, PNG, SVG, GMT) are refused with a note saying why, and its scores and gene sets are withdrawn from what a notebook reads until it is run again.

After a cancel the box reads <mode> cancelled and Cancelled after 12 s. 1,240 of 3,753 genes were done. Nothing was kept., with Run again. A cancel is never reported as an error. Run again runs the form as it stands.

When a run fails the box reads <mode> failed with the reason, again with Run again, and the notification says the same once.

Page selection UI (“Compare pages”)#

Most modes include a page selector labeled Compare pages.

What you can do there:

  • click tabs to select which pages are included,

  • see per-page cell counts,

  • customize page colors (used consistently in plots),

  • select all/deselect all quickly.

Some modes also show derived pages:

  • Rest of <page> (the complement of a page across the full dataset).

The page chips of the Detailed panel: Page 1 with its colour swatch and the count 262, and Rest of Page 1 with its own swatch and count, both selected, with the pointer on Rest of Page 1.

Rest of Page 1 is the derived complement — every cell not in Page 1. You do not create it; it appears next to each base page with its own count and colour, which is what makes a two-group comparison possible from a single selection.#

Tip

When a plot “doesn’t match what you expect”, the most common cause is selecting the wrong pages. Always confirm which pages are selected in the mode you’re currently using.

Variable selection UI (obs vs genes)#

Detailed mode#

Detailed uses a two-step variable selector:

  1. choose the type: Categorical obs / Continuous obs / Gene expression

  2. choose the specific variable (field key or gene)

If gene expression is not available in the dataset, the selector will show an explicit “No gene expression data available” message.

The gene list is the same windowed list as the sidebar’s gene search (see Field selector UX): it lists None and every matching gene, opens with the chosen gene highlighted, and only builds the rows near what is shown. ↓ / ↑ move the highlight and wrap at either end, Home and End jump to the first and the last entry, Enter chooses the highlighted entry and Esc closes the list.

A gene that stays under the pointer, or highlighted with the arrow keys, in the gene list for 150 ms starts loading in the background, so choosing it usually needs no wait. Moving on cancels that load, and choosing the gene uses it.

Correlation mode#

Correlation’s X axis and Y axis use the same picker (continuous obs or gene). Method (Pearson or Spearman) and Colour by are under More options.

“Copy” (floating analysis windows)#

Each analysis accordion item has a small Copy control.

Copy creates a floating analysis window so you can:

  • keep one result visible while exploring another mode, or

  • run the same mode with different settings side-by-side.

The whole Cellucid window with the Correlation analysis copied into a floating window over the point cloud: its own header with copy, maximise, close and collapse buttons, and its own copy of the Correlation form.

Copy undocks a mode into a floating window that sits over the viewer. It has its own header, its own copy and close buttons, and its own independent copy of the form — so you can keep one configuration on screen while changing another.#

Important behavior:

  • Settings are copied. Results are not copied.
    The copied window recomputes from current data/pages.

  • Floating windows have their own UI instance, so they can be configured independently.

Moving, resizing and maximizing a window#

  • Move: drag the header (mouse, pen or finger), or press Alt + an arrow key on the header or an edge (16 px; 64 px with Shift).

  • Resize: drag any of the four edges or four corners. The edges are thin until the pointer reaches them, then show an accent line; the bottom-right corner always shows a grip. A size readout (640 × 480) shows while you drag. Near another window’s edge, the sidebar, the middle of the free area, the screen edges or the height of the content, the edge snaps and a thin guide line shows where.

  • Fit: double-click the top or bottom edge to fit the height to the content; double-click a side edge to return to the width the window opened at.

  • Maximize: the □ button in the header, or a double-click on the header, fills the free area beside the sidebar; the same again restores the size.

  • Keyboard: once focus is inside a window, Tab also reaches its edges and corners. The arrow keys move the focused edge (16 px; 64 px with Shift), Home and End go to the least and the largest size, and a screen reader reads the size on each key.

A window is at least as wide as the sidebar’s least width and as tall as its header and first row; the only largest size is the screen. A new window of an analysis opens at the size you last gave one; the sizes are saved in the session and forgotten when another dataset opens.

On a phone#

On a screen 720 px wide or less, analysis windows are bottom sheets: full width, at 40%, 75% or all of the screen. While the panel is closed, a sheet stands on the panel’s bar at the foot of the screen, no taller than the screen above it, so the bar always opens the panel; every other window is kept above the bar too. Drag the grip above the header to change the height (it settles on the nearest of the three), tap the grip to step through them, or use the arrow keys on it. A tap on the header collapses the sheet to its header. One sheet shows at a time; with several open, a tab strip above the sheet names them and brings one to the front. Turning the phone or widening the window gives every window back its own place and size.

Sessions (what restores)#

If you save/restore a session:

  • the docked panel reopens the mode that was open, with every mode’s settings and which of its More options groups were open,

  • floating analysis windows reopen with their settings and their place, size and open or collapsed state (which window is in front is not saved: a click raises a window), and new windows and expanded views keep the sizes remembered for each analysis,

  • the shown results of Differential expression, Marker genes, Gene signature, Correlation, Dot plot and Composition are saved and restored as they were, without recomputing; Quick and Detailed recompute from their settings,

  • a saved result that names a gene, field or category the open dataset lacks is refused rather than shown against different data,

  • gene-expression caches are not saved; genes are read again when needed.

See Session Saving, Restoring, and Sharing for session semantics.

Next steps#