DOCSEARCHbyAlgolia
Submit Docs

CopyKAT

repository·master·Indexed 43 days ago

https://github.com/navinlabcode/copykat

A computational tool for inferring genomic copy number and subclonal structure from high-throughput single-cell RNAseq data. CopyKAT distinguishes aneuploid tumor cells from diploid normal cells and identifies tumor subclones at 5MB resolution using the copykat() function.

Tokens
1.9K
Snippets
5
Records
9
Agent score
5%

What's inside CopyKAT

  1. Handle multiple samples in CopyKAT

    master
    When analyzing multiple samples, it is recommended to run CopyKAT on each sample individually in parallel to avoid batch effects. Once individual runs are complete, you can combine the bin_by_cell.txt results across samples for downstream analysis, as they share the same set of genomic bins. Do not combine gene_by_cell.txt files directly, as the gene lists may differ between samples.

  2. Define subpopulations of aneuploid tumor cells

    master

    After running CopyKAT, you can identify and cluster aneuploid cells (tumor cells) to define subclonal populations. This is typically done by filtering the prediction results for aneuploid cells, extracting their corresponding Copy Number Alteration (CNA) data, and performing hierarchical clustering (e.g., using hclust with ward.D2 on Euclidean distances).

    # 1. Extract cell names predicted as aneuploid
tumor.cells <- pred.test$cell.names[which(pred.test$copykat.pred=="aneuploid")]

# 2. Extract CNA matrix for these tumor cells
tumor.mat <- CNA.test[, which(colnames(CNA.test) %in% tumor.cells)]

# 3. Perform hierarchical clustering to define subpopulations
hcc <- hclust(parallelDist::parDist(t(tumor.mat),threads =4, method = "euclidean"), method = "ward.D2")
hc.umap <- cutree(hcc,2) # Divide into 2 subpopulations

# 4. Visualize using a heatmap (example using heatmap.3)
# (Note: requires setup of color palettes and chromosome data)
heatmap.3(t(tumor.mat), ...)

  3. Prepare the raw gene expression matrix input

    master

    CopyKAT requires a raw gene expression matrix where gene IDs (symbols or Ensembl IDs) are in rows and cell names are in columns. The values should be UMI counts, though TPM or total read counts are also supported.

    If using 10X Genomics CellRanger V3 output, you can generate the required matrix using Seurat as shown below:

    library(Seurat)
raw <- Read10X(data.dir = data.path.to.cellranger.outs)
raw <- CreateSeuratObject(counts = raw, project = "copycat.test", min.cells = 0, min.features = 0)
exp.rawdata <- as.matrix(raw@assays$RNA@counts)

# Save for future use
write.table(exp.rawdata, file="exp.rawdata.txt", sep="\t", quote = FALSE, row.names = TRUE)

  4. Install CopyKAT from GitHub

    master

    To install CopyKAT, use the devtools package to install directly from the GitHub repository. If you need to update to a new version, first remove the existing package and detach it before reinstalling.

    # Install
library(devtools)
install_github("navinlabcode/copykat")

# Update (remove old version first)
remove.packages("copykat")
detach("package:copykat")

  5. Handle pediatric and liquid tumors with low CNA counts

    master

    CopyKAT may struggle to distinguish between tumor and normal cells in pediatric or liquid tumors where Copy Number Alterations (CNAs) are sparse. To prevent analysis failure, you can use one of two strategies:

    1. Provide known normal cells: Input a vector containing the names of known normal cells from the same dataset.
    2. Search for T cells: Attempt to identify and use T cells as a reference for normal cells.

  6. Extract prediction and CNA results from CopyKAT object

    master

    After running copykat(), you can extract the prediction results (cell types) and the Copy Number Aberration (CNA) matrix from the returned object.

    • copykat.test$prediction: A data frame containing cell predictions (e.g., aneuploid, diploid, or not defined).
    • copykat.test$CNAmat: A data frame containing the estimated copy number profiles.
    # Extract predictions and filter for defined cells
pred.test <- data.frame(copykat.test$prediction)
pred.test <- pred.test[which(pred.test$copykat.pred %in% c("aneuploid","diploid")),]

# Extract CNA matrix
CNA.test <- data.frame(copykat.test$CNAmat)

  7. Run CopyKAT to infer copy number and cell types

    master

    Use the copykat() function to perform the main analysis. This function calculates single-cell copy number profiles, predicts tumor/normal cell states, and infers tumor subclones.

    Key Parameters:

    • rawmat: The input UMI count matrix.
    • id.type: Type of gene IDs. Use "S" or "Symbol" for gene symbols.
    • ngene.chr: Minimum number of genes required per chromosome (default is 5).
    • win.size: Number of genes per segment (default is 25; range 15-150).
    • KS.cut: Segmentation parameter (default 0.1; range 0.05-0.15). Higher values decrease sensitivity.
    • distance: Clustering distance method. Options include "euclidean" (favors larger CN segments) and correlational distances like "1-"pearson" or "1-"spearman" (favors noisy data).
    • norm.cell.names: A vector of known normal cell names (default NULL).
    • cell.line: Set to "yes" for cell line data (uses synthetic baseline); default is "no" for tissue samples.
    • output.seg: Set to "TRUE" to generate a .seg file for IGV visualization.
    • n.cores: Number of cores for parallel computation (default 1).
    library(copykat)
copykat.test <- copykat(
  rawmat=exp.rawdata, 
  id.type="S", 
  ngene.chr=5, 
  win.size=25, 
  KS.cut=0.1, 
  sam.name="test", 
  distance="euclidean", 
  norm.cell.names="",
  output.seg="FALSE", 
  plot.genes="TRUE", 
  genome="hg20",
  n.cores=1
)

  8. Understand CopyKAT intermediate output files

    master

    In version 1.2.5, CopyKAT generates two intermediate files before the final automatic prediction. These are useful for downstream analysis, especially when normal cell names are provided:

    1. copykat_raw_results_gene_by_cell.txt: Cells are referred to as normal, smoothed with DLM, and segmented with MCMC. Note: Gene lists may vary between samples and cannot be easily combined.
    2. copykat_raw_results_bin_by_cell.txt: Cells are referred to as normal, smoothed with DLM, segmented with MCMC, and converted to genomic bins. Note: Genomic bins are consistent across runs/samples and can be freely combined for downstream analysis.

  9. Available annotation data in CopyKAT

    master

    CopyKAT includes several useful annotation datasets for genomic analysis:

    • full.anno: Full annotation of 56,051 genes (hg38) including absolute positions, chr, start, end, ensemble id, gene symbol, and G band.
    • full.anno.mm10: Full annotation of 51,450 genes (mm10) including absolute positions, chr, start, end, ensemble id, gene symbol, and G band.
    • DNA.hg20: Coordinates in hg38 of the 220kb variable bins (excluding the Y chromosome).
    • cyclegenes: List of genes that are removed from the CopyKAT analysis.
    • exp.rawdata: UMI matrix from a breast tumor (example data).