R Package Guide#
This guide documents the cellucid R package (repo: cellucid-r): how to look at a Seurat, SingleCellExperiment or SummarizedExperiment object in the Cellucid viewer from R (cellucid_view(), in the RStudio or Positron Viewer pane or a browser with no Python, or in a Jupyter notebook’s output), bring what you make there back onto the object (cellucid_pull()), and how to write it — or matrices and data frames — as a Cellucid-ready AnnData (several assays: a Cellucid-ready MuData), a standard Zarr store (a .zarr folder or one .zarr.zip file) that the Cellucid web app opens and Python’s anndata reads.
Note
The viewer runs from R: cellucid_view() and cellucid_serve() serve the
object from memory (in a Jupyter notebook cellucid_view() shows it in the
cell’s output as a notebook widget, with no server), one function per action
of the viewer (cellucid_color_by(), cellucid_highlight_cells(), …,
cellucid_act()) acts on it as a step of its history, cellucid_on() and its
siblings receive events over the viewer’s channel, cellucid_pull() writes every highlight, label, score and
gene set made in the viewer onto the object and cellucid_push() sends a
column into it, cellucid_read_session() reads a saved session’s history
(trackers, branches, steps, notes and turns) and cellucid_apply_session()
applies any step of it back onto the object, a plan first
(Viewing and Loading). There is no Shiny or
htmlwidgets integration.
For the web UI experience after opening a store (filtering, analysis, sessions, community annotation), see Web App Guide.
Active package version — 0.9.7
Version 0.9.7 is the active Cellucid for R source and documentation
version and the CRAN submission release. The
CRAN package index
is authoritative for registry availability. Check an installed environment
with packageVersion("cellucid"); the Installation page gives the
matching CRAN and official-source installation paths.
Where to start (pick one)#
“I need to install or verify Cellucid for R” → Installation
“I have a Seurat object” → Seurat Recipe
“I have a SingleCellExperiment” → SingleCellExperiment Recipe
“I just have matrices/data.frames” → Raw Matrices + Data Frames
“I want to understand what gets written to disk” → What is a Cellucid-ready AnnData?
“I want to add vector fields (velocity/drift overlays)” → Vector fields (velocity / displacement)
“I want a full end-to-end walkthrough” → Notebook Tutorials
“I want what I make in the viewer back in my Seurat or SingleCellExperiment object (and my clusters in the viewer)” → Pull everything back: highlights, labels and scores (Seurat, SingleCellExperiment) and the other notebooks of Notebook Tutorials (Jupyter, Colab, RStudio; each with a Python twin)
“Something failed” → Troubleshooting Index
Chapters (what each folder contains)#
Install version 0.9.7 from the source currently available to you, verify the loaded package, and diagnose dependency or environment problems.
Quick starts and “what is this?” explanations for mixed audiences.
What a Cellucid-ready AnnData store is, how it reaches the browser, plus dataset identity and reproducibility.
Deep documentation of cellucid_prepare() including shapes, dtypes, edge cases, and the store layout.
How to open .zarr folders and .zarr.zip files in the Cellucid web app, and how to host them for sharing.
Practical recipes for Seurat and SingleCellExperiment (and “raw matrix” workflows).
Very detailed, notebook-style walkthroughs with lots of “why”, edge cases, and troubleshooting.
A map of what parts of the R API are documented where (useful for maintainers and contributors).
Implementation notes, testing/release guidance, and codebase architecture for cellucid-r contributors.
Symptom → diagnosis → fix across installation, data preparation, and web app loading.