Package {celliverse}

Type:	Package
Title:	An Ecosystem for Exploring the Universe of Single-Cell Data
Language:	en-US
Version:	0.0.2
Description:	Contains functions for single-cell RNA sequencing data analysis. It provides core functionalities for clustering cells, identifying markers for predefined clusters, performing sub-clustering of major cell populations, and discovering markers within custom-selected subsets of cells. 'CelliVerse' also includes methods for analyzing cluster similarity and generating intuitive visualizations. Designed to be independent of library size and other sample- or cell-level confounding effects, 'CelliVerse' ensures reliable and interpretable results across a wide range of datasets. Fred Viole and David Nawrocki (2013, ISBN:1490523995). Csardi G, Nepusz T (2006). "The 'igraph' software package for complex network research." InterJournal, Complex Systems, 1695. Adopted algorithms and sources are referenced in function document.
Imports:	Matrix, Seurat, SummarizedExperiment, scales, ggplot2, magrittr, igraph, cli, dplyr, data.table, stringr, tidyr, RColorBrewer, ggnewscale, patchwork, tidyselect, methods, Rcpp
LinkingTo:	Rcpp, RcppEigen
Suggests:	R.rsp, htmltools, knitr, rmarkdown, plumber, jsonlite, httr2, processx, later, promises, callr, httpuv, openssl, fs, svglite, zip, withr, SeuratObject, ComplexHeatmap, hdf5r, rstudioapi
Depends:	R (≥ 4.1.0)
URL:	https://github.com/asalavaty/celliverse, https://asalavaty.github.io/celliverse/
BugReports:	https://github.com/asalavaty/celliverse/issues
License:	GPL-3
Encoding:	UTF-8
LazyData:	true
LazyDataCompression:	bzip2
RoxygenNote:	7.3.3
VignetteBuilder:	R.rsp
NeedsCompilation:	yes
Packaged:	2026-09-03 07:49:15 UTC; salavatyadrian
Author:	Adrian Salavaty [aut, cre]
Maintainer:	Adrian Salavaty <abbas.salavaty@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-12 13:40:14 UTC

celliverse: A toolkit for single-cell clustering, marker discovery, and annotation

Description

celliverse is a robust and versatile toolkit for the analysis of single-cell data (e.g., single-cell RNA sequencing). The package provides methods for data-driven cell clustering, marker prioritization, sub-clustering of major populations, cell-type annotation, similarity analysis, and visualization.

The methods implemented in celliverse are designed to be robust to library size variation and other common sample- or cell-level confounders, enabling reliable and interpretable analyses across diverse datasets.

Details

• Package: celliverse

• Type: Package

• License: GPL-3

Note

Individual algorithms and data sources are documented at the function level.

Author(s)

Adrian Salavaty (www.ASalavaty.com)

Maintainer: Adrian Salavaty abbas.salavaty@gmail.com

References

Hao et al. Dictionary learning for integrative, multimodal and scalable single-cell analysis. Nature Biotechnology (2023).

Csardi G, Nepusz T (2006). The igraph software package for complex network research. InterJournal, Complex Systems, 1695.

See Also

• https://github.com/asalavaty/celliverse

Add ClustoCell cluster annotations to a Seurat or SingleCellExperiment object

Description

Adds major cluster and/or sub-cluster labels stored in a ClustoCell object to the cell-level metadata of a Seurat or SingleCellExperiment object.

Usage

addClustoData(
  obj,
  clustoCell,
  add_major_clusters = TRUE,
  add_sub_clusters = TRUE,
  major_cluster_name = "ClustoCell_Clusters",
  sub_cluster_name = "ClustoCell_SubClusters"
)

Arguments

Details

This function transfers clustering results obtained using clustoCell() or markoClust() into an existing single-cell object by appending cluster labels as metadata columns. Major clusters and sub-clusters can be added independently and assigned custom column names.

Value

The input object obj with additional metadata columns containing ClustoCell cluster annotations.

See Also

clustoCell, markoClust

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small_cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = TRUE,
  num_threads = 1,
  verbose = FALSE
)

pbmc_small <- addClustoData(
  obj = pbmc_small,
  clustoCell = pbmc_small_cc,
  add_major_clusters = TRUE,
  add_sub_clusters = TRUE
)

Add TypoClust cell type annotations to a single-cell object

Description

Adds inferred cell type annotations from a TypoClust object to the metadata of a Seurat or SingleCellExperiment object.

Usage

addTypoData(
  obj,
  typoClust,
  clusters,
  rank_thresh = 1,
  refine = TRUE,
  refine_thresh = 1,
  outNames = NULL
)

Arguments

Details

Cell type labels are assigned to specified cluster or subset columns and appended as new metadata columns. Multiple ranked cell types can be added, and hierarchical refinement can be applied to obtain more specific cell type annotations.

Value

The input object obj with additional metadata columns containing inferred cell type annotations.

See Also

typoClust, typoClustVis

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

pbmc_small <- addClustoData(
  obj = pbmc_small,
  clustoCell = cc,
  add_major_clusters = TRUE,
  add_sub_clusters = FALSE
)

tc <- typoClust(
  objects = list(cc),
  tissue = "Blood",
  condition = "Healthy",
  use_neg_markers = FALSE,
  thresh = 10,
  mode = "markerDB",
  species = "human",
  verbose = FALSE
)

pbmc_small <- addTypoData(
  obj = pbmc_small,
  typoClust = tc,
  clusters = "ClustoCell_Clusters",
  refine = FALSE
)

LLM-based cell-type annotation of clusters or marker sets (ceLLMarkup)

Description

Annotates cell clusters, sub-clusters, or arbitrary marker sets by asking a large language model to name the most likely cell type for each set, given its marker genes and an optional tissue/condition/species context. Returns ranked candidate cell types per set in a TypoClust-compatible object.

Exactly one of marker_set_list, panels, or seuratClusters must be provided.

Usage

ceLLMarkup(
  sample_source = NULL,
  feature_type = "gene",
  marker_set_list = NULL,
  panels = NULL,
  seuratClusters = NULL,
  padj = 0.05,
  logFC = NULL,
  tissue = NULL,
  condition = NULL,
  species = c("human", "mouse"),
  provider = "ollama",
  model,
  api_key = NULL,
  host = NULL,
  temperature = 0.2,
  top_k = 3L,
  n_markers = 25L,
  max_retries = 1L,
  inherit_major_clusters = TRUE,
  verbose = TRUE
)

Arguments

Value

An object of class TypoClust: a list with cell_types (named list of ranked annotation data.frames) and metadata.

Examples

## Not run: 
# Requires an externally running Ollama server and an installed
# qwen3:8b model.
markers <- list(
  Cluster1 = c("CD3D", "CD3E", "TRBC1", "IL7R", "LTB"),
  Cluster2 = c("MS4A1", "CD79A", "CD37", "CD74", "HLA-DRA")
)

annotations <- ceLLMarkup(
  panels = markers,
  sample_source = "human peripheral blood",
  feature_type = "gene",
  tissue = "Blood",
  condition = "Healthy",
  species = "human",
  provider = "ollama",
  model = "qwen3:8b",
  top_k = 3
)

## End(Not run)
  

Clustering and marker discovery for single-cell data using EWCSR-based similarity

Description

Performs unsupervised clustering of single-cell data using expression-weighted centered scaled ranks (EWCSR), followed by identification of cluster-specific markers and optional sub-clustering. The function supports direct clustering on full datasets or scalable analysis via data sketching with subsequent label transfer to the full dataset.

Usage

clustoCell(
  data,
  assay = "RNA",
  layer = "counts",
  norm_assay = "RNA",
  norm_layer = "data",
  log1p = TRUE,
  subset_to_HVG = FALSE,
  hvg_selection.method = c("vst", "mean.var.plot", "dispersion"),
  hvg_var_thresh = 1,
  high_quantile = 0.25,
  low_quantile = 0.25,
  gini_thresh = 0.5,
  identify_subclusters = TRUE,
  sketch = FALSE,
  sketch_ncells = 5000L,
  label_transfer_method = c("ewcsr-cor", "seurat-project", "ewcsr-red-cor", "seurat-knn"),
  sketch_pca_dims = 30,
  refine_transferred_subClusters = FALSE,
  noise_feature_thresh = 4,
  random_marker_thresh = 5,
  mr_thresh = NULL,
  isolated_cluster_thresh = 5,
  leiden_obj_function = c("modularity", "CPM"),
  leiden_resolution = 1,
  leiden_n_iterations = 5,
  subcluster_resolution_weight = 0.75,
  num_threads = -1,
  seed = 121,
  verbose = TRUE
)

Arguments

Details

If sketch = TRUE, a representative subset of cells is sampled from the input data and used for clustering. Labels are transferred back to the full dataset using the method specified by label_transfer_method. The "seurat-project" and "seurat-knn" methods operate on the original expression matrix rather than the EWCSR representation. The supplied expression data may consist of raw counts, log-normalized expression values, or SCTransform-normalized data, provided that the sketched and full datasets were processed using the same normalization strategy. These methods leverage Seurat's native label transfer workflows (ProjectData, FindTransferAnchors, and TransferData) and do not require integer count matrices.

Value

An object of class ClustoCell containing:

• major and sub-cluster assignments

• EWCSR-transformed data

• cluster- and subcluster-specific marker tables

• similarity and mutual-rank matrices

See Also

typoClust, markoClust

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

Transfer ClustoCell cluster labels to a full-resolution dataset

Description

Transfers major and sub-cluster labels from a ClustoCell object generated on a sketched (subsampled) dataset to a full-resolution dataset using EWCSR-based correlation or Seurat-based projection and anchor transfer strategies.

Usage

clustoCell_TransferLabel(
  clustoCell,
  query_ewcsr_mat = NULL,
  query_expr_mat = NULL,
  assay = "RNA",
  layer = "counts",
  method = c("ewcsr-cor", "seurat-project", "ewcsr-red-cor", "seurat-knn"),
  dims = 30,
  num_threads = -1,
  inherit_major_clusters = TRUE,
  seed = 121,
  verbose = TRUE
)

Arguments

Details

The "seurat-project" and "seurat-knn" methods operate on the original expression matrix ('query_expr_mat') rather than the EWCSR representation. The supplied expression data may consist of raw counts, log-normalized expression values, or SCTransform-normalized data, provided that the sketched and full datasets were processed using the same normalization strategy. These methods leverage Seurat's native label transfer workflows (ProjectData, FindTransferAnchors, and TransferData) and do not require integer count matrices.

Value

An updated object of class ClustoCell containing transferred major and sub-cluster labels for the full dataset.

Examples

utils::data("pbmc_small", package = "SeuratObject")

reference_cells <- colnames(pbmc_small)[1:60]

pbmc_reference <- pbmc_small[, reference_cells]

cc_reference <- clustoCell(
  data = pbmc_reference,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

full_counts <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

full_ewcsr <- ewcsr.sparse(full_counts, num_threads = 1)

cc_full <- clustoCell_TransferLabel(
  clustoCell = cc_reference,
  query_ewcsr_mat = full_ewcsr,
  method = "ewcsr-cor",
  num_threads = 1,
  verbose = FALSE
)

Compute expression-weighted centered scaled ranks (EWCSR)

Description

Computes expression-weighted centered scaled ranks for a sparse or dense expression matrix, calculated per column (cell).

Usage

ewcsr.sparse(mat, num_threads = -1L)

Arguments

Details

EWCSR transformation emphasizes relatively high and low expression features within each cell while accounting for expression magnitude. The output matrix retains the same dimensions as the input.

Value

A matrix of EWCSR-transformed values with the same dimensions as mat.

See Also

gini.ewcsr.fs, markoCell

Examples

utils::data("pbmc_small", package = "SeuratObject")

mat <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

ewcsr_mat <- ewcsr.sparse(mat, num_threads = 1)

Inspect the Membership of Features Across ClustoCell Results

Description

featureInspect() searches one or more features across all marker collections contained within a ClustoCell object, including global feature collections, cross-cluster markers, major cluster-specific markers, and sub-cluster-specific markers. All matches are returned in a single long-format data frame containing the feature level, membership, marker type, Gini score, purity, and rank. Optionally, a publication-quality ggplot2 visualisation summarising feature memberships can also be generated.

Usage

featureInspect(
  clustoCell,
  features,
  level = NULL,
  type = NULL,
  sort_by = c("input", "rank", "gini"),
  plot = FALSE,
  title = NULL,
  subtitle = NULL,
  tag = NULL,
  nrow_panels = NULL,
  dotsize = 3,
  show_purity = TRUE,
  class_palette = NULL,
  color_low = "steelblue",
  color_high = "firebrick",
  panel_border_color = "black",
  panel_border_size = 0.5,
  axis_text_size = 8,
  axis_title_size = 9,
  plot_margin_right = 10,
  xlab = "Rank",
  ylab = "Feature",
  show_legend = TRUE,
  legend_position = "right",
  legend_box = "vertical",
  legend_box_just = "left"
)

Arguments

Details

Rank interpretation. The Rank column reflects the rank of the feature within its specific collection (i.e. within the combination of Level, Membership, and Type), as assigned by clustoCell or markoClust. It does not represent the row position in the output table returned by featureInspect(). A feature ranked 1st in cluster C1 positive markers and 5th in sub-cluster C1-Sub1 medium markers will appear in two separate rows with Rank values of 1 and 5, respectively.

Dot size in the plot. When plot = TRUE, dot size encodes the inverted Gini score: a lower Gini score indicates a purer marker and is represented by a larger dot. The size legend labels display the original Gini score values for interpretability. Features without a Gini score (i.e. global features stored in globally_pure_ranked, globally_pure_high, or globally_pure_medium) are rendered as large, semi-transparent grey dots with a heavier border stroke to signal that their size carries no quantitative meaning. These features are also plotted at x = 0 because no rank is assigned to them; the 0 tick label is suppressed in panels that contain only unranked features to avoid misinterpretation.

Level and type filtering. When level and/or type are specified, only rows matching the requested value(s) are returned. The two filters are applied sequentially and independently: level is applied first, then type. Specifying type = "Pure" expands to all three global pure-type categories ("Pure Ranked", "Pure High", "Pure Medium") but does not override the level filter — if level is set to a non-global level, the combination will yield zero rows (with a warning). If no features are found after filtering, a zero-row data.frame is returned with a warning rather than an error, allowing featureInspect() to be used safely inside loops or lapply() calls.

Value

If plot = FALSE

A data.frame with one row for each occurrence of each queried feature across all (or the selected) marker collections. Columns are:

Feature

Feature name (character).

Level

Hierarchical level at which the feature was found: "Global", "Cross-cluster", "Major cluster", or "Sub-cluster" (character).

Membership

The specific collection in which the feature was found, e.g. "Global Features", "Cross-cluster Marker", "C1", or "C1-Sub1" (character).

Type

Marker type: "Pure High", "Pure Medium", "Pure Ranked", "Positive", "Negative", or "Medium" (character).

Gini_Score

Gini score of the feature within the collection (numeric). NA for global features.

Purity

Purity of the feature within the collection (numeric). NA for global and cross-cluster features.

Rank

Rank of the feature within its specific collection (integer). NA for global features. See Details.

If no queried feature is found in any collection (or in the specified level(s)), a zero-row data.frame with the above columns is returned.

If plot = TRUE

A named list with two elements:

$table

The results data.frame described above.

$plot

A ggplot object visualising the identified feature memberships as a dot plot faceted by Membership. Dot position (x-axis) encodes Rank, dot size encodes the inverted Gini_Score (larger = purer), dot shape encodes Type, and dot colour encodes Purity (or Type when show_purity = FALSE). Features without a Gini score are shown as large semi-transparent grey dots. See Details.

See Also

clustoCell, markoClust

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

markers <- getDatasetMarkers(
  obj = cc,
  sub_clusters = FALSE,
  pos_thresh = 5,
  verbose = FALSE
)

features <- utils::head(
  markers$combined_markers,
  3
)

result <- featureInspect(
  clustoCell = cc,
  features = features
)

result

Collect marker genes from a ClustoCell object

Description

Extracts positive, negative, and/or medium markers from major clusters and sub-clusters stored in a ClustoCell object.

Usage

getDatasetMarkers(
  obj,
  clusters = TRUE,
  sub_clusters = TRUE,
  positive_markers = TRUE,
  negative_markers = FALSE,
  medium_markers = FALSE,
  thresh_mode = c("n", "rank"),
  pos_thresh = 25,
  neg_thresh = 20,
  med_thresh = 10,
  verbose = TRUE
)

Arguments

Details

Marker selection can be controlled using rank-based or fixed-size thresholds. Separate thresholds are applied for positive, negative, and medium markers.

Value

An object of class DatasetMarkers.

See Also

clustoCell, markoClust

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

markers <- getDatasetMarkers(
  obj = cc,
  sub_clusters = FALSE,
  pos_thresh = 20,
  verbose = FALSE
)

Feature selection using Gini coefficient on EWCSR-transformed data

Description

Performs feature selection based on the Gini inequality coefficient computed on expression-weighted centered scaled rank (EWCSR) data.

Usage

gini.ewcsr.fs(
  mat,
  gini_thresh = 0.5,
  ewcsr_high_thresh = NULL,
  ewcsr_low_thresh = NULL,
  noise_thresh = NULL,
  num_threads = -1
)

Arguments

Details

Features are categorized into specific, non-specific, and no-occurrence groups based on Gini thresholds and optional binarization of EWCSR values.

Value

A list containing specific_features, non_specific_features, and no_occurrence.

See Also

ewcsr.sparse, gini.rank.fs

Examples

utils::data("pbmc_small", package = "SeuratObject")

mat <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

fs <- gini.ewcsr.fs(
  mat,
  num_threads = 1
)

Feature selection using Gini coefficient on ranked expression data

Description

Identifies specific and non-specific features based on the Gini inequality coefficient computed on ranked expression values.

Usage

gini.rank.fs(mat, gini_thresh = 0.5, noise_thresh = NULL, num_threads = -1)

Arguments

Details

This method removes globally low-ranked features while retaining features with consistently high ranks across cells for downstream analysis.

Value

A list containing specific_features, non_specific_features, and no_occurrence.

See Also

gini.ewcsr.fs

Examples

utils::data("pbmc_small", package = "SeuratObject")

mat <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

fs <- gini.rank.fs(
  mat,
  num_threads = 1
)

Prepare this machine to run the CelliVerse agent

Description

The agent is cloud-first: it runs out of the box with a cloud provider (set an API key in Settings) and needs no local model. This installer verifies the R web-stack, creates tools::R_user_dir("celliverse", "cache") + a default config, and optionally sets up a local runtime - it detects Ollama (and pulls a tier model when found) and detects LM Studio (via its lms CLI). A local model is never required; you can install Ollama and/or LM Studio at any time later and switch providers in Settings. The config default_model is only pointed at a local Ollama model when Ollama is actually present (or you pass model = explicitly); otherwise the cloud default is left untouched.

Usage

install_celliverse_agent(
  tier = c("auto", "light", "recommended", "strong", "both", "all"),
  model = NULL,
  pull_model = TRUE
)

Arguments

Value

invisibly, a named list summarising what was found/done.

Compute Jaccard similarity for sparse matrices

Description

Computes pairwise Jaccard similarity between columns of a sparse matrix.

Usage

jaccard.sparse(mat, num_threads = -1)

Arguments

Value

A numeric matrix of Jaccard similarity scores.

See Also

mutual.rank

Examples

utils::data("pbmc_small", package = "SeuratObject")

mat <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

binary_mat <- mat
binary_mat@x[] <- 1

jac <- jaccard.sparse(
  binary_mat,
  num_threads = 1
)

Cell-type marker database

Description

A curated database of positive and negative cell-type marker genes for human and mouse, stored in sparse matrix format. This dataset is used internally by typoClust() for marker-based cell-type annotation.

Format

An object of class CelliVerse_Data, implemented as a named list with two elements:

human

A list containing human marker databases:

positive_db

An object of class CelliVerse_Sparse_Data wrapping a sparse dgCMatrix of dimensions 16,899 genes × 9,410 cell types.

negative_db

An object of class CelliVerse_Sparse_Data wrapping a sparse dgCMatrix of dimensions 329 genes × 93 cell types.

mouse

A list containing mouse marker databases:

positive_db

An object of class CelliVerse_Sparse_Data wrapping a sparse dgCMatrix of dimensions 4,779 genes × 2,112 cell types.

negative_db

An object of class CelliVerse_Sparse_Data wrapping a sparse dgCMatrix of dimensions 32 genes × 33 cell types.

Details

Rows correspond to marker genes and columns correspond to annotated cell types. Matrix values encode marker presence or strength as defined during database construction. Sparse representation is used to minimize memory usage.

Source

Curated from published cell-type marker resources and expert annotation.

See Also

typoClust, markerDictionary, tissueCondition_types

Marker gene dictionary

Description

A species-specific dictionary mapping marker identifiers to standardized gene annotations, including gene symbols, aliases, and database identifiers. This dataset supports marker harmonization and identifier resolution within the celliverse framework.

Format

An object of class CelliVerse_Data, implemented as a named list with two elements:

human

A data frame with 20,887 rows and 6 variables:

Marker

Internal marker identifier

Symbol

Official gene symbol

Alias

Alternative gene symbols or aliases

Entrez

Entrez Gene identifier

Ensembl

Ensembl gene identifier

UniProt

UniProt protein identifier

mouse

A data frame with 4,779 rows and 6 variables:

Marker

Internal marker identifier

Symbol

Official gene symbol

Alias

Alternative gene symbols or aliases

Entrez

Entrez Gene identifier

Ensembl

Ensembl gene identifier

UniProt

UniProt protein identifier

Details

This dictionary is used to standardize marker gene identifiers across datasets and species, enabling consistent matching between user-provided markers and curated cell-type marker databases.

Source

Integrated from public gene annotation resources including Ensembl, Entrez Gene, and UniProt.

See Also

markerDB, typoClust

Assess marker purity across clusters or cell subsets

Description

Quantifies marker purity by evaluating expression specificity within clusters or user-defined cell subsets.

Usage

markerPurity(
  data,
  assay = "RNA",
  layer = "counts",
  desired_markers = NULL,
  cluster_labels = NULL,
  desired_clusters = NULL,
  desired_cells = NULL,
  log1p = TRUE,
  remove_quiescent_cells = TRUE,
  high_quantile = 0.25,
  low_quantile = 0.25,
  noise_feature_thresh = 4,
  num_threads = -1,
  seed = 121,
  verbose = TRUE
)

Arguments

Details

Marker purity is assessed using EWCSR-based filtering and supports both Seurat objects and matrix-based inputs.

Value

An object of class MarkerPurity.

See Also

markoCell, getDatasetMarkers

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small$example_clusters <- as.character(
  SeuratObject::Idents(pbmc_small)
)

cluster_ids <- utils::head(
  unique(pbmc_small$example_clusters),
  2
)

mp <- markerPurity(
  data = pbmc_small,
  desired_markers = rownames(pbmc_small)[1:10],
  cluster_labels = "example_clusters",
  desired_clusters = cluster_ids,
  num_threads = 1,
  verbose = FALSE
)

Rank markers for clusters, cell subsets, or individual cells

Description

Identifies and ranks positive and negative marker genes for a specified set of cells, which may correspond to clusters, sub-clusters, arbitrary cell subsets, or even single cells. Marker ranking is based on expression-weighted centered scaled ranks (EWCSR), with Gini-based specificity assessment, and noise suppression.

Usage

markoCell(
  data,
  assay = "RNA",
  layer = "counts",
  norm_assay = "RNA",
  norm_layer = "data",
  cluster_labels = NULL,
  desired_clusters = NULL,
  desired_cells = NULL,
  log1p = TRUE,
  remove_quiescent_cells = TRUE,
  high_quantile = 0.25,
  low_quantile = 0.25,
  subset_to_HVG = FALSE,
  hvg_selection.method = c("vst", "mean.var.plot", "dispersion"),
  hvg_var_thresh = 1,
  gini_thresh = 0.5,
  noise_feature_thresh = 4,
  random_marker_thresh = 5,
  num_threads = -1,
  seed = 9999,
  verbose = TRUE
)

Arguments

Details

When subset_to_HVG = TRUE, highly variable genes are detected using the normalized assay and layer specified by norm_assay and norm_layer. Gini-based filtering is applied to identify global (non-specific) versus specific markers.

Value

An object of class "MarkoCell" containing ranked marker tables and associated statistics for each requested cell set.

See Also

markoClust, markerPurity, gini.ewcsr.fs

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small$example_clusters <- as.character(
  SeuratObject::Idents(pbmc_small)
)

cluster_ids <- utils::head(
  unique(pbmc_small$example_clusters),
  2
)

mc <- markoCell(
  data = pbmc_small,
  cluster_labels = "example_clusters",
  desired_clusters = cluster_ids,
  num_threads = 1,
  verbose = FALSE
)

Evaluate and refine cell clusters using marker ranking and graph partitioning

Description

Identifies markers in predefined cell clusters, and optionally identifying sub-clusters using Leiden community detection. Supports large datasets via uniform sketching with label transfer back to the full dataset.

Usage

markoClust(
  data,
  assay = "RNA",
  layer = "counts",
  norm_assay = "RNA",
  norm_layer = "data",
  cluster_labels,
  log1p = TRUE,
  remove_quiescent_cells = TRUE,
  high_quantile = 0.25,
  low_quantile = 0.25,
  subset_to_HVG = FALSE,
  hvg_selection.method = c("vst", "mean.var.plot", "dispersion"),
  hvg_var_thresh = 1,
  gini_thresh = 0.5,
  sketch = FALSE,
  sketch_fraction = 0.5,
  label_transfer_method = c("ewcsr-cor", "seurat-project", "ewcsr-red-cor", "seurat-knn"),
  sketch_pca_dims = 30,
  noise_feature_thresh = 4,
  random_marker_thresh = 5,
  mr_thresh = NULL,
  isolated_cluster_thresh = 5,
  leiden_obj_function = c("modularity", "CPM"),
  leiden_resolution = 0.75,
  leiden_n_iterations = 5,
  identify_subclusters = FALSE,
  num_threads = -1,
  seed = 121,
  verbose = TRUE
)

Arguments

Details

If sketch = TRUE, a representative subset of cells is sampled from each cluster and used for sub-clustering. Labels are transferred back to the full dataset using the method specified by label_transfer_method. The "seurat-project" and "seurat-knn" methods operate on the original expression matrix rather than the EWCSR representation. The supplied expression data may consist of raw counts, log-normalized expression values, or SCTransform-normalized data, provided that the sketched and full datasets were processed using the same normalization strategy. These methods leverage Seurat's native label transfer workflows (ProjectData, FindTransferAnchors, and TransferData) and do not require integer count matrices.

Value

An object of class "ClustoCell" containing refined clusters, sub-clusters, marker tables, and similarity structures.

See Also

markoCell, addClustoData

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small$example_clusters <- as.character(
  SeuratObject::Idents(pbmc_small)
)

cc <- markoClust(
  data = pbmc_small,
  cluster_labels = "example_clusters",
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

Visualize cluster and cell-subset markers

Description

Generates a faceted dot plot for visualizing marker genes across clusters, sub-clusters, or cell subsets stored in a ClustoCell or MarkoCell object. Marker selection can be controlled by rank or by selecting the top n markers per group. Dot size and color can represent marker purity or marker class.

Usage

markoClustVis(
  obj,
  desired_sets = NULL,
  show_pos_markers = TRUE,
  show_neg_markers = FALSE,
  show_med_markers = FALSE,
  thresh_mode = c("n", "rank"),
  thresh = 5,
  title = NULL,
  subtitle = NULL,
  tag = NULL,
  nrow_panels = NULL,
  dotsize = 2,
  show_purity = TRUE,
  class_palette = NULL,
  color_low = "blue",
  color_high = "red",
  panel_border_color = "black",
  panel_border_size = 0.5,
  axis_text_size = 7,
  axis_title_size = 8,
  plot_margin_right = 10,
  xlab = "Rank",
  ylab = "Marker",
  show_legend = TRUE,
  legend_box = "vertical",
  legend_box_just = "left",
  legend_position = "right"
)

Arguments

Details

This function provides a flexible visualization for exploring marker genes identified in clustering analyses. Marker selection can be based on rank or a fixed number of top markers. The resulting plot is faceted by cluster or subset, enabling comparison across groups.

When show_purity = TRUE, a continuous color scale is used to represent marker purity. Otherwise, discrete colors are used to represent marker classes (e.g., positive, negative, medium).

Value

A ggplot2 object showing a faceted dot plot of selected markers across clusters, sub-clusters, or cell subsets.

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small$example_clusters <- as.character(
  SeuratObject::Idents(pbmc_small)
)

cc <- markoClust(
  data = pbmc_small,
  cluster_labels = "example_clusters",
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

plt <- markoClustVis(
  obj = cc,
  show_pos_markers = TRUE,
  show_neg_markers = FALSE,
  thresh_mode = "n",
  thresh = 2
)

plt

Compute mutual rank from a similarity matrix

Description

Computes the mutual rank (MR) for all pairs in a symmetric similarity or dissimilarity matrix, a robust measure frequently used to stabilize pairwise similarity relationships.

Usage

mutual.rank(mat, num_threads = -1)

Arguments

Value

A numeric matrix of mutual ranks with the same dimensions as mat.

See Also

jaccard.sparse, markoClust

Examples

utils::data("pbmc_small", package = "SeuratObject")

mat <- SeuratObject::LayerData(
  pbmc_small,
  assay = "RNA",
  layer = "counts"
)

binary_mat <- sign(mat)

similarity_matrix <- jaccard.sparse(
  binary_mat,
  num_threads = 1
)

mr <- mutual.rank(
  similarity_matrix,
  num_threads = 1
)

Launch the CelliVerse agent (API + UI)

Description

Starts the local plumber API, serves the prebuilt React UI from 'inst/react-app/', binds to localhost, and (optionally) opens a browser. The agent runs cloud-first: no local model is required — pick a cloud provider + API key in Settings, or install Ollama / LM Studio later for fully-offline local models.

Usage

run_celliverse_agent(
  port = NULL,
  host = "127.0.0.1",
  provider = NULL,
  model = NULL,
  browser = interactive(),
  background = FALSE,
  port_scan = TRUE,
  max_port_tries = 20L
)

Arguments

Value

invisibly, the plumber router (foreground) or a process handle (background).

Save a TypoPrompt to a file

Description

Saves a TypoPrompt object as either its exact plain-text prompt or a self-contained interactive HTML page.

Usage

saveTypoPrompt(x, file, format = c("txt", "html"))

Arguments

Value

Invisibly returns the normalized output file path.

See Also

typoPrompt

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

desired_set <- utils::head(
  sort(unique(as.character(cc$clusters$major_clusters))),
  1
)

prompt <- typoPrompt(
  object = cc,
  desired_sets = desired_set,
  sample_source = "human peripheral blood",
  tissue = "Blood",
  condition = "Healthy",
  species = "human",
  use_neg_markers = FALSE,
  thresh = 10,
  verbose = FALSE
)

txt_file <- tempfile(fileext = ".txt")

saveTypoPrompt(
  prompt,
  file = txt_file,
  format = "txt"
)

Visualize per-signature marker expression across clusters

Description

Generates a dot heatmap summarizing expression of signature-associated features across clusters.

Usage

signatureDotHeatmap(
  seurat_obj,
  cluster_col,
  row_data,
  features_col = NULL,
  signature_col = NULL,
  cell_type_colors = NULL,
  signature_colors = NULL,
  tag = NULL,
  tile_palette = RColorBrewer::brewer.pal(9, "YlOrRd"),
  tile_alpha_range = c(0.15, 0.65),
  dot_size_factor = 2,
  dot_range = c(0.5, 3),
  signature_label_size = 3.3,
  feature_label_size = 6,
  feature_label_angle = 45,
  show_cluster_labels = FALSE,
  show_signature_strip = TRUE,
  show_signature_labels = TRUE,
  show_cluster_strip = TRUE,
  show_cluster_legend = TRUE,
  show_signature_legend = FALSE,
  legend_ncol = 2,
  expression_legend_title = "Expression",
  percent_legend_title = "Percent\nExpressed",
  tile_fill_legend_title = NULL,
  signature_legend_title = "Signature",
  vline_color = "black",
  vline_width = 0.15,
  block_border_color = "grey90",
  feature_label_face = "plain"
)

Arguments

Details

Dot size typically encodes the percentage of cells expressing a feature, while color intensity reflects average expression.

Value

A ggplot2 object.

See Also

typoClustVis, markoCell

Examples

utils::data("pbmc_small", package = "SeuratObject")

pbmc_small$example_clusters <- as.character(
  SeuratObject::Idents(pbmc_small)
)

features <- rownames(pbmc_small)[1:6]

signatures <- data.frame(
  Features = features,
  Signature = rep(
    c("Signature 1", "Signature 2"),
    each = 3
  )
)

p <- signatureDotHeatmap(
  seurat_obj = pbmc_small,
  cluster_col = "example_clusters",
  row_data = signatures,
  features_col = "Features",
  signature_col = "Signature"
)

p

Tissue and condition reference catalog

Description

A reference catalog of tissues and disease conditions for human and mouse, used to contextualize cell-type annotation by tissue and pathological state.

Format

An object of class CelliVerse_Data, implemented as a named list with two elements:

human

A list containing:

all_tissues

Character vector of all supported tissues (length 396)

healthy_tissue

Character vector of healthy tissues (length 367)

diseased_tissue

Character vector of diseased tissues (length 103)

all_conditions

Character vector of all supported conditions (length 265)

diseased_tissueCondition

A data frame with two variables:

Tissue

Tissue name

Condition

Associated disease condition

mouse

A list containing:

all_tissues

Character vector of all supported tissues (length 110)

healthy_tissue

Character vector of healthy tissues (length 108)

diseased_tissue

Character vector of diseased tissues (length 19)

all_conditions

Character vector of all supported conditions (length 51)

diseased_tissueCondition

A data frame with two variables:

Tissue

Tissue name

Condition

Associated disease condition

Details

This dataset is used by typoClust() to restrict or guide cell-type annotation according to tissue context and disease state.

Source

Curated from public tissue ontologies and disease annotation resources.

See Also

typoClust, markerDB

Cell type annotation of clusters, sub-clusters, or cell subsets

Description

Annotates clusters, sub-clusters, or arbitrary cell subsets using curated cell-type marker databases or large language model (LLM)–based annotation. Annotation can be performed either from marker results stored in ClustoCell or MarkoCell objects, or directly from user-specified positive and/or negative marker panels.

Usage

typoClust(
  objects = NULL,
  desired_sets = NULL,
  tissue = NULL,
  condition = NULL,
  use_pos_markers = TRUE,
  use_neg_markers = TRUE,
  desired_pos_markers = NULL,
  desired_neg_markers = NULL,
  thresh_mode = c("n", "rank"),
  thresh = 20,
  mode = c("markerDB", "ceLLMarkup"),
  inherit_major_clusters = TRUE,
  inherit_score_ratio = 0.5,
  species = c("human", "mouse"),
  sample_source = NULL,
  feature_type = "gene",
  llm_provider = "ollama",
  llm_model = NULL,
  llm_api_key = NULL,
  llm_host = NULL,
  llm_top_k = 3,
  verbose = TRUE
)

Arguments

Details

typoClust() identifies candidate cell types for each target set by comparing positive and/or negative marker genes against tissue- and condition-aware cell-type marker databases. Users may restrict annotation to specific tissues or conditions, control the number of markers used per cluster, and choose between rank-based or fixed-size marker selection.

Exactly one of the following inputs must be provided:

• One or more ClustoCell or MarkoCell objects via objects

• User-defined positive and/or negative marker panels via desired_pos_markers and/or desired_neg_markers

Value

An object of class TypoClust containing ranked cell-type annotations, supporting marker evidence, and summary statistics for each annotated set.

See Also

typoClustVis, markoCell, markoClust, clustoCell

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

desired_set <- utils::head(
  sort(unique(as.character(cc$clusters$major_clusters))),
  1
)

tc <- typoClust(
  objects = list(cc),
  desired_sets = desired_set,
  tissue = "Blood",
  condition = "Healthy",
  use_neg_markers = FALSE,
  thresh = 10,
  mode = "markerDB",
  species = "human",
  verbose = FALSE
)

Visualization of TypoClust cell-type annotations

Description

Visualizes cell-type annotation results generated by typoClust() using a composite layout combining label, tile, and dot plots.

Usage

typoClustVis(
  typoClust,
  desired_sets = NULL,
  rank_thresh = 1,
  refine = TRUE,
  refine_thresh = 1,
  order_by = c("Cell Type", "Cluster", "Combined Score", "Combined Count", "Purity"),
  title = NULL,
  subtitle = NULL,
  tag = NULL,
  cellType_palette = NULL,
  flip = FALSE,
  tile_width = 0.2,
  tile_height = 0.6,
  tile_xlim = c(0.5, 1.5),
  tile_legend_title = "Cell Type",
  dot_color_low = "blue",
  dot_color_high = "red",
  dot_panel_border_color = "black",
  dot_panel_border_size = 0.5,
  dot_axis_text_size = 11,
  dot_axis_title_size = 12,
  dot_plot_margin_right = 10,
  dot_xlab = "Lead Cell Type Score",
  dot_size_title = "Combined\nCount",
  dot_color_title = "Avg Purity",
  label_size = 3,
  label_padding_lines = 0.5,
  legend_box = "vertical",
  legend_box_just = "left",
  legend_position = "right"
)

Arguments

Details

typoClustVis() displays the top-ranked cell types per cluster or cell subset, optionally refining annotations to deeper hierarchical levels. The visualization integrates categorical labels, quantitative annotation scores, marker support, and purity metrics.

Value

A ggplot2 object representing the combined visualization.

See Also

typoClust, signatureDotHeatmap

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

desired_sets <- utils::head(
  sort(unique(as.character(cc$clusters$major_clusters))),
  2
)

tc <- typoClust(
  objects = list(cc),
  desired_sets = desired_sets,
  tissue = "Blood",
  condition = "Healthy",
  use_neg_markers = FALSE,
  thresh = 10,
  mode = "markerDB",
  species = "human",
  verbose = FALSE
)

p <- typoClustVis(
  typoClust = tc,
  rank_thresh = 1,
  refine = FALSE,
  order_by = "Cluster"
)

p

Generate an LLM-ready prompt for cell-type annotation

Description

Generates a structured, copy-and-paste-ready prompt for annotation of clusters, sub-clusters, or cell subsets using any chatbot or large language model (LLM). Marker information is extracted directly from a ClustoCell or MarkoCell object and combined with optional biological context such as sample source, tissue, condition, and species.

In interactive sessions, the returned TypoPrompt object opens as a polished HTML interface in the RStudio Viewer, or in the default web browser when the Viewer is unavailable. The interface provides formatted and raw views, collapsible sections, light/dark appearance, one-click copying, TXT/HTML downloads, and printing to PDF. The prompt can also be accessed directly as plain text or saved programmatically as .txt or .html.

Usage

typoPrompt(
  object,
  desired_sets = NULL,
  sample_source = NULL,
  feature_type = "gene",
  species = "human",
  tissue = NULL,
  condition = NULL,
  use_neg_markers = TRUE,
  thresh_mode = c("n", "rank"),
  thresh = 20,
  top_k = 3,
  verbose = TRUE
)

Arguments

Details

typoPrompt() provides a model- and provider-independent workflow for LLM-assisted cell annotation. Unlike ceLLMarkup, it does not connect to an LLM directly and therefore requires no API key, model configuration, or local LLM server. Instead, it prepares the annotation task for submission to the user's preferred chatbot or LLM.

The generated prompt includes:

• positive markers and, optionally, negative markers for each set;

• available sample, tissue, condition, species, and feature context;

• instructions to consider the complete marker profile rather than individual markers;

• instructions to distinguish cell types, subtypes, and cellular states where supported by the marker evidence;

• a request for up to top_k ranked annotations with confidence scores and concise biological rationales; and

• a standardized Markdown-table response format followed by an overall interpretation.

For ClustoCell objects containing both major clusters and sub-clusters, the prompt additionally describes their hierarchy and asks the LLM to first establish the identity of each parent cluster and then interpret its sub-clusters as biologically meaningful subtypes or states within that context.

Printing a returned TypoPrompt object displays its formatted HTML interface:

prompt <- typoPrompt(...)
prompt

The underlying plain-text prompt remains directly accessible with cat(prompt) or as.character(prompt). It can also be saved programmatically using saveTypoPrompt with format = "txt" or format = "html". Interactive HTML rendering and HTML export require the optional htmltools package; when it is unavailable, printing falls back to the plain-text prompt.

Value

An object of class TypoPrompt, inheriting from character, that contains the complete LLM-ready annotation prompt.

In an interactive session, printing the object opens a formatted HTML interface in the RStudio Viewer when available, otherwise in the default web browser. The interface provides formatted and raw views, collapsible sections, light/dark appearance, one-click copying, TXT/HTML downloads, and printing to PDF. In non-interactive sessions, the plain-text prompt is printed instead. The raw prompt can also be obtained with as.character() or cat(), and exported programmatically with saveTypoPrompt.

See Also

typoClust, ceLLMarkup, typoClustVis, saveTypoPrompt, markoCell, markoClust, clustoCell

Examples

utils::data("pbmc_small", package = "SeuratObject")

cc <- clustoCell(
  data = pbmc_small,
  identify_subclusters = FALSE,
  num_threads = 1,
  verbose = FALSE
)

desired_set <- utils::head(
  sort(unique(as.character(cc$clusters$major_clusters))),
  1
)

prompt <- typoPrompt(
  object = cc,
  desired_sets = desired_set,
  sample_source = "human peripheral blood",
  tissue = "Blood",
  condition = "Healthy",
  species = "human",
  use_neg_markers = FALSE,
  thresh = 10,
  top_k = 3,
  verbose = FALSE
)

class(prompt)