FAQ (viewing)#

Do I need to run prepare()?#

No, but it’s often the best choice.

  • Use AnnData mode (show_anndata, serve_anndata) when you want convenience in analysis workflows.

  • Use export mode (prepare → show/serve) when you want speed, reproducibility, and easy sharing.

See:

What’s the difference between serve and show?#

  • serve(...) / cellucid serve ...: starts a server and you use the viewer in a normal browser tab.

  • show(...): starts a server and embeds the viewer in a notebook output cell (iframe).

Does Cellucid upload my data to cellucid.com?#

In the recommended workflows (server/notebook modes), your data is served by your local Python server and loaded by your browser from that server.

The Python server may download the viewer UI assets from https://www.cellucid.com (and cache them locally), but that is UI code, not your dataset.

Security details: Security, privacy, CORS, and networking.

Can I use Cellucid offline?#

Not for a startup that serves the viewer UI. cellucid serve, show(...), and show_anndata(...) establish the configured exact web generation at each startup and report source failure instead of substituting a cached generation.

cellucid serve ... --no-web-ui is the explicit data-endpoint-only mode and does not fetch viewer assets.

Cache details: Server mode (advanced).

What happens if port 8765 is already in use?#

serve(...), serve_anndata(...), and cellucid serve bind the requested port exactly and report an error if it is unavailable. Pass port=0 or --port 0 to request one operating-system-assigned port.

Always use the printed Viewer URL.

Why is a remote notebook iframe blank or unreachable?#

Usually because:

  • the notebook is served over HTTPS, and/or

  • the kernel/server is remote (JupyterHub/cloud), so 127.0.0.1 is not reachable from your browser.

Fix: expose the Cellucid port through an HTTPS proxy (for example Jupyter Server Proxy) and pass that exact browser base as client_server_url=.

Details: Notebook / widget mode (advanced).

Should I use .h5ad or .zarr for large datasets?#

Both can work well in Python server mode:

  • .h5ad is opened read-only-backed and is the lower-memory direct mode.

  • .zarr is materialized eagerly by anndata.read_zarr; use it only when the complete AnnData fits in Python memory. Browser gene requests are still served on demand after that eager load.

If you’re repeatedly viewing or sharing, exports are usually best.

Performance guide: Performance, scaling, and lazy loading.

Is there an R package?#

Yes. cellucid-r prepares Seurat, SingleCellExperiment, matrices, and data frames as Cellucid export folders. Open those folders in the web app or host them as static files. Server processes, notebook embedding, and programmatic viewer control are provided by the Python package.

See R Package Guide.

Where do I learn the web app UI (filters, analysis, figure export)?#

Those are documented in the web app user guide: