Skip to content

Commit 56187f0

Browse files
inecikinecik
committed
onboarding & debugging
1 parent 25b1cf3 commit 56187f0

File tree

10 files changed

+424
-123
lines changed

10 files changed

+424
-123
lines changed

‎README.md‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -127,25 +127,21 @@ Cellucid supports 6 deployment modes, each with support for pre-exported binary
127127
| Mode | Best For | Command/Function |
128128
|------|----------|------------------|
129129
| **Jupyter** | Interactive analysis | `show_anndata(adata)` |
130-
| **Local server** | Development | `cellucid serve ./export` |
131-
| **Remote + SSH** | Team access | `cellucid serve-anndata data.h5ad` |
130+
| **Local server** | Development | `cellucid serve ./data` |
131+
| **Remote + SSH** | Team access | `cellucid serve data.h5ad` |
132132
| **Browser** | Quick preview | [cellucid.com](https://cellucid.com) file picker |
133133
| **Static hosting** | Public sharing | GitHub Pages |
134134

135135
### CLI Commands
136136

137137
```bash
138-
# Serve h5ad file directly (lazy loading, no export needed)
139-
cellucid serve-anndata /path/to/data.h5ad
140-
141-
# Serve zarr store directly (lazy loading, no export needed)
142-
cellucid serve-anndata /path/to/data.zarr
143-
144-
# Serve pre-exported data (fastest)
145-
cellucid serve /path/to/export
138+
# Serve any data - format auto-detected
139+
cellucid serve /path/to/data.h5ad # h5ad file
140+
cellucid serve /path/to/data.zarr # zarr store
141+
cellucid serve /path/to/export # pre-exported data
146142

147143
# With options
148-
cellucid serve-anndata data.h5ad --port 9000 --no-browser
144+
cellucid serve data.h5ad --port 9000 --no-browser
149145

150146
# Show version
151147
cellucid --version
@@ -155,7 +151,7 @@ cellucid --version
155151

156152
```bash
157153
# On remote server
158-
cellucid serve-anndata /data/cells.h5ad --no-browser
154+
cellucid serve /data/cells.h5ad --no-browser
159155

160156
# On local machine (SSH tunnel)
161157
ssh -L 8765:localhost:8765 user@server

‎docs/api/server.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,36 @@ Functions and classes for running a local HTTP visualization server.
88

99
---
1010

11+
## CLI Command
12+
13+
The unified `cellucid serve` command auto-detects the data format:
14+
15+
```bash
16+
# Serve any data - format auto-detected
17+
cellucid serve /path/to/data.h5ad # h5ad file
18+
cellucid serve /path/to/data.zarr # zarr store
19+
cellucid serve /path/to/export # pre-exported data
20+
21+
# With options
22+
cellucid serve data.h5ad --port 9000 --no-browser
23+
24+
# Show help
25+
cellucid serve --help
26+
```
27+
28+
### CLI Options
29+
30+
| Option | Description | Default |
31+
|--------|-------------|---------|
32+
| `--port, -p` | Port to serve on | 8765 |
33+
| `--host, -H` | Host to bind to | 127.0.0.1 |
34+
| `--no-browser` | Don't auto-open browser | False |
35+
| `--quiet, -q` | Suppress info messages | False |
36+
| `--no-backed` | Load entire file into memory (h5ad/zarr) | False |
37+
| `--latent-key` | Key in obsm for latent space | Auto-detected |
38+
39+
---
40+
1141
## Functions
1242

1343
### serve_anndata

‎docs/user_guide/01_loading_options_overview.ipynb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
{
44
"cell_type": "markdown",
55
"metadata": {},
6-
"source": "# Cellucid Loading Options Overview\n\nThis notebook provides a comprehensive overview of all 14 data loading options in Cellucid.\n\n## The 14 Loading Options\n\nCellucid supports 6 deployment modes, each with support for pre-exported binary data, h5ad files, and zarr stores:\n\n| # | Method | Exported | h5ad | zarr | Python | Lazy Load | Performance |\n|---|--------|----------|------|------|--------|-----------|-------------|\n| 1 | Local Demo (GitHub) | ✅ | - | - | No* | Yes | Best |\n| 2 | Remote Demo (GitHub) | ✅ | - | - | No* | Yes | Best |\n| 3 | Browser File Picker | ✅ | - | - | No | Yes | Best |\n| 4 | Browser File Picker | - | ✅ | - | No | **No** | Slower |\n| 5 | Browser File Picker | - | - | ✅ | No | **No** | Slower |\n| 6 | Server CLI | ✅ | - | - | Yes | Yes | Best |\n| 7 | Server CLI | - | ✅ | ✅ | Yes | Yes | Good |\n| 8 | Python serve() | ✅ | - | - | Yes | Yes | Best |\n| 9 | Python serve_anndata() | - | ✅ | ✅ | Yes | Yes | Good |\n| 10 | Jupyter show() | ✅ | - | - | Yes | Yes | Best |\n| 11 | Jupyter show_anndata() | - | ✅ | ✅ | Yes | Yes | Good |\n\n\\* Python required for initial export, not for viewing\n\n**Summary by method:**\n| Method | Exported | h5ad | zarr | Total |\n|--------|----------|------|------|-------|\n| Local/Remote Demo | ✅ | - | - | 2 |\n| Browser File Picker | ✅ | ✅ | ✅ | 3 |\n| Server CLI | ✅ | ✅ | ✅ | 3 |\n| Python serve | ✅ | ✅ | ✅ | 3 |\n| Jupyter | ✅ | ✅ | ✅ | 3 |\n| **Total** | | | | **14** |\n\n### Key Notes:\n- **Browser h5ad/zarr**: Entire file loaded into memory - no lazy loading due to JavaScript limitations\n- **Python h5ad/zarr modes**: True lazy loading via AnnData backed mode (h5ad) or zarr's native chunked access\n- **Pre-exported data**: Always fastest - use for production and sharing\n- **zarr stores**: Can be a directory (.zarr) or a file - the Python server auto-detects the format\n\n---\n\n## Quick Decision Guide\n\n```\nNeed to share publicly?\n |\n +-- YES --> Options 1-2: Local/Remote Demo (export + GitHub Pages)\n |\n +-- NO --> Have Python available?\n |\n +-- NO --> Options 3-5: Browser File Picker\n | (Prefer exported for large datasets)\n |\n +-- YES --> Working in Jupyter?\n |\n +-- YES --> Options 10-11: Jupyter integration\n | show() or show_anndata()\n |\n +-- NO --> Need remote access?\n |\n +-- YES --> Options 6-7: Server CLI\n |\n +-- NO --> Options 8-9: Python serve\n```",
6+
"source": "# Cellucid Loading Options Overview\n\nThis notebook provides a comprehensive overview of all 14 data loading options in Cellucid.\n\n## The 14 Loading Options\n\nCellucid supports 6 deployment modes, each with support for pre-exported binary data, h5ad files, and zarr stores:\n\n| # | Method | Exported | h5ad | zarr | Python | Lazy Load | Performance |\n|---|--------|----------|------|------|--------|-----------|-------------|\n| 1 | Local Demo (GitHub) | ✅ | - | - | No* | Yes | Best |\n| 2 | Remote Demo (GitHub) | ✅ | - | - | No* | Yes | Best |\n| 3 | Browser File Picker | ✅ | - | - | No | Yes | Best |\n| 4 | Browser File Picker | - | ✅ | - | No | **No** | Slower |\n| 5 | Browser File Picker | - | - | ✅ | No | **No** | Slower |\n| 6 | Server CLI | ✅ | - | - | Yes | Yes | Best |\n| 7 | Server CLI | - | ✅ | ✅ | Yes | Yes | Good |\n| 8 | Python serve() | ✅ | - | - | Yes | Yes | Best |\n| 9 | Python serve_anndata() | - | ✅ | ✅ | Yes | Yes | Good |\n| 10 | Jupyter show() | ✅ | - | - | Yes | Yes | Best |\n| 11 | Jupyter show_anndata() | - | ✅ | ✅ | Yes | Yes | Good |\n\n\\* Python required for initial export, not for viewing\n\n**Summary by method:**\n| Method | Exported | h5ad | zarr | Total |\n|--------|----------|------|------|-------|\n| Local/Remote Demo | ✅ | - | - | 2 |\n| Browser File Picker | ✅ | ✅ | ✅ | 3 |\n| Server CLI | ✅ | ✅ | ✅ | 3 |\n| Python serve | ✅ | ✅ | ✅ | 3 |\n| Jupyter | ✅ | ✅ | ✅ | 3 |\n| **Total** | | | | **14** |\n\n### Key Notes:\n- **Browser h5ad/zarr**: Entire file loaded into memory - no lazy loading due to JavaScript limitations\n- **Python h5ad/zarr modes**: True lazy loading via AnnData backed mode (h5ad) or zarr's native chunked access\n- **Pre-exported data**: Always fastest - use for production and sharing\n- **zarr stores**: Can be a directory (.zarr) or a file - the Python server auto-detects the format\n\n## Shareable URLs\n\nThe viewer URL updates to reflect the current data source, enabling bookmarks and sharing:\n\n| Source | URL Format |\n|--------|------------|\n| Demo dataset | `?dataset=dataset_name` |\n| Remote server | `?remote=http://localhost:8765` |\n| GitHub | `?github=owner/repo/path` |\n| Local files | No URL params (browser security) |\n\n**Note:** Loading local files clears URL params since browsers cannot restore file access from URLs.\n\n---\n\n## Quick Decision Guide\n\n```\nNeed to share publicly?\n |\n +-- YES --> Options 1-2: Local/Remote Demo (export + GitHub Pages)\n |\n +-- NO --> Have Python available?\n |\n +-- NO --> Options 3-5: Browser File Picker\n | (Prefer exported for large datasets)\n |\n +-- YES --> Working in Jupyter?\n |\n +-- YES --> Options 10-11: Jupyter integration\n | show() or show_anndata()\n |\n +-- NO --> Need remote access?\n |\n +-- YES --> Options 6-7: Server CLI\n |\n +-- NO --> Options 8-9: Python serve",
77
"id": "27ecade3"
88
},
99
{
@@ -66,7 +66,7 @@
6666
{
6767
"cell_type": "markdown",
6868
"metadata": {},
69-
"source": "---\n\n# Options 6-7: Server via Terminal (CLI)\n\n**Best for:** Team sharing, remote server access\n\n## Option 6: Serve Exported Data\n\n| Property | Value |\n|----------|-------|\n| Data Format | Pre-exported binary |\n| Python Required | Yes (server) |\n| Lazy Loading | Yes |\n| Performance | Best |\n\n```bash\ncellucid serve /path/to/export_dir --port 8765\n```\n\n## Option 7: Serve h5ad or zarr Directly\n\n| Property | Value |\n|----------|-------|\n| Data Format | h5ad or zarr |\n| Python Required | Yes (server) |\n| Lazy Loading | **Yes** (backed mode for h5ad, chunked access for zarr) |\n| Performance | Good |\n\n```bash\n# Serve h5ad file\ncellucid serve-anndata /path/to/data.h5ad --port 8765\n\n# Serve zarr store (directory or file)\ncellucid serve-anndata /path/to/data.zarr --port 8765\n\n# Options:\n# --no-browser Don't auto-open browser\n# --no-backed Load entire file into memory\n# --latent-key Specify latent space for outlier quantiles\n```\n\n## Remote Server with SSH Tunnel\n\n```bash\n# On remote server\ncellucid serve-anndata /data/large_dataset.h5ad --no-browser\n# or\ncellucid serve-anndata /data/large_dataset.zarr --no-browser\n\n# On local machine\nssh -L 8765:localhost:8765 user@server\n\n# Open in browser\n# https://cellucid.com?remote=http://localhost:8765&anndata=true\n```",
69+
"source": "---\n\n# Options 6-7: Server via Terminal (CLI)\n\n**Best for:** Team sharing, remote server access\n\nThe unified `cellucid serve` command auto-detects the data format.\n\n## Option 6: Serve Exported Data\n\n| Property | Value |\n|----------|-------|\n| Data Format | Pre-exported binary |\n| Python Required | Yes (server) |\n| Lazy Loading | Yes |\n| Performance | Best |\n\n```bash\ncellucid serve /path/to/export_dir --port 8765\n```\n\n## Option 7: Serve h5ad or zarr Directly\n\n| Property | Value |\n|----------|-------|\n| Data Format | h5ad or zarr |\n| Python Required | Yes (server) |\n| Lazy Loading | **Yes** (backed mode for h5ad, chunked access for zarr) |\n| Performance | Good |\n\n```bash\n# Serve h5ad file (auto-detected)\ncellucid serve /path/to/data.h5ad --port 8765\n\n# Serve zarr store (auto-detected)\ncellucid serve /path/to/data.zarr --port 8765\n\n# Options:\n# --no-browser Don't auto-open browser\n# --no-backed Load entire file into memory\n# --latent-key Specify latent space for outlier quantiles\n```\n\n## Remote Server with SSH Tunnel\n\n```bash\n# On remote server\ncellucid serve /data/large_dataset.h5ad --no-browser\n# or\ncellucid serve /data/large_dataset.zarr --no-browser\n\n# On local machine\nssh -L 8765:localhost:8765 user@server\n\n# Open in browser\n# https://cellucid.com?remote=http://localhost:8765&anndata=true\n```",
7070
"id": "7765046a"
7171
},
7272
{
@@ -206,7 +206,7 @@
206206
{
207207
"cell_type": "markdown",
208208
"metadata": {},
209-
"source": "---\n\n# Summary: All 14 Options at a Glance\n\n| # | Method | Export | h5ad | zarr | Python | Lazy | Perf |\n|---|--------|--------|------|------|--------|------|------|\n| 1 | Local Demo | ✅ | - | - | No* | Yes | Best |\n| 2 | Remote Demo | ✅ | - | - | No* | Yes | Best |\n| 3 | Browser Picker | ✅ | - | - | No | Yes | Best |\n| 4 | Browser Picker | - | ✅ | - | No | No | Slow |\n| 5 | Browser Picker | - | - | ✅ | No | No | Slow |\n| 6 | CLI serve | ✅ | - | - | Yes | Yes | Best |\n| 7 | CLI serve-anndata | - | ✅ | ✅ | Yes | Yes | Good |\n| 8 | Python serve | ✅ | - | - | Yes | Yes | Best |\n| 9 | Python serve | - | ✅ | ✅ | Yes | Yes | Good |\n| 10 | Jupyter show | ✅ | - | - | Yes | Yes | Best |\n| 11 | Jupyter show | - | ✅ | ✅ | Yes | Yes | Good |\n\n\\* Python required for initial export, but not for viewing\n\n### zarr Notes\n- **zarr stores** can be a directory (`.zarr/`) or a consolidated file\n- Python server auto-detects the format\n- zarr provides native chunked access for efficient lazy loading\n- Ideal for cloud storage scenarios (S3, GCS) with remote zarr stores\n\n---\n\n## Related Notebooks\n\n- [02_local_demo_tutorial.ipynb](02_local_demo_tutorial.ipynb) - GitHub Pages hosting\n- [03_browser_file_picker_tutorial.ipynb](03_browser_file_picker_tutorial.ipynb) - No-Python option\n- [04_server_tutorial.ipynb](04_server_tutorial.ipynb) - CLI and Python servers\n- [05_jupyter_tutorial.ipynb](05_jupyter_tutorial.ipynb) - Jupyter integration",
209+
"source": "---\n\n# Summary: All 14 Options at a Glance\n\n| # | Method | Export | h5ad | zarr | Python | Lazy | Perf |\n|---|--------|--------|------|------|--------|------|------|\n| 1 | Local Demo | ✅ | - | - | No* | Yes | Best |\n| 2 | Remote Demo | ✅ | - | - | No* | Yes | Best |\n| 3 | Browser Picker | ✅ | - | - | No | Yes | Best |\n| 4 | Browser Picker | - | ✅ | - | No | No | Slow |\n| 5 | Browser Picker | - | - | ✅ | No | No | Slow |\n| 6 | CLI serve | ✅ | - | - | Yes | Yes | Best |\n| 7 | CLI serve | - | ✅ | ✅ | Yes | Yes | Good |\n| 8 | Python serve | ✅ | - | - | Yes | Yes | Best |\n| 9 | Python serve | - | ✅ | ✅ | Yes | Yes | Good |\n| 10 | Jupyter show | ✅ | - | - | Yes | Yes | Best |\n| 11 | Jupyter show | - | ✅ | ✅ | Yes | Yes | Good |\n\n\\* Python required for initial export, but not for viewing\n\n### CLI Note\nThe unified `cellucid serve` command auto-detects the data format:\n- `.h5ad` files → served directly via AnnData\n- `.zarr` directories → served directly via AnnData \n- Directories with `dataset_identity.json` → served as pre-exported data\n\n### zarr Notes\n- **zarr stores** can be a directory (`.zarr/`) or a consolidated file\n- Python server auto-detects the format\n- zarr provides native chunked access for efficient lazy loading\n- Ideal for cloud storage scenarios (S3, GCS) with remote zarr stores\n\n---\n\n## Related Notebooks\n\n- [02_local_demo_tutorial.ipynb](02_local_demo_tutorial.ipynb) - GitHub Pages hosting\n- [03_browser_file_picker_tutorial.ipynb](03_browser_file_picker_tutorial.ipynb) - No-Python option\n- [04_server_tutorial.ipynb](04_server_tutorial.ipynb) - CLI and Python servers\n- [05_jupyter_tutorial.ipynb](05_jupyter_tutorial.ipynb) - Jupyter integration",
210210
"id": "b4215735"
211211
}
212212
],

‎docs/user_guide/03_browser_file_picker_tutorial.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@
145145
{
146146
"cell_type": "markdown",
147147
"metadata": {},
148-
"source": "---\n\n## Summary\n\n### Browser File Picker - Key Points\n\n1. **No Python needed** - works directly in browser\n2. **Three options:**\n - Folder button: Pre-exported data (recommended)\n - .h5ad button: Direct h5ad loading\n - .zarr button: Direct zarr loading\n3. **h5ad/zarr limitations:**\n - Entire file loaded into memory\n - No lazy loading\n - Best for small datasets (< 50k cells)\n\n### Quick Links\n\n- [Cellucid Web Viewer](https://cellucid.com)\n- [01_loading_options_overview.ipynb](01_loading_options_overview.ipynb) - All 14 options\n- [02_local_demo_tutorial.ipynb](02_local_demo_tutorial.ipynb) - GitHub Pages hosting\n- [04_server_tutorial.ipynb](04_server_tutorial.ipynb) - Python server options",
148+
"source": "---\n\n## Summary\n\n### Browser File Picker - Key Points\n\n1. **No Python needed** - works directly in browser\n2. **Three options:**\n - Folder button: Pre-exported data (recommended)\n - .h5ad button: Direct h5ad loading\n - .zarr button: Direct zarr loading\n3. **h5ad/zarr limitations:**\n - Entire file loaded into memory\n - No lazy loading\n - Best for small datasets (< 50k cells)\n4. **URL behavior:** Loading local files clears URL params - browsers cannot restore file access from URLs, so bookmarking/sharing these sessions is not possible.\n\n### Quick Links\n\n- [Cellucid Web Viewer](https://cellucid.com)\n- [01_loading_options_overview.ipynb](01_loading_options_overview.ipynb) - All 14 options\n- [02_local_demo_tutorial.ipynb](02_local_demo_tutorial.ipynb) - GitHub Pages hosting\n- [04_server_tutorial.ipynb](04_server_tutorial.ipynb) - Python server options",
149149
"id": "81e4e0d4"
150150
}
151151
],

0 commit comments

Comments
 (0)