CelliVerse — Decode Cell Identity

Choose your route

Start where you are.

CelliVerse supports different ways of working. Jump straight to the part that matches your data, experience and scientific question.

⌘

I am a bioinformaticianRun ClustoCell directly in R, inspect markers, annotate clusters and integrate the outputs with your existing single-cell workflow.

✦

I do not codeUse the CelliVerse Agent to request supported analyses through natural-language instructions in a local browser interface.

◎

I want to annotate cellsChoose curated MarkerDB annotation, direct LLM interpretation, or generate a portable prompt for your preferred chatbot.

↗

I have a very large datasetUse integrated sketching or decouple sketch creation and label transfer for atlas-scale analyses.

⬡

I work on cancerExplore malignant-cell, immune-state and spatial applications demonstrated across cancer single-cell and spatial datasets.

▶

I want to try it firstExplore the browser-based demo, read the full vignette, or inspect the CRAN package page before installing anything locally.

The motivation

Why build ClustoCell?

Conventional annotation and clustering workflows can inherit limitations from references, preprocessing choices and differential-expression ranking. ClustoCell approaches cell identity from the marker structure inside each cell.

Cell identity should emerge from informative markers, not just from variance.

ClustoCell was developed to address limitations associated with both reference-based and marker-based cell-type identification.

✓

Less reference dependence
Discovery is not forced to conform to a predefined reference atlas.

✓

DE ≠ marker identification
High enrichment alone does not guarantee a biologically meaningful or specific marker.

✓

Cell-centric representation
Within-cell ranking and EWCSR emphasize relative expression structure while reducing dependence on global expression scale.

✓

Data-driven hierarchy
Major populations can be followed by sub-clustering and subtype/state-specific marker discovery.

Common dependency

ClustoCell design choice

Reference qualityAnnotation can change with reference composition and compatibility.

Marker-driven discoveryClusters emerge from within-dataset marker relationships before annotation.

HVG / variance-based featuresHighly variable genes are not necessarily cell-type-specific.

Rank-based feature filtrationFeatures are prioritized according to their informative rank patterns across cells.

DE rankingEnrichment may include low-level or non-specific genes and may miss shared markers.

Authentic marker rankingMarker occurrence, purity and cluster specificity are integrated into downstream ranking.

Normalization sensitivityExpression scale and sample-level shifts may alter downstream structure.

Cell-centric transformationEWCSR and logical marker representations are designed for robustness to library-size and expression-scale variation.

Core method

From expression matrix to biological groups.

ClustoCell follows a five-stage framework: feature filtration, logical marker representation, cell-similarity graph construction, major clustering and marker detection, then optional sub-clustering.

ClustoCell framework

Marker-centric clustering and ranked marker discovery in one workflow

Step 1Feature filtration + EWCSR

Filter informative rank patterns and transform expression with expression-weighted centered scaled ranks.

Step 2Logical marker matrices

Represent high- and medium-expression marker states as sparse logical features.

Step 3Cell-similarity graph

Measure marker overlap with Jaccard similarity and refine neighborhood evidence with mutual rank.

Step 4Graph modularization

Detect major clusters, then optionally resolve biologically informative sub-clusters.

Step 5Rank authentic markers

Prioritize positive and negative markers for clusters and sub-clusters for downstream interpretation.

✦Designed for robustness: the framework is built to reduce sensitivity to library-size variation, global batch shifts and expression-scale changes while preserving cell-intrinsic marker programs.

Benchmarking

What has ClustoCell been tested to do?

ClustoCell has been evaluated for clustering concordance, marker quality, robustness, scalability and biologically challenging use cases across diverse single-cell datasets.

◉

Cell-type-concordant clusteringBenchmarked using concordance, ARI, NMI and fragmentation-style measures across annotated datasets.

★

Improved marker identificationEvaluated against conventional marker-ranking approaches with emphasis on marker specificity and biological relevance.

≈

Normalization & batch robustnessTested across normalization choices and global batch effects to assess stability of the marker-centric representation.

↗

Large-scale analysisSupports sketch-based workflows to extend ClustoCell analysis to large single-cell collections.

For R users

Start with one function. Build from there.

The standard R interface remains the most direct route for reproducible scripted analysis. ClustoCell accepts supported single-cell objects or expression matrices, and its outputs can be added back to common single-cell objects for visualization and downstream analysis.

Cluster + discover markersRun clustoCell() on your single-cell object or sparse matrix.

Add results backUse addClustoData() to attach cluster and sub-cluster labels.

AnnotateUse MarkerDB, direct LLM annotation or typoPrompt().

library(celliverse)

# Joint clustering + marker discovery
pbmc_clustoCell <- clustoCell(
  data    = pbmc3k_so,
  seed    = 121,
  verbose = FALSE
)

# Add ClustoCell labels back to your object
pbmc3k_so <- addClustoData(
  obj        = pbmc3k_so,
  clustoCell = pbmc_clustoCell
)

# Curated CelliVerse MarkerDB annotation
pbmc_typo <- typoClust(
  objects      = list(pbmc_clustoCell),
  desired_sets = paste0("C", 1:5),
  tissue       = "Blood",
  mode         = "markerDB",
  species      = "human",
  verbose      = FALSE
)

# Or create an LLM-ready portable prompt
prompt <- typoPrompt(pbmc_clustoCell)

# Integrated sketching for larger datasets
large_cc <- clustoCell(
  data                 = large_object,
  sketch               = TRUE,
  sketch_ncells        = 5000,
  identify_subclusters = TRUE,
  seed                 = 121,
  verbose              = FALSE
)

# For very large datasets, sketch creation and
# label transfer can also be decoupled.

# One-time setup
install_celliverse_agent()

# Launch the browser-based local interface
run_celliverse_agent()

# Optional: launch using a local model provider
run_celliverse_agent(
  provider = "ollama",
  model    = "qwen3:8b"
)

Cell-type interpretation

One marker result. Multiple annotation routes.

Use a curated marker resource for reproducibility, ask a configured LLM directly, or export a structured prompt and take it to the model of your choice.

CelliVerse MarkerDB

Harmonized positive and negative marker information for human and mouse, integrated into the package for curated annotation.

typoClust(mode = "markerDB")

Direct LLM annotation

Pass ClustoCell or MarkoCell marker panels to a configured language model through the familiar TypoClust interface.

typoClust(mode = "ceLLMarkup")

✦

ceLLMarkup

Call LLM-based annotation directly from marker panels, clustering results or compatible marker tables when you want model-specific control.

ceLLMarkup()

↗

Portable TypoPrompt

Generate a structured, reviewable annotation prompt without connecting R to a model provider. Copy it into any suitable chatbot or LLM.

typoPrompt()

Natural-language analysis

Meet the CelliVerse Agent.

A browser-based interface that lets you request supported CelliVerse workflows in natural language while keeping the R analysis environment underneath. It complements, rather than replaces, the standard scripted R interface.

1Load data. Use supported R objects, delimited matrices, Matrix Market / 10x inputs and selected HDF5 formats.

2Ask clearly. “Run ClustoCell on the object”, “give me the top ranked markers”, or “annotate C1–C3”.

3Inspect outputs. Explore clusters, sub-clusters, markers, annotations, UMAPs and generated analysis objects.

4Choose your model. Use supported cloud providers or local model runtimes such as Ollama or LM Studio.

Agent setup guide View source

.rds / .RData / .rda.csv / .tsv / .txt.mtx + sidecars10x .zip.h5 with hdf5r

CelliVerse Agent browser interface screenshot

Where it has been applied

From PBMCs to cancer and spatial omics.

ClustoCell resolves immune populations and cell states, identifies malignant-cell programs, supports immunotherapy-response analyses and maps data-driven populations back into spatial tissue contexts.

PBMC & immune profiling

Resolve major immune populations, subtypes and cell states, then use the derived markers for annotation and improved visualization.

PBMC3K + atlas benchmarks

Cancer & malignant-cell discovery

Use data-driven clusters and marker programs to separate malignant from non-malignant populations and characterize tumor-associated states.

Prostate cancer + multi-cancer scRNA-seq

Immunotherapy response states

Resolve effector, proliferative and exhausted T-cell programs and connect sub-cluster frequencies to clinically relevant response-associated biology.

Effector–exhaustion circuit

Spatial transcriptomics

Map ClustoCell-defined populations back into tissue coordinates to study glandular organization, tumor regions and localized cell communities.

Visium HD + Xenium

Spatial ecotypes

Use fine-grained ClustoCell populations as building blocks for spatial ecotype discovery and interpretation of multicellular niches.

MERSCOPE melanoma

Atlas-scale analysis

Use the integrated sketching workflow for moderate-to-large datasets, or decouple sketching and full-resolution label transfer when resources are constrained.

Sketch → ClustoCell → transfer

Built to fit existing workflows

Use ClustoCell on supported objects or sparse matrices, add cluster labels back to your single-cell object, and continue with the visualization and downstream ecosystem you already use.

Discovery before annotation

ClustoCell can identify structure without requiring reference labels first. Annotation is a downstream interpretation step, not a prerequisite for defining the groups.

Explore before installation

See CelliVerse before you install it.

Explore precomputed ClustoCell outputs in the browser, read the complete vignette, or inspect the official CRAN package page before moving to your own data.

Interactive demo

Explore PBMC3K outputs

Inspect precomputed UMAPs, ClustoCell clusters/sub-clusters and marker tables directly in the browser.

Open Hugging Face Space ↗

Full documentation

Read the CelliVerse vignette

Follow the end-to-end workflow for clustering, marker discovery, cell-type annotation, visualization, large datasets and the CelliVerse Agent.

Read the vignette ↗

Official R package

View the CRAN version

Open the official CRAN package page for the current release, package metadata and installation information.

CRAN version ↗

Open & reproducible

Code, data resources and analysis workflows.

CelliVerse keeps the R package focused while analysis scripts, prepared MarkerDB resources and archived datasets remain openly accessible.

CelliVerse R package

Source code, package documentation, vignettes and development history.

GitHub repositoryasalavaty/celliverse ↗ Full vignetteDocumentation ↗ CRAN versionOfficial package page ↗

Analysis reproducibility

Prepared MarkerDB resources, figure-generating R Markdown scripts and public datasets.

CelliVerse-ProjectScripts + MarkerDB ↗ Zenodo archive10.5281/zenodo.20550512 ↗ Browser demoHugging Face ↗

What is the main difference between CelliVerse and ClustoCell?

CelliVerse is the broader R ecosystem. ClustoCell is its central method for data-driven clustering, sub-clustering and marker discovery. CelliVerse adds focused marker workflows, annotation, visualization, large-data support and the optional Agent around that core.

Does ClustoCell require a reference atlas?

No reference is required to define the ClustoCell groups. The method discovers structure from the input data and its marker relationships. A marker database or LLM can then be used downstream to interpret and annotate those groups.

Can I use CelliVerse if I already use Seurat?

Yes. ClustoCell can operate on supported single-cell objects, and functions such as addClustoData() are designed to add its results back to the analysis object so you can continue with familiar downstream workflows.

Can CelliVerse handle very large datasets?

CelliVerse includes sketch-based workflows. For moderate-to-large datasets you can use integrated sketching; for very large datasets or constrained hardware, sketch creation and label transfer can be decoupled so ClustoCell runs on a representative subset and labels are transferred back to the full data.

How does cell-type annotation work?

You can annotate using the curated CelliVerse MarkerDB with typoClust(mode = "markerDB"), use direct LLM-assisted annotation through ceLLMarkup(), or create a structured portable prompt with typoPrompt() and take it to a suitable model of your choice.

Do I have to use an LLM?

No. LLM functionality is optional. ClustoCell, MarkoCell/MarkoClust, MarkerDB annotation and the core R workflows remain usable independently of an LLM. The Agent and LLM-based annotation routes are additional interfaces.

What is the CelliVerse Agent?

It is an optional local browser interface backed by R that lets users request supported CelliVerse tasks in natural language. It can be configured with supported cloud or local model providers. It is intended to make the package more approachable while preserving the standard scripted interface for reproducibility.

Can I try CelliVerse without installing R?

Yes. The Hugging Face Space provides a lightweight browser-based demonstration using precomputed ClustoCell outputs, so you can explore clusters, sub-clusters and marker tables before installing R locally.

Where are the analysis scripts and marker database files?

The dedicated CelliVerse-Project GitHub repository contains the prepared human/mouse positive and negative marker database files and R Markdown scripts used for the analyses and figures. Public datasets are additionally archived on Zenodo.

Explore the universe of cell identity.

Start with the package, inspect the full vignette, or try the browser demo before installing anything.

Get CelliVerse Try demo