Data Loading in the Web App (All Paths)#

These pages cover the end-to-end ways to get data into Cellucid (pre-exported folders, browser file picker, server mode, and Jupyter).

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 (All 14 Options).

Note

Vector fields (velocity/drift overlays): if your dataset includes per-cell vectors, Cellucid can visualize them as an animated overlay after loading. You don’t need a special loading method—just make sure the vector field data is present and named correctly. See Vector Field / Velocity Overlay (GPU Particle Overlay) and Folder / file format expectations (high-level; link to spec).

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 pre-exported folder from prepare()

Browser folder picker

Fastest, most reliable, no server

03_browser_file_picker_tutorial

A .h5ad file

Server mode (recommended) or Jupyter

Lazy loading for large files, fewer browser memory issues

04_server_tutorial or 05_jupyter_tutorial

A .zarr directory

Server mode or Jupyter

Chunked storage works well with lazy loading

04_server_tutorial or 05_jupyter_tutorial

An in-memory AnnData in a notebook

Jupyter

Fastest way to iterate while analyzing

05_jupyter_tutorial

A dataset you want to share publicly

GitHub-hosted exports

Shareable URL, no server needed

02_local_demo_tutorial

Screenshot Placeholder (You Will Replace Later)#

Placeholder screenshot for the Dataset Connections panel.

Use Dataset Connections to load data from your computer, a server, or a public GitHub repo.#

Getting Started#

Loading Options Overview

Understand all 14 loading options and choose the best approach for your workflow: in-memory, h5ad, zarr, or pre-exported.

Data Loading Overview (All 14 Options)
Local Demo

Export once, then share via public GitHub-hosted exports (no server), or run a local demo viewer.

Local & Remote Demo (Share Without Running a Server)

Viewing Methods#

Browser File Picker

Load datasets directly from your file system using the browser’s native file picker API.

Browser File Picker (No Python Setup)
Server Mode

Run a local HTTP server for larger datasets with efficient lazy loading of gene expression.

Server Mode (CLI + Python) — Recommended for Large Datasets
Jupyter Integration

Visualize AnnData objects directly within Jupyter notebooks with embedded interactive widgets.

Jupyter Integration (Notebook Embedding)

Concepts & Troubleshooting#

Dataset Identity

What makes a dataset “the same dataset” in Cellucid, and why it matters for sessions, sharing, and community annotation.

Dataset identity (why it matters)
Format Expectations

What files/keys are required for exports, GitHub manifests, .h5ad, and .zarr.

Folder / file format expectations (high-level; link to spec)
Troubleshooting

Symptom → diagnosis → fix for file picker, server mode, GitHub exports, and common data issues.

Troubleshooting (data loading)
Screenshot Checklist

One place to capture all screenshots referenced in this section.

Screenshots
Vector Fields Overlay

If your dataset includes vector fields (e.g. RNA velocity), enable the overlay after loading and pick a field for the current dimension.

Vector Field / Velocity Overlay (GPU Particle Overlay)

Quick Comparison#

Method

Best For

Requires Server

Local Demo

Quick visualization, sharing static files

No

File Picker

Desktop viewing without setup

No

Server Mode

Large datasets, lazy gene loading

Yes

Jupyter

Interactive analysis workflows

No

Note

“Requires Server” here means “you run a small local Python process that serves data to the web viewer”. This is still typically local-only (e.g. 127.0.0.1) unless you explicitly bind to 0.0.0.0.

Tip

Adding more pages:

  • Add new pages into cellucid-python/docs/user_guide/web_app/b_data_loading/.

  • Use a numeric prefix like 10_... so they naturally sort.

  • This page includes them automatically via a globbed toctree.