Cellucid (R)

Export single-cell data from R to Cellucid — interactive, GPU-accelerated visualization in the browser.

cellucid (repo: cellucid-r) writes your embeddings, metadata, gene expression, connectivities, and vector fields to the on-disk format consumed by the Cellucid web app.

Active package version — 0.9.1

Version 0.9.1 is the active Cellucid for R source and documentation version, and it is the CRAN submission release. The CRAN package index is authoritative for registry availability; the Installation guide below gives both exact installation paths.

Highlights

• Exporter-only: generate a shareable “export folder” and open it in the web app
• Minimal dependencies: hard dependency jsonlite (optional/recommended: Matrix)
• Flexible inputs: works with raw matrices/data.frames, with docs recipes for Seurat and SingleCellExperiment
• Optional extras: gene expression, connectivity graphs, and vector fields for overlays like velocity/drift

Connectivity matrices may carry positive edge weights. They must be exactly symmetric in topology and weight, have a zero diagonal, and contain no negative, missing, or infinite values. Sparse inputs must omit stored zero entries.

Continuous observation fields, gene-expression matrices, and vector fields must contain only finite values. For unquantized float32 output, every nonzero value after required vector scaling must have magnitude from 2^-149 through (2 - 2^-23) * 2^127; values that would encode as zero or infinity reject the complete candidate. Quantized continuous fields and their manifest bounds use the viewer's exact float32 values; a native-double range that collapses to one float32 value rejects the complete candidate. Individual nonzero source values may round to zero when the resulting float32 range remains non-collapsed. The reserved quantized missing marker is used only for categorical outlier quantiles that Cellucid generates as NaN when a category has fewer than centroid_min_points cells.

gene_expression is always interpreted as cells × genes. Cellucid validates its row and column counts but never guesses or transposes orientation; for a square matrix, shape alone cannot reveal a genes × cells input.

Installation

Use the dedicated Installation guide to choose CRAN or GitHub based on current registry availability. To install the active source directly from the official GitHub repository:

install.packages("remotes")
remotes::install_github("theislab/cellucid-r")

Optional but recommended (sparse matrices + connectivity export):

install.packages("Matrix")

See the dedicated Installation guide for requirements, verification, upgrades, and the CRAN availability status.

Quickstart

library(cellucid)

cellucid_prepare(
  dataset_id = "my-dataset",
  dataset_name = "My dataset",
  latent_space = latent,   # cells × dims
  obs = obs,               # data.frame (cells × fields)
  var = var,               # data.frame (genes × fields)
  gene_expression = expr,  # optional: cells × genes
  X_umap_2d = umap2,       # optional
  out_dir = "exports/my_dataset",
  force = TRUE,
  obs_categorical_dtype = "uint16"
)

Documentation and ecosystem

• R package guide with recipes for Seurat and SingleCellExperiment
• Complete Cellucid documentation
• Live web application and web viewer source
• Python package
• Official public demo datasets
• Three custom dataset repository examples
• Community annotation repository
• Citation: citation("cellucid")

Community

• Contributing: CONTRIBUTING.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Security: SECURITY.md
• Support: SUPPORT.md
• GitHub citation metadata: CITATION.cff

License

BSD-3-Clause