# Cardelino

> cardelino

- Skill: `biomate-ai/cardelino` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/cardelino`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/cardelino/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/cardelino

---


# cardelino

## Workflows

### Standard Workflow

Assign cells to clones using scRNA-seq variant counts and a pre-defined clonal tree configuration.

```r
library(cardelino)
library(ggplot2)

# 1. Load scRNA-seq variant data
vcf_file <- system.file("extdata", "cellSNP.cells.vcf.gz", package = "cardelino")
input_data <- load_cellSNP_vcf(vcf_file)

# 2. Load clonal tree configuration and align variant IDs
canopy_res <- readRDS(system.file("extdata", "canopy_results.coveraged.rds", package = "cardelino"))
Config <- canopy_res$tree$Z
rownames(Config) <- gsub(":", "_", rownames(Config))

# 3. Run Bayesian clustering using clone_id with the configuration matrix
set.seed(7)
assignments <- clone_id(input_data$A, input_data$D, Config = Config, min_iter = 800, max_iter = 1200)

# 4. Assign cells to clones
df <- assign_cells_to_clones(assignments$prob)

# 5. Visualize results
prob_heatmap(assignments$prob)
heat_matrix(t(assignments$Config_prob - Config))

AF <- as.matrix(input_data$A / input_data$D)
cardelino::vc_heatmap(AF, assignments$prob, Config, show_legend=TRUE)
```
*Note: Inputs are variant-by-cell matrices of alternative allele counts (A) and total coverage (D), plus a prior configuration matrix (Config); output is a list containing posterior assignment probabilities and updated clonal configurations.*

### Clone Id Denovo

Infer clonal structure and assign cells to clones de-novo without a pre-defined clonal tree, typically using mitochondrial or high-coverage variants.

```r
library(cardelino)

# 1. Read AD and DP matrices and assign variant and cell names
AD_file <- system.file("extdata", "passed_ad.mtx", package = "cardelino")
DP_file <- system.file("extdata", "passed_dp.mtx", package = "cardelino")
id_file <- system.file("extdata", "passed_variant_names.txt", package = "cardelino")

AD <- Matrix::readMM(AD_file)
DP <- Matrix::readMM(DP_file)
var_ids <- read.table(id_file)
rownames(AD) <- rownames(DP) <- var_ids[, 1]
colnames(AD) <- colnames(DP) <- paste0('Cell', seq(ncol(DP)))

# 2. Run de-novo Bayesian clustering using clone_id with Config=NULL
set.seed(7)
assign_mtClones <- clone_id(AD, DP, Config=NULL, n_clone = 3, keep_base_clone=FALSE)

# 3. Threshold the posterior configuration probability matrix
Config_mt <- assign_mtClones$Config_prob
Config_mt[Config_mt >= 0.5] = 1
Config_mt[Config_mt < 0.5] = 0

# 4. Visualize cell assignments and clonal configurations
AF_mt <- as.matrix(AD / DP)
cardelino::vc_heatmap(AF_mt, assign_mtClones$prob, Config_mt, show_legend=TRUE)
```
*Note: Inputs are sparse matrices of alternative (AD) and total (DP) counts without a prior tree; output is a de-novo clonal assignment and inferred configuration matrix.*

## When to Use
- To assign single-cell transcriptomes to individual clones using sparse variant information from scRNA-seq reads.
- To integrate prior clonal tree configurations (e.g., from bulk DNA-seq using Canopy) with single-cell RNA-seq variant counts.
- To perform de-novo clonal clustering on mitochondrial variations (e.g., from MQuad) without a prior clonal tree.

## When NOT to Use
- Do not use if you do not have variant-level coverage and alternative allele count matrices (A and D) extracted from single-cell sequencing reads.
- Do not use for bulk-only clonal tree reconstruction; use tools like `Canopy` instead.

## Data Requirements
- Matrix `A` (or `AD`): variant x cell matrix of integer counts supporting the alternative allele.
- Matrix `D` (or `DP`): variant x cell matrix of integer counts providing the total read coverage at each site.
- `Config`: variant x clone binary configuration matrix (optional for de-novo mode).

## Key Parameters
- **Config** (NULL): Prior variant-by-clone configuration matrix. Set to `NULL` for de-novo mode.
- **n_clone** (3): Number of clones to infer when `Config` is `NULL`.
- **min_iter** (800): Minimum number of Gibbs sampling iterations.
- **max_iter** (1200): Maximum number of Gibbs sampling iterations.
- **keep_base_clone** (FALSE): Logical indicating whether to keep the first clone as a base clone with no mutations.

## Best Practices
- Ensure variant IDs are perfectly matched between the scRNA-seq matrices (`A` and `D`) and the prior configuration matrix (`Config`).
- Use the Geweke z-statistic (checked automatically in `clone_id`) to ensure Gibbs sampling convergence.
- For de-novo mode, run `clone_id` multiple times with different random seeds and select the run with the highest DIC to avoid local optima.

## Common Pitfalls
- Gibbs sampler not converging: Increase `min_iter` and `max_iter` parameters.
- Local optima in de-novo mode: Run multiple initializations with different seeds.

## Alternatives
- `Canopy` for bulk DNA-seq clonal tree inference.
- `MQuad` for mitochondrial variant calling.

## Citations
- McCarthy, D., & Huang, Y. (2026). cardelino: Clonal tree configuration and cell assignment from single-cell data.

## References
- Homepage: bioconductor.org/packages/cardelino
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/cardelino/inst/doc/vignette-cloneid.html