Your first project¶

This page opens a dataset and gets you to the point where selecting points in the scatter plot shows you neurons in the 3D viewer.

It assumes you have something to open. If you do not, use the example dataset — a public URL, nothing to build — and follow along with that. To make a project of your own, see create a local dataset.

1. Open a project¶

Start BigClust, then File → Open Project (Cmd+O / Ctrl+O).

In the dialog:

1. Type a path or URL into the box at the top, or press Browse… to pick a local folder. The dropdown remembers your last ten locations.
2. If the directory holds several projects, pick one under Select Project. Project Details below shows the info file's contents so you can confirm you have the right one.
3. Leave Filters and Embeddings alone for now.
4. Press Load.

You can skip the dialog entirely by naming the dataset on the command line:

uvx bigclust2@latest --from /path/to/my_clustering

uvx bigclust2@latest --from https://example.org/clusterings/hemibrain_v1.2

2. Find your way around¶

The window is two panes and a sidebar:

• The scatter plot on top is your embedding: one point per neuron, laid out in 2D.
• The 3D viewer below (or beside — see the layout buttons in the top-right of each pane) shows the actual morphology of whatever is selected.
• The control panel on the left has five tabs: General, Embeddings, Fidelity, Cluster, Settings. Press C over the scatter plot to show and hide it.

The annotated screenshot on the front page maps every region to its reference page.

Two keys are worth learning immediately:

3. Select some points¶

Selection is how you drive everything else in the app.

• Shift + drag draws a selection box.
• Shift + Ctrl + drag draws a freehand lasso.
• Hold Cmd as well to add to the existing selection rather than replace it.
• Esc clears the selection.

The status bar in the bottom-right keeps a running count — Selected: 2,604.

As soon as you select something, the 3D viewer starts fetching those neurons. For a big selection that takes a moment; the viewer says Loading 2,079 neurons while it works.

4. Look at one cluster properly¶

Now that you have a selection, the other widgets have something to work on. All four live under the View menu:

Each opens as its own window and follows the selection. See the widget reference for what every control in them does.

5. Colour by something meaningful¶

In the control panel's General tab:

• Color by picks a meta column to colour points by. Any column in your meta table is available, not just the ones named in info.
• Labels picks the column drawn as text over the plot. Double-click a label to highlight every point sharing it; shift + double-click to select them.
• Palette switches the colour map.

This is usually the fastest way to find out whether your embedding agrees with your existing annotations — colour by label and look for clusters that are not one colour.

Where to go next¶

If something is behaving oddly, the concepts pages explain the model the app is built on — particularly what "embedding" versus "distances" versus "features" means here, which is the single most common source of confusion.