### Example usage of cnv_heatmap

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/cnv_heatmap.html

Basic example demonstrating how to call the `cnv_heatmap` function with example segment data.

```R
p = cnv_heatmap(segs_example)
```

--------------------------------

### Install Numbat from GitHub

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Install the latest development version of the Numbat R package from GitHub.

```r
devtools::install_github("https://github.com/kharchenkolab/numbat")
```

--------------------------------

### Install Numbat from CRAN

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Install the Numbat R package and its dependencies from CRAN.

```r
install.packages('numbat', dependencies = TRUE)
```

--------------------------------

### Call CNVs in Pseudobulk Profile

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/analyze_bulk.html

This example demonstrates how to call CNVs in a pseudobulk profile using the analyze_bulk function. It shows how to set specific parameters like transition probability (t), diploid region identification (find_diploid), and retesting of CNVs (retest).

```R
bulk_analyzed = analyze_bulk(bulk_example, t = 1e-5, find_diploid = FALSE, retest = FALSE)
```

--------------------------------

### Load Libraries and Numbat Objects

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/results.html

Loads necessary R libraries and pre-saved Numbat and pagoda2 objects for analysis. Ensure these libraries are installed before running.

```r
library(ggplot2)
library(numbat)
library(dplyr)
library(glue)
library(data.table)
library(ggtree)
library(stringr)
library(tidygraph)
library(patchwork)

nb = Numbat$new(out_dir = './numbat_out')
nb = readRDS(url('http://pklab.org/teng/data/nb_TNBC1.rds'))
pagoda = readRDS(url('http://pklab.org/teng/data/con_TNBC1.rds'))
```

--------------------------------

### Aggregate single-cell data using get_bulk

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_bulk.html

This example demonstrates how to use the get_bulk function to aggregate single-cell data. It requires count matrices, reference profiles, allele data, and GTF information. The output is a pseudobulk gene expression and allele profile.

```R
bulk_example = get_bulk(
    count_mat = count_mat_example,
    lambdas_ref = ref_hca,
    df_allele = df_allele_example,
    gtf = gtf_hg38)

```

--------------------------------

### Run pileup_and_phase.R script in Numbat Docker

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Example of how to execute the R script for SNP pileup and phasing within the Numbat Docker container. Ensure all paths are correctly specified for your environment.

```bash
Rscript /numbat/inst/bin/pileup_and_phase.R \
    --label {sample} \
    --samples {sample} \
    --bams /mnt/mydata/{sample}.bam \
    --barcodes /mnt/mydata/{sample}_barcodes.tsv \
    --outdir /mnt/mydata/{sample} \
    --gmap /Eagle_v2.4.1/tables/genetic_map_hg38_withX.txt.gz \
    --snpvcf /data/genome1K.phase3.SNP_AF5e2.chr1toX.hg38.vcf \
    --paneldir /data/1000G_hg38 \
    --ncores ncores
```

--------------------------------

### Run Numbat analysis in R

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Example of how to run the main Numbat analysis function using pre-prepared gene expression count matrix and allele dataframe. This function performs cell type deconvolution and assigns genotypes.

```R
library(numbat)

count_mat_ATC2 = readRDS(url('http://pklab.med.harvard.edu/teng/data/count_mat_ATC2.rds'))
df_allele_ATC2 = readRDS(url('http://pklab.med.harvard.edu/teng/data/df_allele_ATC2.rds'))

# run
out = run_numbat(
    count_mat_ATC2, # gene x cell integer UMI count matrix 
    ref_hca, # reference expression profile, a gene x cell type normalized expression level matrix
    df_allele_ATC2, # allele dataframe generated by pileup_and_phase script
    genome = "hg38",
    t = 1e-5,
    ncores = 4,
    plot = TRUE,
    out_dir = './test'
)
```

--------------------------------

### Numbat$new()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Initializes a new Numbat object.

```APIDOC
## Method `new()`

### Description
Initializes a new Numbat object.

### Usage

```R
Numbat$new(out_dir, i = 2, gtf = gtf_hg38, verbose = TRUE)
```

### Arguments

* `out_dir` (character string) - Output directory
* `i` (integer) - Get results from which iteration (default=2)
* `gtf` (dataframe) - Transcript gtf (default=gtf_hg38)
* `verbose` (logical) - Whether to output verbose results (default=TRUE)

### Returns

a new 'Numbat' object
```

--------------------------------

### get_nodes_celltree

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_nodes_celltree.html

Get the internal nodes of a dendrogram and the leafs in each subtree.

```APIDOC
## get_nodes_celltree

### Description
Get the internal nodes of a dendrogram and the leafs in each subtree.

### Usage

    get_nodes_celltree(hc, clusters)

### Arguments

#### hc

hclust Clustering results

#### clusters

named vector Cutree output specifying the terminal clusters

### Value

list Interal node subtrees with leaf memberships
```

--------------------------------

### Prepare Allele Data with Numbat Script

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Execute the Numbat preprocessing script to count alleles and phase SNPs.

```bash
numbat/inst/bin/pileup_and_phase.R
```

--------------------------------

### get_internal_nodes

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_internal_nodes.html

Helper function to get the internal nodes of a dendrogram and the leafs in each subtree.

```APIDOC
## get_internal_nodes

### Description
Helper function to get the internal nodes of a dendrogram and the leafs in each subtree.

### Usage

```R
get_internal_nodes(den, node, labels)
```

### Arguments

*   `den` (dendrogram) - The dendrogram object.
*   `node` (character) - Node name.
*   `labels` (character vector) - Leaf labels.
```

--------------------------------

### Run Numbat Docker Container

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Launch the Numbat Docker container, mounting a local directory for data access.

```bash
docker run -v /work:/mnt/mydata -it pkharchenkolab/numbat-rbase:latest /bin/bash
```

--------------------------------

### Get phased haplotypes

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_haplotype_post.html

Retrieves phased haplotypes by taking subtree pseudobulk profiles and consensus CNV segments as input. It can optionally use a naive haplotype classification method.

```APIDOC
## get_haplotype_post

### Description
Retrieves phased haplotypes using subtree pseudobulk profiles and consensus CNV segments.

### Usage

```R
get_haplotype_post(bulks, segs_consensus, naive = FALSE)
```

### Arguments

*   **bulks** (dataframe) - Subtree pseudobulk profiles.
*   **segs_consensus** (dataframe) - Consensus CNV segments.
*   **naive** (logical, optional) - Whether to use naive haplotype classification. Defaults to FALSE.

### Value

*   dataframe - Posterior haplotypes.
```

--------------------------------

### Download 1000 Genomes Reference Panel

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Download the 1000 Genomes phasing reference panel for hg38 or hg19.

```bash
# hg38
wget http://pklab.med.harvard.edu/teng/data/1000G_hg38.zip
```

```bash
# hg19
wget http://pklab.med.harvard.edu/teng/data/1000G_hg19.zip
```

--------------------------------

### Run Numbat Multiome Analysis

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat-multiome.html

Executes the Numbat multiome analysis script. Requires count matrix, allele counts, output directory, reference, GTF file, and optimization parameters.

```bash
binGR="var220kb.rds"
parL="par_numbatm.rds" # a list of any run_numbat parameters you would like to optimize
Rscript run_numbat_multiome.R  \
            --countmat ${sample}/${sample}_comb_bincnt.rds \
            --alleledf ${sample}/${sample}_comb_allele_counts.tsv.gz \
            --out_dir ${sample}/paired/ \
            --ref Reference/lambdas_comb_bincnt.rds \
            --gtf  ${binGR}\
            --parL ${parL}
```

--------------------------------

### Prepare Mouse Expression Reference Data in R

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/mouse.html

Loads scRNA-seq count matrix, cell, and gene information. It then processes the count matrix, performs basic processing with pagoda2, and aggregates counts to create a reference expression profile.

```r
count_mat = readMM('~/GSE159343_RAW/GSM4826923_C57BL6J_matrix.mtx.gz')
cells = fread('~/GSE159343_RAW/GSM4826923_C57BL6J_cells.tsv.gz', header = F)$V1
genes = fread('~/GSE159343_RAW/GSM4826923_C57BL6J_genes.tsv.gz', header = F)$V2
colnames(count_mat) = cells
rownames(count_mat) = genes
count_mat = as.matrix(count_mat)
count_mat = rowsum(count_mat, rownames(count_mat))
count_mat = as(count_mat, "dgCMatrix")
count_mat_ref = count_mat

p2 = pagoda2::basicP2proc(count_mat_ref, n.cores = 30)

clusters = p2$clusters$PCA$multilevel

ref_annot = data.frame(
    cell = names(clusters),
    group = unname(clusters)
)

ref_pancreas = numbat::aggregate_counts(
    count_mat_ref,
    ref_annot %>% group_by(group) %>% filter(n() > 100)
)
```

--------------------------------

### Cloning a Numbat Object

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Demonstrates how to clone a Numbat object. Use the 'deep' argument to control whether a shallow or deep copy is made.

```R
Numbat$clone(deep = FALSE)
```

--------------------------------

### Prepare SNP Allele Data for RNA and ATAC

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat-multiome.html

Use this script to prepare SNP allele counts for both RNA and ATAC modalities. It requires BAM files, barcode files, a genetic map, a VCF file, and a phase panel directory. Specify the number of cores and output directory.

```bash
nc=8 # number of cores to use
sample="MM1"
## default to path in numbat image
phase_panel="/data/1000G_hg38"
vcf_genome1k="/data/genome1K.phase3.SNP_AF5e2.chr1toX.hg38.vcf"
gma_gz="/Eagle_v2.4.1/tables/genetic_map_hg38_withX.txt.gz"

Rscript pileup_and_phase.R \
  --label ${sample} \
  --samples ${sample} \
  --bams ${sample}_rna.bam,${sample}_atac.bam \
  --barcodes ${sample}_rna_barcodes.tsv,${sample}_atac_barcodes.tsv \
  --gmap ${gma_gz} \
  --snpvcf ${vcf_genome1k} \
  --paneldir ${phase_panel} \
  --ncores ${nc} \
  --cellTAG CB \
  --UMItag Auto,None \
  --outdir ${sample}/${sample}_comb_allele_counts.tsv.gz
```

--------------------------------

### Read Numbat Results and Spot Coordinates

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/test2.html

Loads Numbat results and spot coordinates for multiple samples. Ensure the results directory and sample data are correctly configured.

```R
library(data.table)
library(dplyr)
library(glue)
library(stringr)
library(numbat)
library(ggplot2)

# read in the numbat results and spot coordinates
nb = list()
spots = list()
samples = c('OVCA1', 'OVCA3', 'BRCA1', 'GIST1')
for (sample in samples) {
    nb[[sample]] = Numbat$new(glue('~/results/{sample}'))
    spots[[sample]] = fread(glue('~/{sample}/outs/spatial/tissue_positions.csv'))
}
```

--------------------------------

### Load Libraries and Data for scRNA-seq Analysis

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/hmm.html

Loads necessary R libraries and sample data for analyzing scRNA-seq data using Numbat. This includes allele counts, gene counts, and a Pagoda object for cell clustering.

```r
library(numbat)
library(dplyr)
library(glue)
library(stringr)
library(data.table)
```

```r
allele_counts = fread('http://pklab.med.harvard.edu/teng/data/hmm_example/TNBC1_allele_counts.tsv.gz')
gene_counts = readRDS(url('http://pklab.med.harvard.edu/teng/data/hmm_example/TNBC1_gene_counts.rds'))
pagoda = readRDS(url('http://pklab.med.harvard.edu/teng/data/con_TNBC1.rds'))
```

--------------------------------

### clone()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

The objects of this class are cloneable with this method. It allows for creating copies of Numbat objects.

```APIDOC
## Method clone()

### Description
The objects of this class are cloneable with this method.

### Usage

```r
Numbat$clone(deep = FALSE)
```

### Arguments

* `deep` (logical) - Whether to make a deep clone.
```

--------------------------------

### Download 1000 Genomes SNP VCF

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat.html

Download the 1000 Genomes SNP VCF file for hg38 or hg19 reference genomes.

```bash
# hg38
wget https://sourceforge.net/projects/cellsnp/files/SNPlist/genome1K.phase3.SNP_AF5e2.chr1toX.hg38.vcf.gz
```

```bash
# hg19
wget https://sourceforge.net/projects/cellsnp/files/SNPlist/genome1K.phase3.SNP_AF5e2.chr1toX.hg19.vcf.gz
```

--------------------------------

### Generate Gene-to-Bin Mapping

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat-multiome.html

This script creates a mapping between genes and genomic bins using a GTF file and a Grange object containing genomic bins. The output is a CSV file.

```bash
binGR="var220kb.rds" # path to grange object containing genomic bins
gtfF="gtf_hg38.gtf" # any version of gtf files you use or hg38, hg19 or mm10

Rscript get_gene_binned_intersections.R \
  --numbatGTFname ${gtfF} \
  --binGR ${binGR} \
  --outfile gene2bin_map.csv
```

--------------------------------

### Load and Plot Numbat Results

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/mouse.html

Loads Numbat results for a specific sample and plots the phylogenetic heatmap. Customizes clone colors and stacking for visualization. Requires the 'Numbat' object to be initialized with the results directory.

```r
nb = Numbat$new(glue('./results/{sample}'))

options(repr.plot.width = 8, repr.plot.height = 4, repr.plot.res = 200)

clone_pal = c(`1` = 'gray', `2` = "#E41A1C", `3` = "#377EB8",
    `4` = "#4DAF4A", `5` = "#984EA3", `6` = 'bisque3')

nb$plot_phylo_heatmap(pal_clone = clone_pal, clone_stack = TRUE, p_min = 0.9)
```

--------------------------------

### Plot Mutant vs. Normal Probabilities by Sample

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/test2.html

Generates scatter plots showing the spatial distribution of mutant versus normal cell probabilities for each sample. Uses ggplot2 for visualization.

```R
options(repr.plot.width = 8.5, repr.plot.height = 8, repr.plot.res = 300)

lapply(
    c('OVCA1', 'OVCA3', 'GIST1', 'BRCA1'),
    function(sample) {
        
        spots[[sample]] %>%
            left_join(
                nb[[sample]]$clone_post,
                by = c('barcode' = 'cell')
            ) %>%
            filter(in_tissue == 1) %>%
            ggplot(
                aes(x = array_row, y = array_col)
            ) + 
            geom_point(aes(color = p_cnv), size = 1, alpha = 0.8, pch = 16) + 
            scale_color_gradient2(
                low = 'darkgreen', high = 'red3', mid = 'yellow', 
                midpoint = 0.5, limits = c(0,1), oob = scales::oob_squish
            ) + 
            theme_bw() + 
            scale_x_continuous(expand = expansion(add = 1), limits = c(0,77)) + 
            scale_y_continuous(expand = expansion(add = 1), limits = c(0,127)) + 
            ggtitle(sample)
    }
) %>%
wrap_plots(guides = 'collect')
```

--------------------------------

### Load Data for Bulk RNA-seq Analysis

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/hmm.html

Loads allele counts and gene counts for bulk RNA-seq data analysis. This step prepares the data for HMM analysis by reading count matrices.

```r
allele_counts = fread('http://pklab.med.harvard.edu/teng/data/hmm_example/MN-5_TUMOR_allele_counts.tsv.gz')
gene_counts = readRDS(url('http://pklab.med.harvard.edu/teng/data/hmm_example/MN_gene_counts.rds'))
```

--------------------------------

### Numbat$plot_sc_tree()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Plots the single-cell phylogeny.

```APIDOC
## Method `plot_sc_tree()`

### Description
Plot the single cell phylogeny.

### Usage

```R
Numbat$plot_sc_tree(...)
```

### Arguments

* `...` - additional parameters passed to plot_sc_tree()
```

--------------------------------

### Create Reference Expression Profile for Bulk RNA-seq

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/hmm.html

Creates a reference expression profile from a diploid sample (MN-1037_TUMOR) to be used in the Numbat HMM analysis for other bulk RNA-seq samples. This involves normalizing gene counts.

```r
ref_internal = gene_counts[,'MN-1037_TUMOR',drop=F] %>% {./sum(.)}
head(ref_internal)
```

--------------------------------

### return_missing_columns

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/return_missing_columns.html

Checks the format of a given file. It takes a file path and an optional vector of expected column names.

```APIDOC
## return_missing_columns

### Description
Checks the format of a given file.

### Usage

```R
return_missing_columns(file, expected_colnames = NULL)
```

### Parameters

*   **file** (character) - The path to the file to check.
*   **expected_colnames** (character vector, optional) - A vector of expected column names. If NULL, no specific column names are enforced.
```

--------------------------------

### Aggregate scRNA-seq Cells and Analyze Bulk Data

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/hmm.html

Aggregates scRNA-seq cells into pseudobulks based on provided clusters and runs the Numbat HMM analysis on each bulk. Requires gene expression counts, allele counts, reference data, and genomic maps.

```r
clusters = pagoda$clusters$PCA$multilevel

bulks = list()

for (cluster in c('1','3','5')) {
  
    cells = names(clusters[clusters == cluster])
   
    bulks[[cluster]] = get_bulk(
        gene_counts[,cells],
        ref_hca,
        allele_counts %>% filter(cell %in% cells),
        gtf_hg38,
        genetic_map_hg38
    ) %>% 
    mutate(sample = cluster)
  
    bulks[[cluster]] = bulks[[cluster]] %>% analyze_bulk(t = 1e-5)
  
}

bind_rows(bulks) %>% plot_bulks()
```

--------------------------------

### Analyze Bulk RNA-seq Sample with Numbat HMM

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/hmm.html

Performs Numbat HMM analysis on a specific bulk RNA-seq sample using the provided gene counts, allele counts, reference profile, and genomic information. Visualizes the results with `plot_psbulk`.

```r
sample = 'MN-5_TUMOR'

bulk = get_bulk(
        count_mat = gene_counts[,sample,drop=F],
        df_allele = allele_counts,
        lambdas_ref = ref_internal,
        genetic_map = genetic_map_hg38,
        gtf = gtf_hg38
    ) %>% 
    analyze_bulk()

bulk %>% plot_psbulk(min_depth = 15)
```

--------------------------------

### get_trans_probs

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_trans_probs.html

This function calculates transition probabilities. It is a helper function within the numbat package.

```APIDOC
## get_trans_probs

### Description
Helper function to calculate transition probabilities.

### Usage

```r
get_trans_probs(t, p_s, w, cn_from, phase_from, cn_to, phase_to)
```

### Parameters

*   **t** - Description not available.
*   **p_s** - Description not available.
*   **w** - Description not available.
*   **cn_from** - Description not available.
*   **phase_from** - Description not available.
*   **cn_to** - Description not available.
*   **phase_to** - Description not available.

### Details

Source: [`R/hmm.R`](https://github.com/kharchenkolab/numbat/blob/HEAD/R/hmm.R)

`get_trans_probs.Rd`

Helper function to calculate transition porbabilities
```

--------------------------------

### Overlay Mutant vs. Normal Probabilities on Tissue Images

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/test2.html

Visualizes mutant versus normal cell probabilities overlaid on tissue images for each sample. Requires JPEG images and uses ggplot2 with background images.

```R
options(repr.plot.width = 8.5, repr.plot.height = 8, repr.plot.res = 300)

lapply(
    c('OVCA1', 'OVCA3', 'GIST1', 'BRCA1'),
    function(sample) {
        
        img <- jpeg::readJPEG(glue("~/visium/nyu/images/{sample}_cropped.jpg"))

        spots[[sample]] %>%
            left_join(
                nb[[sample]]$clone_post,
                by = c('barcode' = 'cell')
            ) %>%
            filter(in_tissue == 1) %>%
            ggplot(
                aes(x = array_row, y = array_col)
            ) + 
            background_image(img) + 
            geom_point(
                aes(color = p_cnv), size = 0.3,
                stroke = 0.3, alpha = 0.8, pch = 21
            ) + 
            scale_color_gradient2(
                low = 'darkgreen', high = 'red3', mid = 'yellow', 
                midpoint = 0.5, limits = c(0,1), oob = scales::oob_squish
            ) + 
            theme_bw() + 
            scale_x_continuous(expand = expansion(add = 1), limits = c(0,77)) + 
            scale_y_continuous(expand = expansion(add = 1), limits = c(0,127)) + 
            ggtitle(sample)
    }
) %>%
wrap_plots(guides = 'collect')
```

--------------------------------

### Numbat$plot_mut_history()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Plots the mutation history of the tumor.

```APIDOC
## Method `plot_mut_history()`

### Description
Plot the mutation history of the tumor.

### Usage

```R
Numbat$plot_mut_history(...)
```

### Arguments

* `...` - additional parameters passed to plot_mut_history()
```

--------------------------------

### Generate Binned RNA Reference

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/numbat-multiome.html

Generates binned RNA counts for reference. Requires RNA counts, barcodes, and gene-to-bin mapping.

```bash
Rscript get_binned_rna.R \
  --rnaCountsFile ref_seu.rds \
  --outFile Reference/lambdas_RNA_bincnt.rds \
  --barcodesKeep ref_barcodes.tsv \
  --geneBinMapCSVFile gene2bin_map.csv \
  --generateAggRef
```

--------------------------------

### run_joint_hmm

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/run_joint_hmm.html

Runs a joint Hidden Markov Model (HMM) on a pseudobulk profile to infer copy number states and allele-specific expression. It takes paternal allele counts, total allele counts, and phase switch probabilities as primary inputs, along with various optional parameters to control the HMM's behavior and interpretation.

```APIDOC
## Function: run_joint_hmm

### Description
Runs a joint Hidden Markov Model (HMM) on a pseudobulk profile to infer copy number states and allele-specific expression. It takes paternal allele counts, total allele counts, and phase switch probabilities as primary inputs, along with various optional parameters to control the HMM's behavior and interpretation.

### Arguments

*   **pAD** (integer vector) - Paternal allele counts.
*   **DP** (integer vector) - Total allele counts.
*   **p_s** (numeric vector) - Phase switch probabilities.
*   **Y_obs** (numeric vector, optional) - Observed gene counts. Defaults to 0.
*   **lambda_ref** (numeric vector, optional) - Reference expression rates. Defaults to 0.
*   **d_total** (integer, optional) - Total library size for expression counts. Defaults to 0.
*   **theta_min** (numeric, optional) - Minimum haplotype imbalance threshold. Defaults to 0.08.
*   **theta_neu** (numeric, optional) - Default value is 0.
*   **bal_cnv** (logical, optional) - Default to TRUE.
*   **phi_del** (numeric, optional) - Expected fold change for deletion. Defaults to 2^(-0.25).
*   **phi_amp** (numeric, optional) - Expected fold change for amplification. Defaults to 2^(0.25).
*   **phi_bamp** (numeric, optional) - Expected fold change for balanced amplification. Defaults to phi_amp.
*   **phi_bdel** (numeric, optional) - Expected fold change for balanced deletion. Defaults to phi_del.
*   **alpha** (numeric, optional) - Defaults to 1.
*   **beta** (numeric, optional) - Defaults to 1.
*   **mu** (numeric, optional) - Global expression bias. Defaults to 0.
*   **sig** (numeric, optional) - Global expression variance. Defaults to 1.
*   **t** (numeric, optional) - Transition probability between copy number states. Defaults to 1e-05.
*   **gamma** (numeric, optional) - Overdispersion in the allele-specific expression. Defaults to 18.
*   **prior** (any, optional) - Default to NULL.
*   **exp_only** (logical, optional) - Whether to only use expression data. Defaults to FALSE.
*   **allele_only** (logical, optional) - Whether to only use allele data. Defaults to FALSE.
*   **classify_allele** (logical, optional) - Default to FALSE.
*   **phasing** (logical, optional) - Default to TRUE.
*   **debug** (logical, optional) - Default to FALSE.

### Source
[`R/hmm.R`](https://github.com/kharchenkolab/numbat/blob/HEAD/R/hmm.R)
```

--------------------------------

### Plot Pseudobulk HMM Profiles

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/plot_bulks.html

Generates a ggplot object visualizing pseudobulk HMM profiles. Requires a dataframe with a 'sample' column. Additional parameters can control plot layout and titles.

```r
p = plot_bulks(bulk_example)
```

--------------------------------

### get_clone_post

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_clone_post.html

Maps cells to the phylogeny (or genotypes) based on CNV posteriors.

```APIDOC
## get_clone_post

### Description
Maps cells to the phylogeny (or genotypes) based on CNV posteriors.

### Usage

```R
get_clone_post(gtree, exp_post, allele_post)
```

### Arguments

#### `gtree`
- Type: tbl_graph
- Description: A cell lineage tree

#### `exp_post`
- Type: dataframe
- Description: Expression posteriors

#### `allele_post`
- Type: dataframe
- Description: Allele posteriors

### Value

- Type: dataframe
- Description: Clone posteriors
```

--------------------------------

### get_ordered_tips

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_ordered_tips.html

Retrieves ordered tips from a tree structure. This function is part of the numbat package and is used for tree manipulation.

```APIDOC
## get_ordered_tips

### Description
Retrieves ordered tips from a tree structure.

### Usage

    get_ordered_tips(tree)

### Parameters
#### Path Parameters
- **tree** (type) - Description: The tree from which to get ordered tips.
```

--------------------------------

### exp_hclust

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/exp_hclust.html

Runs smoothed expression-based hierarchical clustering.

```APIDOC
## exp_hclust

### Description
Runs smoothed expression-based hierarchical clustering.

### Usage

```R
exp_hclust(count_mat, lambdas_ref, gtf, sc_refs = NULL, window = 101, ncores = 1, verbose = TRUE)
```

### Arguments

*   `count_mat` (dgCMatrix) - Gene counts
*   `lambdas_ref` (matrix) - Reference expression profiles
*   `gtf` (dataframe) - Transcript GTF
*   `sc_refs` (named list, optional) - Reference choices for single cells
*   `window` (integer) - Sliding window size
*   `ncores` (integer) - Number of cores
*   `verbose` (logical) - Verbosity
```

--------------------------------

### analyze_bulk

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/analyze_bulk.html

Calls CNVs in a pseudobulk profile using the Numbat joint HMM. This function takes a pseudobulk profile and several optional parameters to tune the HMM analysis for CNV detection.

```APIDOC
## analyze_bulk

### Description
Calls CNVs in a pseudobulk profile using the Numbat joint HMM.

### Usage

```R
analyze_bulk(
  bulk,
  t = 1e-05,
  gamma = 20,
  theta_min = 0.08,
  logphi_min = 0.25,
  nu = 1,
  min_genes = 10,
  exp_only = FALSE,
  allele_only = FALSE,
  bal_cnv = TRUE,
  retest = TRUE,
  find_diploid = TRUE,
  diploid_chroms = NULL,
  classify_allele = FALSE,
  run_hmm = TRUE,
  prior = NULL,
  exclude_neu = TRUE,
  phasing = TRUE,
  verbose = TRUE
)
```

### Arguments

*   **bulk** (dataframe) - Pseudobulk profile.
*   **t** (numeric) - Transition probability.
*   **gamma** (numeric) - Dispersion parameter for the Beta-Binomial allele model.
*   **theta_min** (numeric) - Minimum imbalance threshold.
*   **logphi_min** (numeric) - Minimum log expression deviation threshold.
*   **nu** (numeric) - Phase switch rate.
*   **min_genes** (integer) - Minimum number of genes to call an event.
*   **exp_only** (logical) - Whether to run expression-only HMM.
*   **allele_only** (logical) - Whether to run allele-only HMM.
*   **bal_cnv** (logical) - Whether to call balanced amplifications/deletions.
*   **retest** (logical) - Whether to retest CNVs after Viterbi decoding.
*   **find_diploid** (logical) - Whether to run diploid region identification routine.
*   **diploid_chroms** (character vector) - User-given chromosomes that are known to be in diploid state.
*   **classify_allele** (logical) - Whether to only classify allele (internal use only).
*   **run_hmm** (logical) - Whether to run HMM (internal use only).
*   **prior** (numeric vector) - Prior probabilities of states (internal use only).
*   **exclude_neu** (logical) - Whether to exclude neutral segments from retesting (internal use only).
*   **phasing** (logical) - Whether to use phasing information (internal use only).
*   **verbose** (logical) - Verbosity.

### Value

A pseudobulk profile dataframe with called CNV information.

### Examples

```R
bulk_analyzed = analyze_bulk(bulk_example, t = 1e-5, find_diploid = FALSE, retest = FALSE)
```
```

--------------------------------

### get_gtree Function

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_gtree.html

Generates a phylogenetic tree with simplified mutational history. Specify either max_cost or n_cut. The top-level normal diploid clone is always included.

```APIDOC
## get_gtree

### Description
Get a tidygraph tree with simplified mutational history.

### Usage

```R
get_gtree(tree, P, n_cut = 0, max_cost = 0)
```

### Arguments

*   `tree` (phylo) - Single-cell phylogenetic tree
*   `P` (matrix) - Genotype probability matrix
*   `n_cut` (integer) - Number of cuts on the phylogeny to define subclones
*   `max_cost` (numeric) - Likelihood threshold to collapse internal branches

### Value

tbl_graph - Phylogeny annotated with branch lengths and mutation events
```

--------------------------------

### get_move_opt

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_move_opt.html

Calculates the least costly mutation reassignment by considering the mutation graph and a likelihood matrix.

```APIDOC
## get_move_opt

### Description
Get the least costly mutation reassignment.

### Usage

```R
get_move_opt(G, l_matrix)
```

### Arguments

#### `G`
- **Type**: igraph
- **Description**: Mutation graph.

#### `l_matrix`
- **Type**: matrix
- **Description**: Likelihood matrix of mutation placements.

### Value

- **Type**: numeric
- **Description**: Likelihood cost of performing the mutation move.
```

--------------------------------

### combine_bulk

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/combine_bulk.html

Combines allele and expression pseudobulk dataframes into a single pseudobulk profile.

```APIDOC
## combine_bulk

### Description
Combines allele and expression pseudobulks.

### Usage

```R
combine_bulk(allele_bulk, exp_bulk)
```

### Arguments

*   **allele_bulk** (dataframe) - Bulk allele profile
*   **exp_bulk** (dataframe) - Bulk expression profile

### Value

*   dataframe - Pseudobulk allele and expression profile
```

--------------------------------

### Run Numbat for Mouse CNV Analysis

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/mouse.html

Executes the Numbat analysis with mouse-specific settings, including genome build 'mm10' and disabling phase switching by setting nu = 0. Adjusts parameters like t, ncores, and min_LLR for the analysis.

```r
run_numbat(
    count_mat_tumor, 
    ref_pancreas, 
    df_allele,
    t = 1e-5,
    ncores = 20,
    skip_nj = TRUE,
    min_LLR = 30,
    out_dir = './results',
    # mouse specific settings
    genome = "mm10",
    nu = 0
)
```

--------------------------------

### generate_postfix

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/generate_postfix.html

Generates alphabetical postfixes for a vector of integers.

```APIDOC
## generate_postfix

### Description
Generates alphabetical postfixes for a vector of integers.

### Usage

```R
generate_postfix(n)
```

### Arguments

#### n
- **n** (vector of integers) - The input vector of integers.

### Value

- **vector of alphabetical postfixes** - Returns a vector of alphabetical postfixes corresponding to the input integers.
```

--------------------------------

### Numbat$plot_exp_roll()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Plots window-smoothed expression profiles.

```APIDOC
## Method `plot_exp_roll()`

### Description
Plot window-smoothed expression profiles.

### Usage

```R
Numbat$plot_exp_roll(k = 3, n_sample = 300, ...)
```

### Arguments

* `k` (integer) - Number of clusters
* `n_sample` (integer) - Number of cells to subsample
* `...` - additional parameters passed to plot_exp_roll()
```

--------------------------------

### run_numbat

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/run_numbat.html

Executes the Numbat workflow to decompose tumor subclones. This function takes raw count matrices, reference allele frequencies, and other parameters to infer subclone structures.

```APIDOC
## run_numbat

### Description

Executes the Numbat workflow to decompose tumor subclones. This function takes raw count matrices, reference allele frequencies, and other parameters to infer subclone structures.

### Usage

```R
run_numbat(
  count_mat,
  lambdas_ref,
  df_allele,
  gtf = NULL,
  genome = "hg38",
  out_dir = tempdir(),
  max_iter = 2,
  max_nni = 100,
  t = 1e-05,
  gamma = 20,
  min_LLR = 5,
  alpha = 1e-04,
  eps = 1e-05,
  max_entropy = 0.5,
  init_k = 3,
  min_cells = 50,
  tau = 0.3,
  nu = 1,
  max_cost = ncol(count_mat) * tau,
  n_cut = 0,
  min_depth = 0,
  common_diploid = TRUE,
  min_overlap = 0.45,
  ncores = 1,
  ncores_nni = ncores,
  random_init = FALSE,
  segs_loh = NULL,
  call_clonal_loh = FALSE,
  verbose = TRUE,
  diploid_chroms = NULL,
  segs_consensus_fix = NULL,
  use_loh = NULL,
  min_genes = 10,
  skip_nj = FALSE,
  multi_allelic = TRUE,
  p_multi = 1 - alpha,
  plot = TRUE,
  check_convergence = FALSE,
  exclude_neu = TRUE
)
```

### Arguments

*   **count_mat** (dgCMatrix) - Raw count matrices where rownames are genes and column names are cells
*   **lambdas_ref** (matrix) - Either a named vector with gene names as names and normalized expression as values, or a matrix where rownames are genes and columns are pseudobulk names
*   **df_allele** (dataframe) - Allele counts per cell, produced by preprocess_allele
*   **gtf** (dataframe) - Transcript GTF, if NULL will use the default GTF for the specified genome
*   **genome** (character) - Genome version (hg38, hg19, or mm10)
*   **out_dir** (string) - Output directory
*   **max_iter** (integer) - Maximum number of iterations to run the phyologeny optimization
*   **max_nni** (integer) - Maximum number of iterations to run NNI in the ML phylogeny inference
*   **t** (numeric) - Transition probability
*   **gamma** (numeric) - Dispersion parameter for the Beta-Binomial allele model
*   **min_LLR** (numeric) - Minimum LLR to filter CNVs
*   **alpha** (numeric) - P value cutoff for diploid finding
*   **eps** (numeric) - Convergence threshold for ML tree search
*   **max_entropy** (numeric) - Entropy threshold to filter CNVs
*   **init_k** (integer) - Number of clusters in the initial clustering
*   **min_cells** (integer) - Minimum number of cells to run HMM on
*   **tau** (numeric) - Factor to determine max_cost as a function of the number of cells (0-1)
*   **nu** (numeric) - Phase switch rate
*   **max_cost** (numeric) - Likelihood threshold to collapse internal branches
*   **n_cut** (integer) - Number of cuts on the phylogeny to define subclones
*   **min_depth** (integer) - Minimum allele depth
*   **common_diploid** (logical) - Whether to find common diploid regions in a group of peusdobulks
*   **min_overlap** (numeric) - Minimum CNV overlap threshold
*   **ncores** (integer) - Number of threads to use
*   **ncores_nni** (integer) - Number of threads to use for NNI
*   **random_init** (logical) - Whether to initiate phylogney using a random tree (internal use only)
*   **segs_loh** (dataframe) - Segments of clonal LOH to be excluded
*   **call_clonal_loh** (logical) - Whether to call segments with clonal LOH
*   **verbose** (logical) - Verbosity
*   **diploid_chroms** (vector) - Known diploid chromosomes
*   **segs_consensus_fix** (dataframe) - Pre-determined segmentation of consensus CNVs
*   **use_loh** (logical) - Whether to include LOH regions in the expression baseline
*   **min_genes** (integer) - Minimum number of genes to call a segment
*   **skip_nj** (logical) - Whether to skip NJ tree construction and only use UPGMA
*   **multi_allelic** (logical) - Whether to call multi-allelic CNVs
*   **p_multi** (numeric) - P value cutoff for calling multi-allelic CNVs
*   **plot** (logical) - Whether to plot results
*   **check_convergence** (logical) - Whether to check for convergence
*   **exclude_neu** (logical) - Whether to exclude neutral segments
```

--------------------------------

### Numbat$cutree()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Re-defines subclones on the phylogeny.

```APIDOC
## Method `cutree()`

### Description
Re-define subclones on the phylogeny.

### Usage

```R
Numbat$cutree(max_cost = 0, n_cut = 0)
```

### Arguments

* `max_cost` (numeric) - Likelihood threshold to collapse internal branches
* `n_cut` (integer) - Number of cuts on the phylogeny to define subclones
```

--------------------------------

### check_exp_ref

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/check_exp_ref.html

Checks the format of the expression reference profile.

```APIDOC
## check_exp_ref

### Description
Checks the format of the expression reference profile.

### Usage

```R
check_exp_ref(lambdas_ref)
```

### Arguments

#### lambdas_ref
- **lambdas_ref** (matrix) - Expression reference profile

### Value

matrix Expression reference profile
```

--------------------------------

### Display Clonal Assignment Posteriors

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/results.html

Displays the first few rows of the clone posterior dataframe, showing cell, optimal clone assignment, and posterior probabilities for each clone. Useful for understanding cell lineage.

```r
nb$clone_post %>% head() %>% select(cell, clone_opt, p_1, p_2, p_3, p_4)
```

--------------------------------

### Numbat$plot_clone_profile()

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/Numbat.html

Plots clone CNV profiles.

```APIDOC
## Method `plot_clone_profile()`

### Description
Plot clone cnv profiles.

### Usage

```R
Numbat$plot_clone_profile(...)
```

### Arguments

* `...` - additional parameters passed to plot_clone_profile()
```

--------------------------------

### simplify_history

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/simplify_history.html

Simplifies the mutational history based on likelihood evidence.

```APIDOC
## simplify_history

### Description
Simplifies the mutational history based on likelihood evidence.

### Usage

```R
simplify_history(G, l_matrix, max_cost = 150, n_cut = 0, verbose = TRUE)
```

### Arguments

#### G
igraph Mutation graph

#### l_matrix
matrix Mutation placement likelihood matrix (node by mutation)

#### max_cost
(numeric) Maximum cost for simplification. Defaults to 150.

#### n_cut
(numeric) Number of cuts to make. Defaults to 0.

#### verbose
(logical) Whether to print verbose output. Defaults to TRUE.

### Value

igraph Mutation graph
```

--------------------------------

### Generate single-cell allele counts with cellsnp-lite

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/articles/mouse.html

Generates single-cell allele counts for SNP positions using cellsnp-lite. This command requires the BAM file, a barcode file, the VCF file, and specifies parameters for minimum minor allele frequency and count.

```bash
cellsnp-lite \
    -s $cellrangerout/outs/possorted_genome_bam.bam \
    -b $cellrangerout/outs/filtered_feature_bc_matrix/barcodes.tsv.gz \
    -O ./pileup \
    -R ./129S1_SvImJ.sites.vcf.gz \
    -p 25 \
    --minMAF 0 \
    --minCOUNT 1
```

--------------------------------

### log_mem

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/log_mem.html

Logs the current memory usage. This function is part of the diagnostic utilities in Numbat.

```APIDOC
## log_mem

### Description
Logs the current memory usage. This function is part of the diagnostic utilities in Numbat.

### Usage

    log_mem()

### Details

This function is developed by Teng Gao, Ruslan Soldatov, Hirak Sarkar, Evan Biederstedt, Peter Kharchenko.

Source: [`R/diagnostics.R`](https://github.com/kharchenkolab/numbat/blob/HEAD/R/diagnostics.R)
```

--------------------------------

### binary_entropy

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/binary_entropy.html

Calculates the entropy for a binary variable.

```APIDOC
## binary_entropy

### Description
Calculates the entropy for a binary variable.

### Usage

```R
binary_entropy(p)
```

### Parameters

*   **p** (numeric) - The probability of the event.
```

--------------------------------

### get_allele_hmm

Source: https://github.com/kharchenkolab/numbat/blob/main/docs/reference/get_allele_hmm.html

Calculates an allele Hidden Markov Model (HMM) using paternal allele counts, total allele counts, phase switch probabilities, haplotype imbalance, and overdispersion.

```APIDOC
## get_allele_hmm

### Description
Calculates an allele Hidden Markov Model (HMM).

### Usage

```R
get_allele_hmm(pAD, DP, p_s, theta, gamma = 20)
```

### Arguments

#### `pAD`
- **Type**: integer vector
- **Description**: Paternal allele counts.

#### `DP`
- **Type**: integer vector
- **Description**: Total allele counts.

#### `p_s`
- **Type**: numeric vector
- **Description**: Phase switch probabilities.

#### `theta`
- **Type**: numeric
- **Description**: Haplotype imbalance.

#### `gamma`
- **Type**: numeric
- **Description**: Overdispersion in the allele-specific expression. Defaults to 20.

### Value

- **Type**: HMM object
- **Description**: An object representing the allele HMM.
```