Contents

1 Introduction

A variety of exogenous exposures or endogenous biological processes can contribute to the overall mutational load observed in human tumors. Many different mutational patterns, or “mutational signatures”, have been identified across different tumor types. These signatures can provide a record of environmental exposure and can give clues about the etiology of carcinogenesis. The Mutational Signature Comprehensive Analysis Toolkit (musicatk) has utilities for extracting variants from a variety of file formats, contains multiple methods for discovery of novel signatures or prediction of known signatures, as well as many types of downstream visualizations for exploratory analysis. This package has the ability to parse and combine multiple motif classes in the mutational signature discovery or prediction processes. Mutation motifs include single base substitutions (SBS), double base substitutions (DBS), insertions (INS) and deletions (DEL).

2 Installation

Currently musicatk can be installed from on Bioconductor using the following code:

if (!requireNamespace("BiocManager", quietly=TRUE)){
    install.packages("BiocManager")}
BiocManager::install("musicatk")

To install the latest version from Github, use the following code:

if (!requireNamespace("devtools", quietly=TRUE)){
    install.packages("devtools")}

library(devtools)
install_github("campbio/musicatk")

The package can be loaded using the library command.

library(musicatk)

3 Setting up a musica object

In order to discover or predict mutational signatures, we must first set up our musica object by 1) extracting variants from files or objects such as VCFs and MAFs, 2) selecting the appropriate reference genome 3) creating a musica object, and 4) building a count tables for our variants of interest.

3.1 Extracting variants

Variants can be extracted from various formats using the following functions:

  • The extract_variants_from_vcf_file() function will extract variants from a VCF file. The file will be imported using the readVcf function from the VariantAnnotation package and then the variant information will be extracted from this object.
  • The extract_variants_from_vcf() function extracts variants from a CollapsedVCF or ExpandedVCF object from the VariantAnnotation package.
  • The extract_variants_from_maf_file() function will extract variants from a file in Mutation Annotation Format (MAF) used by TCGA.
  • The extract_variants_from_maf() function will extract variants from a MAF object created by the maftools package.
  • The extract_variants_from_matrix() function will get the information from a matrix or data.frame like object that has columns for the chromosome, start position, end position, reference allele, mutation allele, and sample name.
  • The extract_variants() function will extract variants from a list of objects. These objects can be any combination of VCF files, VariantAnnotation objects, MAF files, MAF objects, and data.frame objects.

Below are some examples of extracting variants from MAF and VCF files:

# Extract variants from a MAF File
lusc_maf <- system.file("extdata", "public_TCGA.LUSC.maf", package = "musicatk") 
lusc.variants <- extract_variants_from_maf_file(maf_file = lusc_maf)

# Extract variants from an individual VCF file
luad_vcf <- system.file("extdata", "public_LUAD_TCGA-97-7938.vcf", 
                         package = "musicatk")
luad.variants <- extract_variants_from_vcf_file(vcf_file = luad_vcf)

# Extract variants from multiple files and/or objects
melanoma_vcfs <- list.files(system.file("extdata", package = "musicatk"), 
                           pattern = glob2rx("*SKCM*vcf"), full.names = TRUE)
variants <- extract_variants(c(lusc_maf, luad_vcf, melanoma_vcfs))
## 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |==============                                                        |  20%
  |                                                                            
  |============================                                          |  40%
  |                                                                            
  |==========================================                            |  60%
  |                                                                            
  |========================================================              |  80%
  |                                                                            
  |======================================================================| 100%

3.2 Choosing a genome

musicatk uses BSgenome objects to access genome sequence information that flanks each mutation which is used bases for generating mutation count tables. BSgenome objects store full genome sequences for different organisms. A full list of supported organisms can be obtained by running available.genomes() after loading the BSgenome library. Custom genomes can be forged as well (see BSgenome documentation). musicatk provides a utility function called select_genome() to allow users to quickly select human genome build versions “hg19” and “hg38” or mouse genome builds “mm9” and “mm10”. The reference sequences for these genomes are in UCSC format (e.g. chr1).

g <- select_genome("hg38")

3.3 Creating a musica object

The last preprocessing step is to create an object with the variants and the genome using the create_musica function. This function will perform checks to ensure that the chromosome names and reference alleles in the input variant object match those in supplied BSgenome object. These checks can be turned off by setting check_ref_chromosomes = FALSE and check_ref_bases = FALSE, respectively. This function also looks for adjacent single base substitutions (SBSs) and will convert them to double base substitutions (DBSs). To disable this automatic conversion, set convert_dbs = FALSE.

musica <- create_musica(x = variants, genome = g)
## Checking that chromosomes in the 'variant' object match chromosomes in the 'genome' object.
## Checking that the reference bases in the 'variant' object match the reference bases in the 'genome' object.
## Warning in .check_variant_ref_in_genome(dt = dt, genome = genome): Reference
## bases for 6 out of 911 variants did not match the reference base in the
## 'genome'. Make sure the genome reference is correct.
## Converting adjacent SBS into DBS
## 5 SBS converted to DBS
## Standardizing INS/DEL style
## Removing 4 compound insertions
## Removing 15 compound deletions
## Converting 7 insertions
## Converting 1 deletions

4 Creating mutation count tables

Motifs are the building blocks of mutational signatures. Motifs themselves are a mutation combined with other genomic information. For instance, SBS96 motifs are constructed from an SBS mutation and one upsteam and one downstream base sandwiched together. We build tables by counting these motifs for each sample.

build_standard_table(musica, g = g, table_name = "SBS96")

Here is a list of mutation tables that can be created by setting the table_name parameter in the build_standard_table function:

5 Discovering Signatures and Exposures

Mutational signature discovery is the process of deconvoluting a matrix containing counts for each mutation type in each sample into two matrices: 1) a signature matrix containing the probability of each mutation motif in signature and 2) an exposure matrix containing the estimated counts of each signature in each sample. Discovery and prediction results are save in a musica_result object that includes both the signatures and sample exposures.

result <- discover_signatures(musica = musica, table_name = "SBS96", 
                              num_signatures = 3, method = "lda", nstart = 10)

Supported signature discovery algorithms include:

Both have built-in seed capabilities for reproducible results, nstarts for multiple independent chains from which the best final result will be chosen. NMF also allows for parallel processing via par_cores.

To get the signatures or exposures from the result object, the following functions can be used:

# Extract the exposure matrix
expos <- exposures(result)
expos[1:3,1:3]
##            TCGA-56-7582-01A-11D-2042-08 TCGA-77-7335-01A-11D-2042-08
## Signature1                 189.92890956                  74.58640786
## Signature2                   0.03554522                 193.37804112
## Signature3                   0.03554522                   0.03555103
##            TCGA-94-7557-01A-11D-2122-08
## Signature1                   0.03553278
## Signature2                 116.92893445
## Signature3                   0.03553278
# Extract the signature matrix
sigs <- signatures(result)
sigs[1:3,1:3]
##           Signature1  Signature2   Signature3
## C>A_ACA 1.262464e-02 0.013012144 2.293541e-62
## C>A_ACC 1.646964e-02 0.008469406 3.354501e-64
## C>A_ACG 2.424973e-11 0.009309249 5.083041e-94

6 Plotting

6.1 Signatures

Barplots showing the probability of each mutation type in each signature can be plotted with the plot_signatures function:

plot_signatures(result)

By default, the scales on the y-axis are forced to be the same across all signatures. This behavior can be turned off by setting same_scale = FALSE. Signatures can be re-named based on prior knowledge and displayed in the plots:

name_signatures(result, c("Smoking", "APOBEC", "UV"))
plot_signatures(result)

6.2 Exposures

Barplots showing the exposures in each sample can be plotted with the plot_exposures function:

plot_exposures(result, plot_type = "bar")

The proportion of each exposure in each tumor can be shown by setting proportional = TRUE:

plot_exposures(result, plot_type = "bar", proportional = TRUE)

Counts for individual samples can also be plotted with the plot_sample_counts function:

samples <- sample_names(musica)
plot_sample_counts(musica, sample_names = samples[c(3,4,5)], table_name = "SBS96")

6.3 Comparison to external signatures (e.g. COSMIC)

A common analysis is to compare the signatures estimated in a dataset to those generated in other datasets or to those in the COSMIC database. We have a set of functions that can be used to easily perform pairwise correlations between signatures. The compare_results functions compares the signatures between two musica_result objects. The compare_cosmic_v2 will correlate the signatures between a musica_result object and the SBS signatures in COSMIC V2. For example:

compare_cosmic_v2(result, threshold = 0.75)

##      cosine x_sig_index y_sig_index x_sig_name  y_sig_name
## 2 0.9729624           3           7         UV  Signature7
## 1 0.7922749           1           4    Smoking  Signature4
## 3 0.7734316           3          11         UV Signature11
## 4 0.7540679           3          30         UV Signature30

In this example, our Signatures 1 and 2 were most highly correlated to COSMIC Signature 7 and 4, respectively, so this may indicate that samples in our dataset were exposed to UV radiation or cigarette smoke. Only pairs of signatures who have a correlation above the threshold parameter will be returned. If no pairs of signatures are found, then you may want to consider lowering the threshold. The default correlation metric is the cosine similarity, but this can be changed to using 1 - Jensen-Shannon Divergence by setting metric = "jsd" Signatures can also be correlated to those in the COSMIC V3 database using the compare_cosmic_v3 function.

7 Predicting exposures using pre-existing signatures

Instead of discovering mutational signatures and exposures from a dataset de novo, one might get better results by predicting the exposures of signatures that have been previously estimated in other datasets. We incorporate several methods for estimating exposures given a set of pre-existing signatures. For example, we can predict exposures for COSMIC signatures 1, 4, 7, and 13 in our current dataset:

# Load COSMIC V2 data
data("cosmic_v2_sigs")

# Predict pre-existing exposures using the "lda" method
pred_cosmic <- predict_exposure(musica = musica, table_name = "SBS96",
                               signature_res = cosmic_v2_sigs,
                               signatures_to_use =  c(1, 4, 7, 13),
                               algorithm = "lda")

# Plot exposures
plot_exposures(pred_cosmic, plot_type = "bar")

The cosmic_v2_sigs object is just a musica_result object containing COSMIC V2 signatures without any sample or exposure information. Note that if signatures_to_use is not supplied by the user, then exposures for all signatures in the result object will be estimated. We can predict exposures for samples in any musica object from any musica_result object as long as the same mutation schema was utilized.

We can list which signatures are present in each tumor type according to the COSMIC V2 database. For example, we can find which signatures are present in lung cancers:

cosmic_v2_subtype_map("lung")
## [1] "lung adeno"
## [1]  1  2  4  5  6 13 17
## [1] "lung  small cell"
## [1]  1  4  5 15
## [1] "lung  squamous"
## [1]  1  2  4  5 13

We can predict exposures for samples in a musica object using the signatures from any musica_result object. Just for illustration, we will predict exposures using the estimated signatures from musica_result object we created earlier:

pred_our_sigs <- predict_exposure(musica = musica, table_name = "SBS96",
                                 signature_res = result, algorithm = "lda")

Of course, this example is not very useful because we are predicting exposures using signatures that were learned on the same set of samples. Most of the time, you want to give the signature_res parameter a musica_result object that wss generated using independent samples from those in the musica object. As mentioned above, different signatures in different result objects can be compared to each other using the compare_results function:

compare_results(result = pred_cosmic, other_result = pred_our_sigs, 
                threshold = 0.60)

##      cosine x_sig_index y_sig_index  x_sig_name y_sig_name
## 2 0.9729624           3           3  Signature7         UV
## 1 0.7922749           2           1  Signature4    Smoking
## 3 0.7227123           4           2 Signature13     APOBEC

8 Comparing samples between groups using Sample Annotations

8.1 Adding sample annotations

We first must add an annotation to the musica or musica_result object

annot <- read.table(system.file("extdata", "sample_annotations.txt", 
                                package = "musicatk"), sep = "\t", header=TRUE)
samp_annot(result, "Tumor_Subtypes") <- annot$Tumor_Subtypes

Note that the annotations can also be added directly the musica object in the beginning using the same function: samp_annot(musica, "Tumor_Subtypes") <- annot$Tumor_Subtypes. These annotations will then automatically be included in any down-stream result object.

  • Be sure that the annotation vector being supplied is in the same order as the samples in the musica or musica_result object. You can view the sample order with the sample_names function:
sample_names(result)
## [1] TCGA-56-7582-01A-11D-2042-08 TCGA-77-7335-01A-11D-2042-08
## [3] TCGA-94-7557-01A-11D-2122-08 TCGA-97-7938-01A-11D-2167-08
## [5] TCGA-EE-A3J5-06A-11D-A20D-08 TCGA-ER-A197-06A-32D-A197-08
## [7] TCGA-ER-A19O-06A-11D-A197-08
## 7 Levels: TCGA-56-7582-01A-11D-2042-08 ... TCGA-ER-A19O-06A-11D-A197-08

8.2 Plotting exposures by a Sample Annotation

As mentioned previously, the plot_exposures function can plot sample exposures in a musica_result object. It can group exposures by either a sample annotation or by a signature by setting the group_by parameter. Here will will group the exposures by the Tumor_Subtype annotation:

plot_exposures(result, plot_type = "bar", group_by = "annotation", 
               annotation = "Tumor_Subtypes")

The distribution of exposures with respect to annotation can be viewed using boxplots by setting plot_type = "box" and group_by = "annotation":

plot_exposures(result, plot_type = "box", group_by = "annotation", annotation = "Tumor_Subtypes")

Note that the name of the annotation must be supplied via the annotation parameter. Boxplots can be converted to violin plots by setting plot_type = "violin". To compare the level of each exposure across sample groups within a signature, we can set group_by = "signature" and color_by = "annotation":

plot_exposures(result, plot_type = "box", group_by = "signature", 
               color_by = "annotation", annotation = "Tumor_Subtypes")

8.3 Visualizing samples in 2D using UMAP

The create_umap function embeds samples in 2 dimensions using the umap function from the uwot package. The major parameters for fine tuning the UMAP are n_neighbors, min_dist, and spread. See ?uwot::umap for more information on these parameters.

create_umap(result = result)
## The parameter 'n_neighbors' cannot be bigger than the total number of samples. Setting 'n_neighbors' to 7.

The plot_umap function will generate a scatter plot of the UMAP coordinates. The points of plot will be colored by the level of a signature by default:

plot_umap(result = result)

By default, the exposures for each sample will share the same color scale. However, exposures for some signatures may have really high levels compared to others. To make a plot where exposures for each signature will have their own color scale, you can set same_scale = FALSE:

plot_umap(result = result, same_scale = FALSE)

Lastly, points can be colored by a Sample Annotation by setting color_by = "annotation" and annotation to the name of the annotation:

plot_umap(result = result, color_by = "annotation", 
          annotation = "Tumor_Subtypes", add_annotation_labels = TRUE)

When add_annotation_labels = TRUE, the centroid of each group is identified using medians and the labels are plotted on top of the centroid.

9 Use of Plotly in plotting

plot_signatures, plot_exposures, and plot_umap, all have builty in ggplotly capabilities. Simply specifying plotly = TRUE enables interactive plots that allows examination of individuals sections, zooming and resizing, and turning on and off annotation types and legend values.

plot_signatures(result, plotly = TRUE)
plot_exposures(result, plotly = TRUE)
plot_umap(result, plotly = TRUE)
## Warning: `group_by_()` is deprecated as of dplyr 0.7.0.
## Please use `group_by()` instead.
## See vignette('programming') for more help
## This warning is displayed once every 8 hours.
## Call `lifecycle::last_warnings()` to see where this warning was generated.

10 Note on reproducibility

Several functions make use of stochastic algorithms or procedures which require the use of random number generator (RNG) for simulation or sampling. To maintain reproducibility, all these functions should be called using set_seed(1) or withr::with_seed(seed, function()) to make sure same results are generatedeach time one of these functions is called. Using with_seed for reproducibility has the advantage of not interfering with any other user seeds, but using one or the other is important for several functions including discover_signatures, predict_exposure, and create_umap, as these functions use stochastic processes that may produce different results when run multiple times with the same settings.

seed <- 1
reproducible_prediction <- withr::with_seed(seed, 
                                            predict_exposure(musica = musica, 
                                                         table_name = "SBS96",
                                 signature_res = result, algorithm = "lda"))

11 Combine count tables

Different count tables can be combined into one using the combine_count_tables function. For example, the SBS96 and the DBS tables could be combined and mutational signature discovery could be performed across both mutations modalities. Tables with information about the same types of variants (e.g. two related SBS tables) should generally not be combined and used together.

data(dbs_musica)

build_standard_table(dbs_musica, g, "SBS96")
build_standard_table(dbs_musica, g, "DBS")

combine_count_tables(musica = dbs_musica, to_comb = c("SBS96", "DBS"), 
                     name = "sbs_dbs", description = "An example combined 
                     table, combining SBS96 and DBS", overwrite = TRUE)

12 Custom count tables

Custom count tables can be created from user-defined mutation-level annotations using the build_custom_table function. These can be used and combined just like other tables for discovery and prediction. Custom tables are built from a variant annotation (e.g. Transcript_Strand). The motifs can be provided manually using data_factor or will be generated automatically from the range of existing data in that column.

annotate_transcript_strand(musica, "19", build_table = FALSE)
##   403 genes were dropped because they have exons located on both strands
##   of the same reference sequence or on more than one reference sequence,
##   so cannot be represented by a single genomic range.
##   Use 'single.strand.genes.only=FALSE' to get all the genes in a
##   GRangesList object, or use suppressMessages() to suppress this message.
build_custom_table(musica = musica, variant_annotation = "Transcript_Strand", 
                   name = "Transcript_Strand", 
                   description = "A table of transcript strand of variants", 
                   data_factor = c("T", "U"), overwrite = TRUE)

13 Session Information

sessionInfo()
## R version 4.0.3 (2020-10-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 18.04.5 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.12-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.12-bioc/R/lib/libRlapack.so
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## attached base packages:
## [1] parallel  stats     graphics  grDevices utils     datasets  methods  
## [8] base     
## 
## other attached packages:
##  [1] musicatk_1.0.0      NMF_0.23.0          bigmemory_4.5.36   
##  [4] Biobase_2.50.0      BiocGenerics_0.36.0 cluster_2.1.0      
##  [7] rngtools_1.5        pkgmaker_0.32.2     registry_0.5-1     
## [10] BiocStyle_2.18.0   
## 
## loaded via a namespace (and not attached):
##   [1] bigmemory.sri_0.1.3                     
##   [2] colorspace_1.4-1                        
##   [3] ellipsis_0.3.1                          
##   [4] modeltools_0.2-23                       
##   [5] BSgenome.Hsapiens.UCSC.hg38_1.4.3       
##   [6] XVector_0.30.0                          
##   [7] GenomicRanges_1.42.0                    
##   [8] farver_2.0.3                            
##   [9] ggrepel_0.8.2                           
##  [10] bit64_4.0.5                             
##  [11] RSpectra_0.16-0                         
##  [12] AnnotationDbi_1.52.0                    
##  [13] xml2_1.3.2                              
##  [14] codetools_0.2-16                        
##  [15] splines_4.0.3                           
##  [16] doParallel_1.0.16                       
##  [17] knitr_1.30                              
##  [18] maftools_2.6.0                          
##  [19] jsonlite_1.7.1                          
##  [20] Cairo_1.5-12.2                          
##  [21] Rsamtools_2.6.0                         
##  [22] gridBase_0.4-7                          
##  [23] dbplyr_1.4.4                            
##  [24] uwot_0.1.8                              
##  [25] BiocManager_1.30.10                     
##  [26] compiler_4.0.3                          
##  [27] httr_1.4.2                              
##  [28] lazyeval_0.2.2                          
##  [29] assertthat_0.2.1                        
##  [30] Matrix_1.2-18                           
##  [31] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2 
##  [32] htmltools_0.5.0                         
##  [33] prettyunits_1.1.1                       
##  [34] tools_4.0.3                             
##  [35] NLP_0.2-1                               
##  [36] gtable_0.3.0                            
##  [37] glue_1.4.2                              
##  [38] GenomeInfoDbData_1.2.4                  
##  [39] reshape2_1.4.4                          
##  [40] dplyr_1.0.2                             
##  [41] rappdirs_0.3.1                          
##  [42] Rcpp_1.0.5                              
##  [43] TxDb.Hsapiens.UCSC.hg38.knownGene_3.10.0
##  [44] slam_0.1-47                             
##  [45] vctrs_0.3.4                             
##  [46] Biostrings_2.58.0                       
##  [47] rtracklayer_1.50.0                      
##  [48] crosstalk_1.1.0.1                       
##  [49] iterators_1.0.13                        
##  [50] xfun_0.18                               
##  [51] stringr_1.4.0                           
##  [52] lifecycle_0.2.0                         
##  [53] gtools_3.8.2                            
##  [54] XML_3.99-0.5                            
##  [55] zlibbioc_1.36.0                         
##  [56] scales_1.1.1                            
##  [57] BSgenome_1.58.0                         
##  [58] VariantAnnotation_1.36.0                
##  [59] hms_0.5.3                               
##  [60] MatrixGenerics_1.2.0                    
##  [61] SummarizedExperiment_1.20.0             
##  [62] RColorBrewer_1.1-2                      
##  [63] yaml_2.2.1                              
##  [64] curl_4.3                                
##  [65] gridExtra_2.3                           
##  [66] memoise_1.1.0                           
##  [67] MCMCprecision_0.4.0                     
##  [68] ggplot2_3.3.2                           
##  [69] biomaRt_2.46.0                          
##  [70] stringi_1.5.3                           
##  [71] RSQLite_2.2.1                           
##  [72] S4Vectors_0.28.0                        
##  [73] foreach_1.5.1                           
##  [74] GenomicFeatures_1.42.0                  
##  [75] BiocParallel_1.24.0                     
##  [76] GenomeInfoDb_1.26.0                     
##  [77] rlang_0.4.8                             
##  [78] pkgconfig_2.0.3                         
##  [79] matrixStats_0.57.0                      
##  [80] bitops_1.0-6                            
##  [81] evaluate_0.14                           
##  [82] lattice_0.20-41                         
##  [83] purrr_0.3.4                             
##  [84] htmlwidgets_1.5.2                       
##  [85] GenomicAlignments_1.26.0                
##  [86] labeling_0.4.2                          
##  [87] cowplot_1.1.0                           
##  [88] bit_4.0.4                               
##  [89] tidyselect_1.1.0                        
##  [90] RcppAnnoy_0.0.16                        
##  [91] plyr_1.8.6                              
##  [92] magrittr_1.5                            
##  [93] bookdown_0.21                           
##  [94] R6_2.4.1                                
##  [95] magick_2.5.0                            
##  [96] IRanges_2.24.0                          
##  [97] topicmodels_0.2-11                      
##  [98] generics_0.0.2                          
##  [99] combinat_0.0-8                          
## [100] DelayedArray_0.16.0                     
## [101] DBI_1.1.0                               
## [102] pillar_1.4.6                            
## [103] withr_2.3.0                             
## [104] survival_3.2-7                          
## [105] RCurl_1.98-1.2                          
## [106] tibble_3.0.4                            
## [107] crayon_1.3.4                            
## [108] plotly_4.9.2.1                          
## [109] BiocFileCache_1.14.0                    
## [110] rmarkdown_2.5                           
## [111] progress_1.2.2                          
## [112] grid_4.0.3                              
## [113] data.table_1.13.2                       
## [114] blob_1.2.1                              
## [115] digest_0.6.27                           
## [116] xtable_1.8-4                            
## [117] tm_0.7-7                                
## [118] tidyr_1.1.2                             
## [119] openssl_1.4.3                           
## [120] stats4_4.0.3                            
## [121] munsell_0.5.0                           
## [122] viridisLite_0.3.0                       
## [123] askpass_1.1