Data Loading in the Web App (All Paths)#
These pages cover every current route into Cellucid: public samples,
files and folders from your computer, links, local or remote Python and R
servers, Jupyter, and published dataset catalogs. Every route opens the same
way: AnnData, or a file Cellucid presents as AnnData (a Seurat or
SingleCellExperiment .rds, Loom, 10x, MatrixMarket, MuData), read in the
browser as each view needs it.
They are written for mixed audiences:
Wet lab / non-technical: click-by-click, “what success looks like”, and safe defaults.
Computational users: formats, performance tradeoffs, parameter choices, and reproducibility.
Power users / developers: edge cases, failure modes, and how to debug loading issues.
Important
If you are not sure which method to use, start with Data Loading Overview (Every Route).
Note
Vector fields (velocity/drift overlays): if your dataset includes per-cell
vectors, Cellucid can draw them as an animated overlay after loading. Nothing
has to be switched on: however the file is opened — a browser picker, a drop,
a link, a catalog, cellucid serve, serve_anndata() or show_anndata() —
the browser discovers <field>_<basis> keys in obsm (velocity_umap for
X_umap, scVelo’s naming convention) and reads a field’s
vectors only when the overlay shows it.
See Vector Field / Velocity Overlay (GPU Particle Overlay) and File format expectations.
Fast Path (Choose Your Workflow)#
Use this as a decision tree. You can always switch later.
You have… |
Best first choice |
Why |
Next page |
|---|---|---|---|
A dataset you opened before in this browser |
My datasets under Open data |
One click opens it again, with the cells you chose for it |
|
A Zarr store folder ( |
Open… › Folder…, or drop the folder |
Read key by key from disk, nothing zipped or uploaded |
|
A |
Open… › File… (Loom, |
Read in place as it is, no conversion |
Open Loom and 10x Cell Ranger files or Multimodal data: MuData and the Modality select |
A Seurat or SingleCellExperiment object ( |
Open… › File… (R objects) or Folder… (MatrixMarket) |
Cannot be read in parts: read whole once into this browser’s storage and kept for next time, no R needed |
|
A portable |
Open… › File… |
One validated file selection in every supported browser |
|
A |
Open… › File… |
One file selection, nothing installed, nothing uploaded; read from disk as each view needs it |
|
A |
Server mode or Jupyter |
Python hands the file to the browser, which reads it in place as each view needs it |
Server Mode (CLI + Python) or Jupyter Integration (Notebook Embedding) |
A Zarr store folder on a remote machine |
Server mode or Jupyter |
Served key by key as it is on disk, nothing zipped or copied |
Server Mode (CLI + Python) or Jupyter Integration (Notebook Embedding) |
An in-memory |
Jupyter |
Fastest way to iterate while analyzing |
|
One dataset you want to share publicly, of any size |
A Zarr store folder on GitHub |
Free hosting, no file over GitHub’s 100 MB limit, no Git LFS quota; one link opens it |
|
A dataset collection you want to share publicly |
A dataset catalog on GitHub |
Exact shareable URLs, no running server |
|
A static host, CDN, or intranet server you control |
A dataset catalog on that host |
|
Interface reference#
Every loading path has its own label under Open data in the Session panel: Sample dataset, My datasets (once you have opened a dataset in this browser), File or folder and Link or server (Interface reference). Stored (once something is kept) sits below it, and under it two sections collapsed to one line each: Subsampling (how much is read: Cells to open, Genes read for) and Data mapping. The Dataset box at the top always describes the dataset currently open, whichever path opened it (The Dataset box). Sharing and loading a session file is in the sidebar’s State section, under Session (Share… and Load…; State and History).#
Note
The Session panel keeps every loading action and connection state visible;
Subsampling and Data mapping start collapsed, each saying what it holds in its
header (“100 % cells · genes 6 %”, “3 embeddings · UMAP 2D”), and remember
whether you opened them, in this browser only.
Its compact i buttons only open explanatory help: click one, or focus it with
Tab and press Enter or Space. Press Escape, click
elsewhere, or move focus outside to close it. See
UI glossary (terminology) and
Accessibility.
Changing your mind while a dataset loads#
Every dataset control is live while a dataset loads, including the dataset Cellucid opens when it starts. Whatever you choose last is what you get:
Choosing another sample, None, a dataset under My datasets, a file or folder with Open…, an address in the Link or server bar, or running the benchmark, stops the load in progress at once (its downloads are cancelled) and loads your new choice instead. The Dataset box shows a spinner and what is opening, for example Opening data.h5ad….
Connecting to a server or GitHub repository that holds exactly one dataset opens that dataset, unless you chose another dataset, or applied a session with Load… under State › Session, after clicking Open. Then what you did later stays and the connection is kept: its line under the bar still names it, with Disconnect.
A session file opened (Load… › Open a session file…) while a dataset loads waits for it, says so in a notification, and then applies the session to the dataset that loaded. A session saved from a different dataset is refused with an explanation, as always.
A load you replaced never appears afterwards and reports nothing; only the
outcome of your latest choice is reported. If the dataset Cellucid opens at
startup fails and you had not chosen anything else, Cellucid starts without
it: a panel over the empty viewer says the data could not be opened and why,
with the raw error under Details, Try again and Open without this
link. When asking again cannot change the answer (a file without an
embedding, a folder without datasets.json, a file that is not shared),
Open without this link comes first.
Dropping a file or folder onto the viewer#
Instead of a button, you can drag one file (.h5ad, .zarr.zip, .rds,
.rda/.RData, .loom, .h5, .h5mu), one .zarr store folder, one Cell
Ranger outs/ folder or one MatrixMarket folder from your file manager and
drop it anywhere on the viewer. While you drag, an outline and a Drop to open card cover the viewer.
A drop is read exactly as Open… › File… or Open… › Folder… would
read it, and it replaces any load in progress like any other choice. A
dropped folder’s files are asked for several at a time, as many as the
browser answers faster with, and in Chrome and Edge through the folder’s
handle, which those browsers list faster than its entries: measured on a
real drop in Chrome, a Zarr folder of 22,023 files is listed in 2.7 s
rather than 4.4 s; in Safari’s engine the listing takes about a quarter
less time than one file after another. A dropped file or folder is listed
under My datasets as a chosen one is, and in Chrome and Edge it opens
again from there with one click (Opening a file again).
Anything else is refused with a notification that says what can be dropped:
several items at once (drop the .zarr folder itself, not the files inside
it), any other file, or a folder that holds no Zarr metadata (.zgroup,
.zarray or zarr.json), no Cell Ranger matrix and no MatrixMarket matrix. A file
dropped onto the page never makes the browser leave Cellucid, including while
it is still starting; until the data controls are ready, the pointer shows the
drop as not allowed. The buttons remain the way to open data from the keyboard
or with a screen reader.
Getting Started#
Every route into Cellucid — the browser itself (a sample, a link, a file) or a Cellucid server — and how to choose between them.
Publish a folder of AnnData files with a datasets.json catalog on GitHub Pages or any static host, and share it with one link — no server.
Follow a complete five-dataset reference repository, validate its exact catalog contract, and publish stable dataset-specific links.
Open a file from Google Drive or OneDrive in place, and share unpublished data with a collaborator: one sign-in, nothing stored on a server.
Publish a dataset as a Zarr folder on GitHub (Pages or raw), with the measured speed of each host, GitHub’s limits, and Git LFS’s bandwidth trade-off.
Load the scVelo pancreas sample and verify its 1D/2D/3D embeddings, dimension-matched velocity, metadata, genes, connectivity, and provenance.
What to cite for each built-in sample, which one can be rebuilt and checked from its recipe, and what is recorded for the four that cannot.
Viewing Methods#
Load a file (.h5ad, .zarr.zip, .rds, .loom, 10x .h5, .h5mu) or a
folder (Zarr, Cell Ranger outs/, MatrixMarket) with Open…, or by
dropping it on the viewer.
Run a local HTTP server that hands an .h5ad or a Zarr store to the viewer, on your machine or over an SSH tunnel.
Visualize AnnData objects directly within Jupyter notebooks with embedded interactive widgets.
Concepts & Troubleshooting#
What makes a dataset “the same dataset” in Cellucid, and why it matters for sessions, sharing, and community annotation.
Choose which obsm array each dimension and each view
shows, and what happens when a file has no UMAP.
Open a Seurat or SingleCellExperiment .rds, an .rda of several objects, or a MatrixMarket count matrix folder.
Open a .loom, a Cell Ranger .h5 or its outs/ folder with Cell Ranger’s own UMAP and clusters.
Open an .h5mu or MuData Zarr and switch modality (RNA, protein) under Data mapping.
A GEO sample’s MatrixMarket files and a Seurat object on Zenodo by link, and a
Cell Ranger outs/ folder from disk.
Every format Cellucid reads and how, what uns['cellucid'] may say, and the datasets.json catalog contract.
Symptom → diagnosis → fix for file picker, server mode, links and catalogs, and common data issues.
Current loading controls, a successful direct H5AD load, and browser-engine acceptance captures.
If your dataset includes vector fields (e.g. RNA velocity), enable the overlay after loading and pick a field bound to the embedding the view shows.
Quick Comparison#
Method |
Best For |
Separate server command? |
|---|---|---|
Public sample |
Learning with known-good data |
No |
Browser file picker |
Local viewing without Python |
No |
GitHub catalog |
Public, dataset-specific share links |
No |
Self-hosted catalog |
A catalog on your own static host or CDN |
No — any HTTP server will do |
Server mode |
Data on a remote machine, or a Zarr store folder |
Yes — |
Jupyter |
Interactive analysis workflows |
No — the viewer is a notebook widget; no server, no port |
Note
Server mode binds to 127.0.0.1 by default; use the documented SSH-tunnel
workflow for a remote machine. Jupyter uses no server at all: the widget hands
the data to the viewer through the notebook’s own connection, so a remote
notebook needs nothing extra.