Appearance
Brush Selection
Core Feature
This feature is available in all Portrai Explorer deployments.
The brush paints a region of interest onto the map instead of enclosing it in a single outline. Painting accumulates, the eraser takes parts back out, and every edit can be undone, so a region can be refined without starting over.
Choosing the Brush
The mode switcher at the bottom-center of the map viewer holds four tools:
| Tool | Shortcut | What it does |
|---|---|---|
| Pan | V | Drag to move the map |
| Lasso | S | Draw one closed outline (see Lasso Selection) |
| Brush | B | Paint cells into the selection |
| Eraser | E | Paint cells out of the selection |
Press Esc to return to Pan. While a brush or eraser stroke is in progress, the first Esc only abandons that stroke and keeps the tool. Holding Space pans temporarily without changing the selected tool.
These shortcuts, and the radius and undo shortcuts below, do not work while you type in a text field (the radius box included) or while a dialog, a menu or a popover such as the Subset Panel is open.
Brush and Eraser are unavailable while the facet view is open; entering it returns the map to Pan.
Painting
- Select Brush and drag across the tissue. Cells under the stroke join the selection as you paint.
- Release and drag again to add more. Strokes accumulate; they do not replace one another.
- Click without dragging to drop a single circle.
The painted fill follows the pointer. The selected points and the item count in the mode switcher update several times a second while you paint. Other views update once you release: scatter plots right away, the Detail Panel and the other plots within about half a second. While you paint stroke after stroke, the other plots wait until you pause (see Subsets Narrow, Selections Mark).
A stroke is abandoned instead of committed if you press Esc, switch to Pan or Lasso, change projection, or the window loses focus while the pointer is down.
A brush drag that pans the map instead of painting means the brush could not start a stroke: the projection's embedding is still loading, the Eraser has no selection to take from, or the region is full (see Limits).
Very large datasets
In very large datasets, upwards of about 33 million points, the selected cells and the item count may not update while you paint. Keep painting: the painted fill still follows your pointer, and the selection catches up when you release.
Brush size
The radius is measured in screen pixels, so it stays the same size under the cursor at every zoom level and covers less tissue as you zoom in, which is what you want when tracing a boundary.
- Drag the slider or type a value in the brush options (2 to 200 px, 20 px by default)
[and]step the radius by a factor of 1.2 (about 20% larger, 17% smaller)Shift+ scroll wheel does the same
The size is remembered between sessions.
Each stroke keeps the size it started with. Zooming mid-stroke does not change the stroke already being painted.
Erasing
Select Eraser and drag over the part to remove, or hold Alt (Option on macOS) while brushing. Alt is read when the stroke starts and holds for the whole stroke, so releasing the key mid-drag does not switch it back.
Holding Alt with the Eraser selected inverts it the other way and adds.
With nothing selected there is nothing to erase: the cursor circle turns into a thin grey dashed outline, and dragging pans the map instead of painting.
Refining a lasso
A lasso can be handed to the brush. Draw the rough region with the Lasso, switch to Brush or Eraser, and paint: the outline becomes a filled region whose first element is the lasso polygon, and the lasso itself is cleared.
The reverse does not hold. Drawing a new lasso while a brush region exists replaces the region, because the map shows one selection at a time.
Cursor and fill
| State | Cursor circle | Fill |
|---|---|---|
| Brush | Solid blue, 2 px | Translucent blue |
Brush + Alt | Solid blue, 2 px | Removed from fill |
| Eraser | Dashed red, 2 px | Removed from fill |
Eraser + Alt | Dashed red, 2 px | Translucent blue |
| Eraser, nothing selected | Dashed grey, 1 px | None |
The circle follows the selected tool, not Alt, so an inverted stroke looks like an ordinary one while the fill it leaves behind is the opposite.
What the map shows
While a region is being painted, and after it is finished, the points it selects are drawn at full strength and the rest of the visible points are dimmed behind them: same color, lower opacity. The dimmed points are context, not leftovers, and they stay hoverable: the tooltip still reports what is under the pointer.
Hovering a category or a histogram bar in the Detail Panel is a short-lived exception. For as long as the pointer rests on it, the map shows only the highlighted points that are also selected, and the dimmed layer is hidden until you move off.
Dimming is how a selection reads. Hiding is how a filter reads. Points removed by a Subset condition or by a cutoff are gone from the map; points the brush simply has not reached are dimmed. Adding the region to a subset therefore changes what you see: see Adding the region to a subset.
Very large datasets colored by a continuous feature or a Signature score are the exception: there the map draws a blended picture, and the cells the region leaves out disappear instead of dimming. See Very Large Datasets.
Undo and redo
| Action | Shortcut |
|---|---|
| Undo | Ctrl/Cmd + Z |
| Redo | Ctrl/Cmd + Shift + Z |
The brush options also carry Undo, Redo and Clear buttons.
Undo steps back through the edits one at a time and the selection is re-evaluated from the remaining ones. Painting a new stroke after undoing drops whatever was ahead of the cursor, as in any editor.
Adding the region to a subset clears the region and its history. Clear brush selection (the trash button in the brush options) and the Clear ✕ on the Subset Panel banner discard the region and its history without adding it, and cannot be undone. Drawing a new lasso on the map does the same.
Adding the region to a subset
Open the Items dropdown in the mode switcher and choose Add selection to subset, or use the Add to subset button on the Subset Panel banner. The region is stored as a Brush condition in the first condition group, named after the projection it was painted on (for example Spatial Brush A3F2).
Brush conditions combine with AND/OR like any other condition and can be renamed from the Subset Panel.
InSilicoLab Feature
In InSilicoLab, a Brush condition can define a DEG comparison group: save the subset that holds it as a saved subset, then bring it into the group with Apply Saved Subset (see DEG Analysis - Using Saved Subsets).
Expect the map to change when the region is added. Up to that point the region was a selection, so the points outside it were dimmed; as a condition it is a filter, so they are hidden. The painted region disappears from the map with them: every point still on screen is inside it, so drawing its shape over all of them would add nothing. The condition card in the Subset Panel is where an applied region is listed from then on.
The condition card shows its source projection and how many strokes and polygons it holds.
Editing a saved region
The pencil button on a Brush condition card puts the region back on the map and selects the Brush, so it can be painted on again. It is available only while the projection the region was painted on is the one on screen, and while no other brush selection is pending. When it is unavailable, its tooltip says why: "Finish the current brush selection first", or "Switch to UMAP to edit" (naming the region's projection). A region undone back to nothing still counts as pending: clear it with Clear brush selection first.
Reopening removes the condition
Confirming the reopen deletes the Brush condition from the subset, so the map and the subset never hold two copies that drift apart. The region returns to the subset only when you add it back. Switch projection before you do and both are gone.
Limits
A brush region is stored inside the subset, and saved subsets live in browser storage, so a region cannot grow without bound:
- 1,000 edit elements per region
- About 40 KB of painted geometry before a new stroke is refused, and a 50 KB hard limit when the region becomes a condition
Each limit is reported with a notification, and the remedy differs:
- The 1,000-element limit (Brush limit reached) and the 40 KB limit (Brush region is full) refuse a new stroke: the drag pans the map instead. Add the region to a subset, which empties it, and keep painting. The next region you add becomes a second Brush condition joined to the first by AND, so set the operator between them to OR to keep both areas. Until you do, points outside the first region stay hidden, because it is already a filter.
- The 50 KB limit (Brush region is too large to save) refuses the add itself. The region stays on the map, so undo a few edits and add it again.
Projections
The brush works on every projection: Spatial, UMAP, t-SNE and any other embedding. A region belongs to the projection it was painted on, so switching projections clears it and posts a notification titled Brush selection cleared. Switching to another extension and back returns the map to the default projection, which clears a region painted on any other projection the same way. Add the region to a subset first to keep it: a Brush condition keeps selecting by the projection it was painted on, whichever projection is shown.
A page reload discards a region that has not been added, and also the active subset, Brush conditions included. To keep a Brush condition across reloads, store its subset as a saved subset.
Notes
- The brush is a map tool. Scatter plots keep Pan and Lasso only.
- Painting does not need the pointer to stay over the map; a stroke continues if you drag past the edge and finishes when you release.
Related Topics
- Lasso Selection - Drawing a single outline
- Subset - Combining brush regions with other conditions
- Saved Subsets - Storing and reloading subsets
- Map Viewer - The mode switcher the tools live in