[meta]
name = "cellsnp-lite"
category = "single-cell"
description = "Efficient pileup of known SNPs from single-cell or bulk RNA/DNA-seq BAM files"
tags = ["single-cell", "snp", "pileup", "allele-specific", "genotyping", "rna-seq", "demultiplexing"]
author = "oxo-call built-in"
source_url = "https://cellsnp-lite.readthedocs.io/"

[context]
concepts = [
    "cellsnp-lite piles up reads at known SNP positions (Mode 1) or discovers de novo SNPs (Mode 2) in single-cell or bulk BAMs.",
    "Mode 1a: bulk BAM + known SNPs (-R); Mode 1b: 10x BAM + cell barcodes (-b) + known SNPs; Mode 2: de novo SNP discovery.",
    "Output is a set of sparse matrix files (AD.mtx, DP.mtx, OTH.mtx) in VCF + MTX format compatible with Vireo and other demultiplexers.",
    "The -R flag points to a VCF of known SNPs (e.g., 1000G or dbSNP); using a genome-matched SNP panel improves genotyping accuracy.",
    "Cell barcodes are supplied via -b (plain text file, one barcode per line) matching the CB tags in the BAM.",
    "--minMAF and --minCOUNT filter sparse positions; for genotyping applications use --minMAF 0.1 --minCOUNT 20.",
]

pitfalls = [
    "BAM files must have CB (cell barcode) and UB (UMI) tags for single-cell mode; bulk BAMs without CB tags must use Mode 1a.",
    "Not filtering by mapping quality (--minMAPQ 20) allows multi-mapping reads to distort allele counts.",
    "Using too permissive --minMAF (e.g., 0) in Mode 2 generates millions of low-quality SNPs; use --minMAF 0.1 for reliability.",
    "The SNP VCF for -R must contain REF and ALT alleles; position-only files cause incorrect allele counting.",
    "Output directories must not exist; cellsnp-lite fails if -O points to an existing directory without --force.",
    "Single-cell mode requires the BAM index (.bai); run samtools index before cellsnp-lite.",
]

[[examples]]
task = "pileup known SNPs in a 10x Chromium scRNA-seq BAM with cell barcodes"
args = "cellsnp-lite -s possorted_genome_bam.bam -b barcodes.tsv -O cellsnp_out -R common_snps.vcf.gz -p 16 --minMAF 0.1 --minCOUNT 20"
explanation = "-s BAM; -b cell barcodes file; -O output dir; -R known SNP VCF; -p threads; --minMAF and --minCOUNT for quality filter"

[[examples]]
task = "pileup SNPs in a bulk BAM without cell barcodes"
args = "cellsnp-lite -s bulk.bam -O bulk_snp_out -R common_snps.vcf.gz -p 16 --minMAF 0.05 --minCOUNT 10"
explanation = "Mode 1a: no -b flag for bulk; -R provides known SNP positions; output has total AD/DP counts per SNP"

[[examples]]
task = "de novo SNP discovery in single-cell BAM (Mode 2)"
args = "cellsnp-lite -s possorted_genome_bam.bam -b barcodes.tsv -O denovo_snp_out -p 16 --minMAF 0.1 --minCOUNT 100 --gzip"
explanation = "Mode 2: no -R flag; discovers SNPs from the data; --gzip compresses output matrix files; higher --minCOUNT for quality"

[[examples]]
task = "pileup multiple BAMs from different samples at shared SNP positions"
args = "cellsnp-lite -s sample1.bam,sample2.bam,sample3.bam -O multi_sample_out -R common_snps.vcf.gz -p 16 --minMAF 0.1 --minCOUNT 20"
explanation = "comma-separated BAM list for multi-sample bulk pileup; useful for genotyping donors for Vireo demultiplexing"

[[examples]]
task = "restrict pileup to specific chromosomes to reduce runtime"
args = "cellsnp-lite -s possorted_genome_bam.bam -b barcodes.tsv -O chr1_out -R chr1_snps.vcf.gz --chrom 1 -p 8 --minMAF 0.1 --minCOUNT 20"
explanation = "--chrom 1 restricts to chromosome 1; useful for testing or chromosome-level parallel jobs"

[[examples]]
task = "pileup with strict base quality filter for high-confidence allele counts"
args = "cellsnp-lite -s possorted_genome_bam.bam -b barcodes.tsv -O hq_out -R snps.vcf.gz -p 16 --minMAF 0.1 --minCOUNT 20 --minBQ 30 --minMAPQ 30"
explanation = "--minBQ 30 and --minMAPQ 30 filter low-quality bases and reads; recommended for variant-level analyses"
