DOCSEARCHbyAlgolia
Submit Docs

Numbat

repository·main·Indexed 42 days ago

https://github.com/kharchenkolab/numbat

A bioinformatics tool for detecting allele-specific copy number variations (CNVs) from single-cell and spatial transcriptomics data using haplotype-aware integration. It integrates gene expression, allelic ratio, and population-derived haplotype information to infer CNVs, differentiate tumor from normal cells, and reconstruct clonal architecture without requiring paired DNA or genotype data. The toolset includes extensions for multi-modality data (Numbat-multiome) and CLI utilities for processing RNA and ATAC-seq matrices.

Tokens
4.2K
Snippets
10
Records
20
Agent score
53%

What's inside Numbat

  1. Overview of Numbat for CNV calling

    main

    Numbat is a haplotype-aware Copy Number Variation (CNV) caller designed for single-cell and spatial transcriptomics data. It integrates gene expression, allelic ratio, and population-derived haplotype information to infer allele-specific CNVs and reconstruct lineage relationships.

    Key capabilities include:

    1. Detecting allele-specific CNVs from scRNA-seq and spatial transcriptomics.
    2. Differentiating tumor vs. normal cells within the tumor microenvironment.
    3. Inferring clonal architecture and the evolutionary history of profiled tumors.

    Numbat operates solely on donor scRNA-seq data (e.g., 10x Cell Ranger output) and does not require paired DNA or genotype data.

  4. GTF and GRanges input requirements

    main

    The script accepts two types of genomic annotation inputs via the --gtf flag:

    1. GRanges Object (.rds): If the input is a GRanges object, the script automatically derives the following fields required by Numbat:

      • gene: A string formatted as seqnames:start-end.
      • gene_length: The width of the range.
      • gene_start: The start position.
      • gene_end: The end position.
      • CHROM: The sequence name with the chr prefix removed.
      • The script also filters out CHROM == "X" and removes the strand column.

    2. GTF File: If a standard GTF-like structure is provided, the column names must match the expected Numbat GTF schema (e.g., numbat::gtf_hg38). If column names do not match, the script will throw an error during validation.

  5. How barcodesKeep works in get_binned_rna.R

    main

    The --barcodesKeep argument allows you to filter the input count matrix to a specific subset of cells.

    • If NULL (default): All cells in the input file are kept.
    • If a file path is provided: The script reads the file and matches the barcodes. It supports exact matches or suffix matches (e.g., matching barcode to barcode_1).
    • If using --generateAggRef: The file must be a tabular file containing at least two columns: cell (the barcode) and group (the annotation used for aggregation/pseudobulking).

  6. Use get_binned_rna.R to generate binned RNA matrices

    main

    The get_binned_rna.R script is a CLI tool used to convert gene-level RNA-seq count data into genomic bin-level data. It supports input from Seurat objects (.rds files) or 10x HDF5 (.h5) files.

    Depending on the flags provided, the script can either:

    1. Generate a standard binned count matrix for a single sample.
    2. Generate an aggregated reference matrix (pseudobulk) by grouping cells based on provided annotations.

    Requirements:

    • The presto R package must be installed for efficient sparse matrix operations.
    • A gene-to-bin mapping CSV file (generated via get_gene_binned_intersections.R) containing gene_name and bingrp columns.
    # Example: Generate a binned count matrix for a single sample
# Rscript get_binned_rna.R --rnaCountsFile sample.rds --geneBinMapCSVFile mapping.csv --outFile binned_counts.rds

# Example: Generate an aggregated reference matrix using cell annotations
# Rscript get_binned_rna.R --rnaCountsFile sample.rds --geneBinMapCSVFile mapping.csv --outFile agg_ref.rds --barcodesKeep annotations.csv --generateAggRef

  7. Run SNP pileup and phasing with pileup_and_phase.R

    main

    The pileup_and_phase.R script is a CLI tool used to perform SNP pileup and phasing using cellsnp-lite and Eagle2. It automates the process of generating VCFs from BAM files, performing phasing against a reference panel, and producing allele count dataframes.

    Required Arguments:

    • --bams: Path to BAM file(s); comma-delimited if multiple.
    • --snpvcf: SNP VCF file for pileup.
    • --outdir: Output directory for all results.
    • --gmap: Path to the genetic map file (e.g., from Eagle2).
    • --paneldir: Directory containing the phasing reference panel (BCF files).

    Operational Modes:

    • 10X Mode (Default): Requires --samples and --barcodes.
    • SMART-seq Mode: Triggered by --smartseq. Requires --bams (as a text file of paths) and --barcodes (as a text file of cell names).
    • Bulk Mode: Triggered by --bulk. Requires --bams and --samples (no barcodes).
    • Mixed 10X Mode: Triggered when multiple different UMI tags are provided in the --UMItag argument.
    # Example for 10X mode
./pileup_and_phase.R \
  --label 'subject_01' \
  --samples 'sample1,sample2' \
  --bams 's1.bam,s2.bam' \
  --barcodes 's1.bc,s2.bc' \
  --snpvcf 'variants.vcf' \
  --paneldir './ref_panel' \
  --gmap 'genetic_map.txt.gz' \
  --outdir './results'

  8. Configure UMI and Cell Tags in pileup_and_phase.R

    main

    When running pileup_and_phase.R, you can specify how the tool identifies Unique Molecular Identifiers (UMIs) and Cell Barcodes in your BAM files using the following flags:

    • --UMItag: Specifies the UMI tag in the BAM.
      • Auto or UB: Recommended for 10x scRNA-seq.
      • None: Recommended for scATAC-seq.
      • XM: Recommended for Slide-seq.
      • You can provide a comma-delimited list if different samples use different tags.
    • --cellTAG: Specifies the cell barcode tag in the BAM.
      • CB: Recommended for 10x.
      • XC: Recommended for Slide-seq.
      • Default is CB.

  9. Preprocess and combine count matrices with binCnt_union

    main

    The binCnt_union function is used to merge two separate count matrices (e.g., from different modalities in a multiome dataset) into a single combined sparse matrix.

    It performs the following steps:

    1. Loads both input files using loadcnt (supports .rds or delimited text files).
    2. Identifies the union of all features (rows) present in either matrix.
    3. Aligns features: For each matrix, it adds zero-rows for any features missing from that specific matrix and reorders the rows to match the union of all features.
    4. Subsamples and combines: It subsamples the cells (columns) from each matrix up to a specified maxCB limit and then horizontally binds them into a single matrix.

    This ensures that the resulting matrix has a consistent set of features across all columns, even if some features were only present in one of the original datasets.

    # Example usage of binCnt_union
# bincntF: a vector of two file paths
# seed: integer for reproducibility
# maxCB: maximum number of cells to sample per matrix (default 10000)

combined_matrix <- binCnt_union(c("path/to/matrix1.rds", "path/to/matrix2.rds"), seed = 42, maxCB = 5000)

  10. Load count matrices with loadcnt

    main

    The loadcnt function loads count data from a file and returns it as a sparse dgCMatrix (from the Matrix package).

    Supported Formats:

    • .rds files: Loaded using readRDS. If the object is not already a dgCMatrix, it is converted to one.
    • Text/Delimited files: Loaded using data.table::fread. The function expects the first column (V1) to contain the feature names (row names). The resulting data is converted to a dgCMatrix.

    Note: The function uses ensure_matrix internally to handle table or array types during conversion.

    # Loading an RDS file
mat <- loadcnt("data.rds")

# Loading a text file (expects V1 to be row names)
mat <- loadcnt("data.txt")

  11. Aggregate counts by group with agg_ref

    main

    The agg_ref function is used to subsample cells and aggregate their counts into groups. This is useful for creating reference datasets or downsampling high-resolution data.

    Parameters:

    • cnt: The input count matrix.
    • maxn: The number of cells to sample.
    • x: A vector/factor representing the group assignment for the sampled cells.
    • s: An integer seed for reproducibility.

    It uses numbat::aggregate_counts to perform the actual aggregation of the sampled cells based on the provided group assignments.

    # Example: Aggregate counts for 500 cells based on group assignments 'x'
agg_mat <- agg_ref(my_counts, maxn = 500, x = group_vector, s = 123)

  12. Reference: pileup_and_phase.R CLI Flags

    main

    Full list of command-line options for the pileup_and_phase.R script:

    FlagDefaultDescription
    --labelsubjectIndividual label. One per run.
    --samplessampleSample name(s); comma delimited if multiple.
    --bamsNULLBAM file(s); one per sample, comma delimited if multiple.
    --barcodesNULLCell barcode file(s); one per sample, comma delimited if multiple.
    --gmapNULLPath to genetic map provided by Eagle2.
    --eagleeaglePath to Eagle2 binary file.
    --snpvcfNULLSNP VCF for pileup.
    --paneldirNULLDirectory to phasing reference panel (BCF files).
    --outdirNULLOutput directory.
    --ncores1Number of cores.
    --UMItagAutoUMI tag(s) in bam (Auto, UB, None, XM).
    --cellTAGCBCell tag in bam (CB or XC).
    --smartseqFALSEEnable SMART-seq mode.
    --bulkFALSEEnable bulk RNA-seq mode.