# Cellbarcode

> CellBarcode

- Skill: `biomate-ai/cellbarcode` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/cellbarcode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/cellbarcode/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/cellbarcode

---


# CellBarcode

## Workflows

### Standard Workflow

Perform quality control, filter, extract, cure, and quantify lineage barcodes and UMIs from raw FASTQ files.

```r
library(CellBarcode)

# 1. Load User Inputs
example_data <- system.file("extdata", "mef_test_data", package = "CellBarcode")
fq_files <- dir(example_data, "fastq.gz", full=TRUE)
sample_name <- paste0("sample_", seq_along(fq_files))

# 2. Quality Control
qc_noFilter <- bc_seq_qc(fq_files)
bc_plot_seqQc(qc_noFilter)

# 3. Filtering
fq_filter <- bc_seq_filter(fq_files, min_average_quality = 30, min_read_length = 60, sample_name = sample_name)

# 4. Extraction
pattern <- "([ACGT]{12})CTCGAGGTCATCGAAGTATC([ACGT]+)CCGTAGCAAGCTCGAGAGTAGACCTACT"
bc_obj <- bc_extract(fq_filter, pattern = pattern, pattern_type = c("UMI" = 1, "barcode" = 2), sample_name = sample_name)

# 5. Curing and Quantification
bc_sub <- bc_cure_umi(bc_obj, depth = 2)
bc_sub <- bc_cure_depth(bc_sub, depth = 2)

# 6. Export
df_counts <- bc_2df(bc_sub)
mat_counts <- bc_2matrix(bc_sub)
```
*Inputs/Outputs:* Takes raw FASTQ files and a regular expression pattern as inputs, and outputs a `BarcodeObj` containing cleaned barcode and UMI counts, exportable to a data frame (`bc_2df`) or matrix (`bc_2matrix`).

### Scrnaseq Sam Lineage Barcoding

Extract lineage barcodes, cell barcodes, and UMIs from 10X Genomics single-cell RNA-seq SAM files.

```r
library(CellBarcode)

# 1. Load User Inputs
sam_file <- system.file("extdata", "scRNASeq_10X.sam", package = "CellBarcode")

# 2. Extract Lineage Barcode
d <- bc_extract_sc_sam(
  sam = sam_file,
  pattern = "AGATCAG(.*)TGTGGTA",
  cell_barcode_tag = "CR",
  umi_tag = "UR"
)
```
*Inputs/Outputs:* Takes a SAM file derived from 10X Genomics CellRanger output and a regular expression pattern as inputs, and outputs a data frame containing `cell_barcode`, `umi`, `barcode_seq`, and `count`.

## When to Use
- To perform cellular DNA barcode analysis and lineage tracing from raw FASTQ files using `bc_extract`.
- To extract lineage barcodes, cell barcodes, and UMIs from single-cell RNA-seq SAM/BAM files using `bc_extract_sc_sam`.
- To filter sequences by quality and length using `bc_seq_filter` and perform quality control visualization using `bc_plot_seqQc`.
- To perform error correction on barcodes and UMIs using `bc_cure_umi` and `bc_cure_depth`.

## When NOT to Use
- For standard transcriptomic alignment or gene expression quantification (use `Rsubread` or `Salmon` instead).
- For single-cell RNA-seq clustering and cell-type annotation (use `Seurat` or `scran` instead).

## Data Requirements
- Raw sequencing data in FASTQ format, or aligned single-cell RNA-seq data in SAM/BAM format (from CellRanger).
- A regular expression pattern defining the constant regions and the variable barcode/UMI regions (e.g., `"([ACGT]{12})CTCGAGGTCATCGAAGTATC([ACGT]+)CCGTAGCAAGCTCGAGAGTAGACCTACT"`).

## Key Parameters
- **pattern**: A regular expression matching the barcode structure, with brackets `()` capturing the target sequences.
- **pattern_type**: A named vector (e.g., `c("UMI" = 1, "barcode" = 2)`) mapping captured groups to sequence types.
- **min_average_quality** (30): Minimum average base quality across a read in `bc_seq_filter`.
- **min_read_length** (60): Minimum read length in bases in `bc_seq_filter`.
- **depth** (2): Minimum read/UMI depth threshold for filtering in `bc_cure_umi` and `bc_cure_depth`.
- **cell_barcode_tag** ("CR"): The SAM file tag for 10X cell barcodes in `bc_extract_sc_sam`.
- **umi_tag** ("UR"): The SAM file tag for 10X UMIs in `bc_extract_sc_sam`.

## Best Practices
- Run `bc_seq_qc` and `bc_plot_seqQc` before extraction to identify constant and random regions of the sequencing reads.
- Filter low-quality reads using `bc_seq_filter` to reduce noise and false-positive barcodes.
- Apply `bc_cure_umi` followed by `bc_cure_depth` to perform sequence error correction and remove low-abundance barcode artifacts.

## Common Pitfalls
- Incorrect regular expression pattern resulting in zero extracted barcodes. Fix: Verify the constant flanking sequences using `bc_plot_seqQc` base ratio plots.
- High memory usage with large SAM/BAM files. Fix: Pre-filter the BAM file to include only unmapped reads (e.g., using `samtools view -f 4`) before running `bc_extract_sc_sam`.

## Alternatives
- `ShortRead` for general FASTQ manipulation and quality control without specialized barcode/UMI extraction.
- `scuttle` for single-cell preprocessing and QC without lineage barcode extraction.

## Citations
- Sun W, Lyne AM (2024). CellBarcode: an R/Bioconductor package for cellular DNA barcode analysis. Nature Computational Science.

## References
- Homepage: bioconductor.org/packages/cellbarcode
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/cellbarcode/inst/doc/CellBarcode.html