1 Introduction

The R package HiLDA is developed under the Bayesian framework to select the number of mutational signatures based on perplexity and cross-validation. The mutation signature is defined based on the independent model proposed by Shiraishi’s et al. 

1.1 Paper

  • Shiraishi et al. A simple model-based approach to inferring and visualizing cancer mutation signatures, bioRxiv, doi: http://dx.doi.org/10.1101/019901.

  • Zhi Yang, Paul Marjoram, Kimberly D. Siegmund. Selecting the number of mutational signatures using a perplexity-based measure and cross-validation.

2 Installing and loading the package

2.1 Installation

2.1.1 Bioconductor

selectKSigs requires several CRAN and Bioconductor R packages to be installed. Dependencies are usually handled automatically, when installing the package using the following commands:

install.packages("BiocManager")
BiocManager::install("selectKSigs")

[NOTE: Ignore the first line if you already have installed the BiocManager.]

You can also download the newest version from the GitHub using devtools:

devtools::install_github("USCbiostats/selectKSigs")

3 Input data

selectKSigs is a package built on some basic functions from pmsignature including how to read the input data. Here is an example from pmsignature on the input data, mutation features are elements used for categorizing mutations such as:

  • 6 substitutions (C>A, C>G, C>T, T>A, T>C and T>G)
  • 2 flanking bases (A, C, G and T)
  • transcription direction.

3.1 Mutation Position Format

sample1 chr1  100   A   C   
sample1 chr1    200 A   T   
sample1 chr2    100 G   T   
sample2 chr1    300 T   C   
sample3 chr3    400 T   C   
  • The 1st column shows the name of samples
  • The 2nd column shows the name of chromosome
  • The 3rd column shows the coordinate in the chromosome
  • The 4th column shows the reference base (A, C, G, or T).
  • The 5th colum shows the alternate base (A, C, G, or T).

4 Workflow

4.1 Get input data

Here, inputFile is the path for the input file. numBases is the number of flanking bases to consider including the central base (if you want to consider two 5’ and 3’ bases, then set 5). Also, you can add transcription direction information using trDir. numSig sets the number of mutation signatures estimated from the input data. You will see a warning message on some mutations are being removed.

library(HiLDA)
## Loading required package: ggplot2
library(tidyr)
library(ggplot2)
library(dplyr)
## 
## Attaching package: 'dplyr'
## The following objects are masked from 'package:stats':
## 
##     filter, lag
## The following objects are masked from 'package:base':
## 
##     intersect, setdiff, setequal, union
inputFile <- system.file("extdata/esophageal.mp.txt.gz", package="HiLDA")
G <- hildaReadMPFile(inputFile, numBases=5, trDir=TRUE)
## Warning in hildaReadMPFile(inputFile, numBases = 5, trDir = TRUE): Out of 24861
## mutations, we could obtaintranscription direction information for 24728
## mutation. Other mutations are removed.

Also, we also provided a small simulated dataset which contains 10 mutational catalogs and used it for demonstrating the key functions in selectKSigs. We start with loading the sample dataset G stored as extdata/sample.rdata.

library(selectKSigs)
load(system.file("extdata/sample.rdata", package = "selectKSigs"))

4.1.1 Perform the selecting process

After we read in the sample data G, we can run the process from selectKSigs. Here, we specify the inputG as G, the number of cross-validation folds, kfold to be 3, the number of replications, nRep, to be 3, and the upper limit of the K values for exploration to be 7.

4.1.2 Visualizing the results

After we obtained the results, we can plot each measure by the range of K values that were refitted during the calculation. The optimal value of K is achieved at its minimum value highlighted in grey.

results$Kvalue <- seq_len(nrow(results)) + 1
results_df <- gather(results, Method, value, -Kvalue) %>% 
  group_by(Method) %>%
  mutate(xmin = which.min(value) + 1 - 0.1,
         xmax = which.min(value) + 1 + 0.1)

ggplot(results_df) +
  geom_point(aes(x = Kvalue, y = value, color = Method), size = 2) +
  facet_wrap(~ Method, scales = "free") + 
  geom_rect(mapping = aes(xmin = xmin, xmax = xmax, 
                          ymin = -Inf, ymax = Inf),
            fill = 'grey', alpha = 0.05) +
  theme_bw()+
  xlab("Number of signatures")

4.2 Session info

Here is the output of sessionInfo() for reproducibility in the future.

sessionInfo()
## R Under development (unstable) (2023-10-22 r85388)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 22.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.19-bioc/R/lib/libRblas.so 
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              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       
## 
## time zone: America/New_York
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] selectKSigs_1.15.0   GenomicRanges_1.55.0 S4Vectors_0.41.0    
##  [4] IRanges_2.37.0       XVector_0.43.0       dplyr_1.1.3         
##  [7] tidyr_1.3.0          HiLDA_1.17.0         ggplot2_3.4.4       
## [10] BiocStyle_2.31.0    
## 
## loaded via a namespace (and not attached):
##   [1] DBI_1.1.3                              
##   [2] bitops_1.0-7                           
##   [3] biomaRt_2.59.0                         
##   [4] rlang_1.1.1                            
##   [5] magrittr_2.0.3                         
##   [6] matrixStats_1.0.0                      
##   [7] compiler_4.4.0                         
##   [8] RSQLite_2.3.1                          
##   [9] GenomicFeatures_1.55.0                 
##  [10] png_0.1-8                              
##  [11] vctrs_0.6.4                            
##  [12] stringr_1.5.0                          
##  [13] pkgconfig_2.0.3                        
##  [14] crayon_1.5.2                           
##  [15] fastmap_1.1.1                          
##  [16] magick_2.8.1                           
##  [17] dbplyr_2.3.4                           
##  [18] labeling_0.4.3                         
##  [19] utf8_1.2.4                             
##  [20] Rsamtools_2.19.0                       
##  [21] rmarkdown_2.25                         
##  [22] R2WinBUGS_2.1-21                       
##  [23] purrr_1.0.2                            
##  [24] bit_4.0.5                              
##  [25] xfun_0.40                              
##  [26] zlibbioc_1.49.0                        
##  [27] cachem_1.0.8                           
##  [28] GenomeInfoDb_1.39.0                    
##  [29] jsonlite_1.8.7                         
##  [30] progress_1.2.2                         
##  [31] blob_1.2.4                             
##  [32] DelayedArray_0.29.0                    
##  [33] BiocParallel_1.37.0                    
##  [34] parallel_4.4.0                         
##  [35] prettyunits_1.2.0                      
##  [36] R6_2.5.1                               
##  [37] bslib_0.5.1                            
##  [38] stringi_1.7.12                         
##  [39] rtracklayer_1.63.0                     
##  [40] boot_1.3-28.1                          
##  [41] rjags_4-14                             
##  [42] jquerylib_0.1.4                        
##  [43] Rcpp_1.0.11                            
##  [44] bookdown_0.36                          
##  [45] SummarizedExperiment_1.33.0            
##  [46] knitr_1.44                             
##  [47] Matrix_1.6-1.1                         
##  [48] tidyselect_1.2.0                       
##  [49] abind_1.4-5                            
##  [50] yaml_2.3.7                             
##  [51] codetools_0.2-19                       
##  [52] curl_5.1.0                             
##  [53] lattice_0.22-5                         
##  [54] tibble_3.2.1                           
##  [55] Biobase_2.63.0                         
##  [56] withr_2.5.1                            
##  [57] KEGGREST_1.43.0                        
##  [58] coda_0.19-4                            
##  [59] evaluate_0.22                          
##  [60] BiocFileCache_2.11.0                   
##  [61] xml2_1.3.5                             
##  [62] R2jags_0.7-1                           
##  [63] Biostrings_2.71.1                      
##  [64] filelock_1.0.2                         
##  [65] pillar_1.9.0                           
##  [66] BiocManager_1.30.22                    
##  [67] MatrixGenerics_1.15.0                  
##  [68] TxDb.Hsapiens.UCSC.hg19.knownGene_3.2.2
##  [69] stats4_4.4.0                           
##  [70] generics_0.1.3                         
##  [71] RCurl_1.98-1.12                        
##  [72] hms_1.1.3                              
##  [73] munsell_0.5.0                          
##  [74] scales_1.2.1                           
##  [75] gtools_3.9.4                           
##  [76] glue_1.6.2                             
##  [77] tools_4.4.0                            
##  [78] BiocIO_1.13.0                          
##  [79] BSgenome_1.71.0                        
##  [80] GenomicAlignments_1.39.0               
##  [81] forcats_1.0.0                          
##  [82] XML_3.99-0.14                          
##  [83] cowplot_1.1.1                          
##  [84] grid_4.4.0                             
##  [85] AnnotationDbi_1.65.0                   
##  [86] colorspace_2.1-0                       
##  [87] GenomeInfoDbData_1.2.11                
##  [88] restfulr_0.0.15                        
##  [89] cli_3.6.1                              
##  [90] rappdirs_0.3.3                         
##  [91] fansi_1.0.5                            
##  [92] S4Arrays_1.3.0                         
##  [93] gtable_0.3.4                           
##  [94] BSgenome.Hsapiens.UCSC.hg19_1.4.3      
##  [95] sass_0.4.7                             
##  [96] digest_0.6.33                          
##  [97] BiocGenerics_0.49.0                    
##  [98] SparseArray_1.3.0                      
##  [99] farver_2.1.1                           
## [100] rjson_0.2.21                           
## [101] memoise_2.0.1                          
## [102] htmltools_0.5.6.1                      
## [103] lifecycle_1.0.3                        
## [104] httr_1.4.7                             
## [105] bit64_4.0.5