version 0.9.0

Author: inecik

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-01-01
+
+This release graduates Cellucid Python out of alpha (still pre-1.0).
+
+### Added
+
+- AnnData-first viewing and serving with `.h5ad` and `.zarr` support (lazy/backed loading where possible).
+- Unified `cellucid serve` CLI with auto-detection for `.h5ad`, `.zarr`, and pre-exported dataset directories.
+- Jupyter notebook integration (`CellucidViewer`, `AnnDataViewer`, `show()`, `show_anndata()`) with event hooks and session export.
+- Session bundle support (`.cellucid-session`) including `CellucidSessionBundle` and `apply_cellucid_session_to_anndata()` for round-tripping highlights and user-defined fields back into AnnData.
+- Multi-dimensional embedding exports (1D/2D/3D/4D) and vector-field overlays (RNA velocity / drift) via `prepare()` and `vector_fields` helpers.
+- Hosted web UI proxy mode with on-disk caching helpers (`get_web_cache_dir()`, `clear_web_cache()`).
+
+### Changed
+
+- Export format now includes explicit dataset identity metadata (`dataset_identity.json`) for reproducible sharing and session compatibility checks.
+- Reduced export size and improved load performance with optimized manifests, improved connectivity edge export, and optional quantization + gzip compression knobs.
+
+### Security
+
+- Session bundles are treated as untrusted input with bounds checks and dataset mismatch policies when applying to AnnData.
+
+### Documentation
+
+- Major Read the Docs expansion and restructuring (Python package + web app guides), plus new publishing and contributing documentation.
+
 ## [0.0.1a2] - 2025
 
 ### Added
@@ -25,5 +51,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   - Jupyter integration (`show()`, `show_anndata()`)
 - Export functionality for web deployment
 
-[Unreleased]: https://github.com/theislab/cellucid-python/compare/v0.0.1a2...HEAD
+[Unreleased]: https://github.com/theislab/cellucid-python/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/theislab/cellucid-python/releases/tag/v0.9.0
 [0.0.1a2]: https://github.com/theislab/cellucid-python/releases/tag/v0.0.1a2

PUBLISHING.md

@@ -114,7 +114,7 @@ python -m twine check dist/*
 ### 3.0 Publish via GitHub Actions (recommended)
 
 If `PYPI_API_TOKEN` is configured (Section 1.3):
-1) Push a tag like `v0.0.1a3` (Section 2.3.1).
+1) Push a tag like `v0.0.9` (Section 2.3.1). <!-- CELLUCID_VERSION -->
 2) Watch the GitHub Actions run: **Actions → Publish to PyPI**.
 
 That workflow builds and uploads both wheel and sdist.

README.md

@@ -1,257 +1,57 @@
-<p>
-  <img src="https://raw.githubusercontent.com/theislab/cellucid-python/main/cellucid-logo.svg" alt="Cellucid logo" width="360">
-</p>
+![Cellucid](https://raw.githubusercontent.com/theislab/cellucid-python/main/cellucid-logo.svg)
 
 [![PyPI version](https://img.shields.io/pypi/v/cellucid.svg)](https://pypi.org/project/cellucid/)
 [![Python versions](https://img.shields.io/pypi/pyversions/cellucid.svg)](https://pypi.org/project/cellucid/)
 [![Documentation Status](https://readthedocs.org/projects/cellucid/badge/?version=latest)](https://cellucid.readthedocs.io/en/latest/)
+[![License](https://img.shields.io/pypi/l/cellucid.svg)](https://pypi.org/project/cellucid/)
 
 # Cellucid
 
-Python package for visualizing single-cell data with the [Cellucid WebGL viewer](https://cellucid.com). Cellucid renders millions of cells in real-time 3D, enabling interactive exploration of UMAP/tSNE embeddings with gene expression overlays, filtering, and KNN connectivity visualization.
+**See every cell. Query any gene. Fly through millions. Interactive, GPU-accelerated single-cell visualization in the browser.**
 
-## Features
+Cellucid is a browser-first viewer for exploring large single-cell datasets in real time: fly through 2D/3D embeddings (UMAP/t-SNE/PCA), color by genes or metadata, filter and compare populations, and share reproducible views with collaborators.
 
-- **Interactive Single-Cell Data Visualization** of UMAP/tSNE embeddings
-- **Gene expression overlays** with fast queries
-- **Cell metadata filtering** and categorical coloring
-- **KNN connectivity** edge visualization
-- **Multi-dimensional** support (1D timelines, 2D, 3D)
-- **Jupyter integration** with bidirectional communication
-- **Scales to millions** of cells with adaptive LOD
+## Highlights
 
-## Installation
+- **GPU-accelerated WebGL rendering** with adaptive detail for millions of cells
+- **AnnData-first workflow** for the Scanpy ecosystem (`.h5ad` and Zarr supported)
+- **Shareable exports** you can host locally, on GitHub, or behind a server
+- **Genes + metadata overlays** optimized for interactive querying
+- **Connectivity + dynamics**: KNN edges and animated vector fields (RNA velocity / drift)
+- **Collaboration**: community annotation voting with optional GitHub sync
+- **Publication export**: SVG (vector) and high-DPI PNG figures
+- **Works everywhere**: web app, local/remote server, and Jupyter notebooks
 
-```bash
-pip install cellucid
-```
-
-All features (Jupyter, AnnData, server) are included in the standard install.
-
-## Quick Start
-
-### Option 1: Direct AnnData Visualization (No Export)
-
-The fastest way to get started - visualize your AnnData directly:
-
-```python
-from cellucid import show_anndata
-
-# In-memory AnnData
-show_anndata(adata)
-
-# From h5ad file (lazy loading)
-show_anndata("/path/to/data.h5ad")
-
-# From zarr store (lazy loading)
-show_anndata("/path/to/data.zarr")
-```
-
-### Option 2: Pre-export for Best Performance
-
-For production use or sharing, export to optimized binary format:
-
-```python
-from cellucid import prepare, show
-
-# Pick UMAP embeddings (explicit keys preferred, fall back to X_umap).
-X_umap_1d = adata.obsm.get("X_umap_1d")
-X_umap_2d = adata.obsm.get("X_umap_2d")
-X_umap_3d = adata.obsm.get("X_umap_3d")
-X_umap = adata.obsm.get("X_umap")  # may be 1D/2D/3D depending on how it was computed
-if X_umap is not None and X_umap_1d is None and X_umap.shape[1] == 1:
-    X_umap_1d = X_umap
-if X_umap is not None and X_umap_2d is None and X_umap.shape[1] == 2:
-    X_umap_2d = X_umap
-if X_umap is not None and X_umap_3d is None and X_umap.shape[1] == 3:
-    X_umap_3d = X_umap
-
-# Optional: include any per-cell displacement vector fields in embedding space
-# (see "Vector Field Overlay" section below for naming conventions).
-vector_fields = {
-    "velocity_umap_2d": adata.obsm.get("velocity_umap_2d"),
-    "velocity_umap_3d": adata.obsm.get("velocity_umap_3d"),
-}
-
-prepare(
-    # Required inputs
-    latent_space=adata.obsm.get(
-        "X_pca",
-        X_umap_3d if X_umap_3d is not None else (X_umap_2d if X_umap_2d is not None else X_umap_1d),
-    ),
-    obs=adata.obs,
-    var=adata.var,
-    gene_expression=adata.X,
-
-    # Optional inputs
-    connectivities=adata.obsp.get("connectivities"),
-    vector_fields=vector_fields,
-
-    # Embeddings (provide any/all of 1D/2D/3D)
-    X_umap_1d=X_umap_1d,
-    X_umap_2d=X_umap_2d,
-    X_umap_3d=X_umap_3d,
-
-    # Output + performance knobs
-    out_dir="./my_export",
-    compression=6,
-    var_quantization=8,
-    obs_continuous_quantization=8,
-)
-
-# View anytime (fastest loading)
-show("./my_export")
-```
-
-## AnnData Requirements
-
-Your AnnData needs UMAP coordinates in `obsm`:
-
-```python
-# Required: one of these
-adata.obsm['X_umap_3d']  # shape (n_cells, 3) - recommended
-adata.obsm['X_umap_2d']  # shape (n_cells, 2)
-adata.obsm['X_umap']     # shape (n_cells, 2 or 3)
-
-# Optional
-adata.obsm['velocity_umap_2d']  # shape (n_cells, 2) - vector field overlay (velocity/drift)
-adata.obs                # Cell metadata (categorical/continuous)
-adata.X                  # Gene expression (dense or sparse)
-adata.obsp['connectivities']  # KNN graph edges
-```
-
-### Vector Field Overlay (Velocity / CellRank Drift)
-
-Cellucid’s web viewer can render an animated particle-flow overlay from **per-cell displacement vectors** in embedding space.
-
-Store vectors in `adata.obsm` with keys like:
-- `velocity_umap_2d`, `velocity_umap_3d`
-- `T_fwd_umap_2d`, `T_bwd_umap_2d` (CellRank-style drift)
-
-If you have a CellRank transition matrix `T` and an embedding `X_umap`, you can derive drift vectors:
-
-```python
-from cellucid import add_transition_drift_to_obsm
-
-add_transition_drift_to_obsm(
-    adata,
-    T_fwd,                # (n_cells, n_cells) sparse/dense transition matrix
-    basis="umap",
-    field_prefix="T_fwd", # -> writes adata.obsm['T_fwd_umap_<dim>d']
-)
-```
-
-Computing 3D UMAP with scanpy:
-
-```python
-import scanpy as sc
-sc.pp.neighbors(adata)
-sc.tl.umap(adata, n_components=3)
-adata.obsm['X_umap_3d'] = adata.obsm['X_umap']
-```
-
-## All 14 Loading Options
-
-Cellucid supports 6 deployment modes, each with support for pre-exported binary data, h5ad files, and zarr stores:
-
-| # | Method | Exported | h5ad | zarr | Python | Lazy Load | Performance |
-|---|--------|----------|------|------|--------|-----------|-------------|
-| 1 | Local Demo (GitHub) | ✅ | - | - | No* | Yes | Best |
-| 2 | Remote Demo (GitHub) | ✅ | - | - | No* | Yes | Best |
-| 3 | Browser File Picker | ✅ | - | - | No | Yes | Best |
-| 4 | Browser File Picker | - | ✅ | - | No | **No** | Slower |
-| 5 | Browser File Picker | - | - | ✅ | No | **No** | Slower |
-| 6 | Server CLI | ✅ | - | - | Yes | Yes | Best |
-| 7 | Server CLI | - | ✅ | ✅ | Yes | Yes | Good |
-| 8 | Python serve() | ✅ | - | - | Yes | Yes | Best |
-| 9 | Python serve_anndata() | - | ✅ | ✅ | Yes | Yes | Good |
-| 10 | Jupyter show() | ✅ | - | - | Yes | Yes | Best |
-| 11 | Jupyter show_anndata() | - | ✅ | ✅ | Yes | Yes | Good |
-
-\* Python required for initial export, not for viewing
-
-**Summary by method:**
-| Method | Exported | h5ad | zarr | Total |
-|--------|----------|------|------|-------|
-| Local/Remote Demo | ✅ | - | - | 2 |
-| Browser File Picker | ✅ | ✅ | ✅ | 3 |
-| Server CLI | ✅ | ✅ | ✅ | 3 |
-| Python serve | ✅ | ✅ | ✅ | 3 |
-| Jupyter | ✅ | ✅ | ✅ | 3 |
-| **Total** | | | | **14** |
-
-### Key Notes:
-- **Browser h5ad/zarr**: Entire file loaded into memory - no lazy loading due to JavaScript limitations
-- **Python h5ad/zarr modes**: True lazy loading via AnnData backed mode (h5ad) or zarr's native chunked access
-- **Pre-exported data**: Always fastest - use for production and sharing
-- **zarr stores**: Can be a directory (.zarr) or a file - the Python server auto-detects the format
-
-## Deployment Modes
-
-| Mode | Best For | Command/Function |
-|------|----------|------------------|
-| **Jupyter** | Interactive analysis | `show_anndata(adata)` |
-| **Local server** | Development | `cellucid serve ./data` |
-| **Remote + SSH** | Team access | `cellucid serve data.h5ad` |
-| **Browser** | Quick preview | [cellucid.com](https://cellucid.com) file picker |
-| **Static hosting** | Public sharing | GitHub Pages |
-
-### CLI Commands
+## Install
 
 ```bash
-# Serve any data - format auto-detected
-cellucid serve /path/to/data.h5ad      # h5ad file
-cellucid serve /path/to/data.zarr      # zarr store
-cellucid serve /path/to/export         # pre-exported data
-
-# With options
-cellucid serve data.h5ad --port 9000 --no-browser
-
-# Show version
-cellucid --version
+pip install cellucid
 ```
 
-### Remote Server Access
+## Quickstart
 
-```bash
-# On remote server
-cellucid serve /data/cells.h5ad --no-browser
+Try the web app (no setup):
 
-# On local machine (SSH tunnel)
-ssh -L 8765:localhost:8765 user@server
-# Then open: https://cellucid.com?remote=http://localhost:8765
-```
+1. Open https://cellucid.com
+2. Load a pre-exported folder, `.h5ad`, or `.zarr`
 
-## Jupyter Features
+Or visualize an AnnData from Python/Jupyter:
 
 ```python
 from cellucid import show_anndata
 
-viewer = show_anndata(adata, height=600)
-
-# Programmatic control
-viewer.highlight_cells([1, 2, 3], color="#ff0000")
-viewer.set_color_by("cell_type")
-viewer.set_visibility([0, 1, 2], visible=False)
-
-# Cleanup
-viewer.stop()
+show_anndata(adata)  # or: show_anndata("dataset.h5ad")
 ```
 
-## Performance Guide
-
-| Method | Load Time | Gene Queries | Recommended For |
-|--------|-----------|--------------|-----------------|
-| Pre-exported (`show`) | Fast | Fast | Production, sharing |
-| Direct AnnData (`show_anndata`) | Medium | Medium | Exploration |
-| Browser file picker | Slower | Slower | Quick preview |
-
-For datasets > 500k cells, pre-export with `prepare()` is recommended.
-
-## Documentation
+## Links
 
-- **[Full documentation](https://cellucid.readthedocs.io)** - API reference and tutorials
-- **[Web viewer](https://github.com/theislab/cellucid)** - JavaScript repository
+- Web app: https://cellucid.com
+- Documentation: https://cellucid.readthedocs.io
+- Community annotation voting: https://cellucid.readthedocs.io/en/latest/user_guide/web_app/j_community_annotation/index.html
+- Source: https://github.com/theislab/cellucid-python
+- Web viewer: https://github.com/theislab/cellucid
+- Annotation template: https://github.com/theislab/cellucid-annotation
+- Issues: https://github.com/theislab/cellucid-python/issues
 
 ## License
 

docs/_static/switcher.json

@@ -5,8 +5,9 @@
         "url": "https://cellucid.readthedocs.io/en/latest/"
     },
     {
-        "name": "0.0.1a2 (stable)",
-        "version": "0.0.1a2",
+        "name": "0.0.9 (stable)",
+        "version": "0.0.9",
+        "cellucid_version_marker": "CELLUCID_VERSION",
         "url": "https://cellucid.readthedocs.io/en/stable/",
         "preferred": true
     }

docs/conf.py

@@ -22,7 +22,7 @@
 
     release = version = __version__
 except Exception:
-    release = version = "0.0.1a2"
+    release = version = "0.0.9"  # CELLUCID_VERSION
 
 # -- General configuration ---------------------------------------------------
 extensions = [

docs/user_guide/python_package/a_landing_pages/02_installation.md

@@ -67,7 +67,7 @@ pip install -U cellucid
 Pin a specific version (recommended for paper pipelines):
 
 ```bash
-pip install "cellucid==0.0.1a2"
+pip install "cellucid==0.0.9"  # CELLUCID_VERSION
 ```
 
 ### Optional dependencies (what you might need next)

docs/user_guide/python_package/c_data_preparation_api/09_output_format_specification_exports_directory.md

@@ -81,7 +81,8 @@ It provides:
   "name": "PBMC demo",
   "description": "",
   "created_at": "2026-01-01T00:00:00Z",
-  "cellucid_data_version": "0.0.1a2",
+  "_cellucid_version_marker": "CELLUCID_VERSION",
+  "cellucid_data_version": "0.0.9",
   "stats": {
     "n_cells": 10000,
     "n_genes": 2000,

docs/user_guide/python_package/f_notebooks_tutorials/jupyter_hooks_sessions_he_developmental.ipynb

@@ -267,12 +267,12 @@
               " 'client_server_url': 'http://127.0.0.1:8766',\n",
               " 'server_health': {'status': 'ok',\n",
               "  'type': 'anndata',\n",
-              "  'version': '0.0.1a2',\n",
+              "  'version': '0.0.9',\n",
               "  'format': 'h5ad',\n",
               "  'is_backed': True,\n",
               "  'n_cells': 71650,\n",
               "  'n_genes': 8192},\n",
-              " 'server_info': {'version': '0.0.1a2',\n",
+              " 'server_info': {'version': '0.0.9',\n",
               "  'type': 'anndata',\n",
               "  'format': 'h5ad',\n",
               "  'host': '127.0.0.1',\n",
@@ -493,6 +493,7 @@
     }
   ],
   "metadata": {
+    "cellucid_version_marker": "CELLUCID_VERSION",
     "kernelspec": {
       "display_name": "tardis_env",
       "language": "python",