Contents

1 Installation

To install this package, start R (version “4.2”) and enter:

# Install via BioConductor
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("katdetectr")
library(katdetectr)

2 Introduction

katdetectr is an R package for the detection, characterization and visualization of localized hypermutated regions, often referred to as kataegis.

The general workflow of katdetectr can be summarized as follows:

  1. Import of genomic variants; VCF, MAF or VRanges objects.
  2. Detection of kataegis foci.
  3. Visualization of segmentation and kataegis foci.

Please see the Application Note (under submission) for additional background and details of katdetectr. The application note also section regarding the performance of katdetectr and other kataegis detection packages: maftools, ClusteredMutations, SeqKat, kataegis, and SigProfilerClusters.

We have made katdetectr available on BioConductor as this insures reliability, and operability on common operation systems (Linux, Mac, and Windows).

Below, the katdetectr workflow is performed in a step-by-step manner on publicly-available datasets which are included within this package.

3 Importing genomic variants

Genomic variants from multiple common data-formats (VCF/MAF and VRanges objects) can be imported into katdetectr.

# Genomic variants stored within the VCF format.
pathToVCF <- system.file(package = "katdetectr", "extdata/CPTAC_Breast.vcf")

# Genomic variants stored within the MAF format.
pathToMAF <- system.file(package = "katdetectr", "extdata/APL_primary.maf")

# In addition, we can generate synthetic genomic variants including kataegis foci.
# using generateSyntheticData(). This will output a VRanges object.
syntheticData <- generateSyntheticData(nBackgroundVariants = 2500, nKataegisFoci = 1)

4 Detection of kataegis foci

Using detectKataegis(), we can employ changepoint detection to detect distinct clusters of varying IMD and size.

Imported samples can contain either single or multiple samples, in which case records can be aggregated by setting aggregateRecords = TRUE. Overlapping genomic variants (e.g., an InDel and SNV) are reduced into a single record.

From the genomic variants data, we calculate the intermutation distance (IMD). The IMD is defined as the genomic distance (in bp) between a genomic variant and it’s respective nearest upstream genomic variant (5’ A <- B 3’). Following, changepoint analysis is performed on the IMD of the genomic variants which results in segments. Lastly, a segment is labelled as kataegis foci if the segment fits the following parameters: minSizeKataegis = 6 and maxMeanIMD = 1000.

# Detect kataegis foci within the given VCF file.
kdVCF <- detectKataegis(genomicVariants = pathToVCF)
    
# # Detect kataegis foci within the given MAF file.
# As this file contains multiple samples, we set aggregateRecords = TRUE.
kdMAF <- detectKataegis(genomicVariants = pathToMAF, aggregateRecords = TRUE)

# Detect kataegis foci within the synthetic data.
kdSynthetic <- detectKataegis(genomicVariants = syntheticData)

All relevant input and subsequent results are stored within KatDetect objects. Using summary(), show() and/or print(), we can generate overviews of these KatDetect object(s).

summary(kdVCF)
## Sample name:                                 CPTAC 
## Total number of genomic variants:            3684 
## Total number of putative Kataegis foci:      9 
## Total number of variants in a Kataegis foci: 133
print(kdVCF)
## Sample name:                                 CPTAC 
## Total number of genomic variants:            3684 
## Total number of putative Kataegis foci:      9 
## Total number of variants in a Kataegis foci: 133
show(kdVCF)
## Class 'KatDetect' : KatDetect Object
##                   : S4 class containing 4 slots with names:
##                     kataegisFoci genomicVariants segments info 
## 
## Created on:         Sun Sep 18 16:47:21 2022 
## katdetectr version: 0.99.13 
## 
## summary: 
## --------------------------------------------------------
## Sample name:                                 CPTAC 
## Total number of genomic variants:            3684 
## Total number of putative Kataegis foci:      9 
## Total number of variants in a Kataegis foci: 133
## --------------------------------------------------------
# Or simply:
kdVCF
## Class 'KatDetect' : KatDetect Object
##                   : S4 class containing 4 slots with names:
##                     kataegisFoci genomicVariants segments info 
## 
## Created on:         Sun Sep 18 16:47:21 2022 
## katdetectr version: 0.99.13 
## 
## summary: 
## --------------------------------------------------------
## Sample name:                                 CPTAC 
## Total number of genomic variants:            3684 
## Total number of putative Kataegis foci:      9 
## Total number of variants in a Kataegis foci: 133
## --------------------------------------------------------

Underlying data can be retrieved from a KatDetect objects using the following getter functions:

  1. getGenomicVariants() returns: VRanges object. Processed genomic variants used as input for changepoint detection. This VRanges contains the genomic location, IMD, and kataegis status of each genomic variant
  2. getSegments() returns: GRanges object. Contains the segments as derived from changepoint detection. This Granges contains the genomic location, total number of variants, mean IMD and, mutation rate of each segment.
  3. getKataegisFoci() returns: GRanges object. Contains all segments designated as putative kataegis foci according the the specified parameters (minSizeKataegis and maxMeanIMD). This Granges contains the genomic location, total number of variants and mean IMD of each putative kataegis foci
  4. getInfo() returns: List object. Contains supplementary information including used parameter settings.
getGenomicVariants(kdVCF)
## VRanges object with 3684 ranges and 4 metadata columns:
##          seqnames    ranges strand         ref              alt     totalDepth
##             <Rle> <IRanges>  <Rle> <character> <characterOrRle> <integerOrRle>
##      [1]     chr1    935222      *           C                A             50
##      [2]     chr1    949608      *           G                A             50
##      [3]     chr1    981131      *           A                G             50
##      [4]     chr1    982722      *           A                G             50
##      [5]     chr1   1164015      *           C                A             50
##      ...      ...       ...    ...         ...              ...            ...
##   [3680]     chrX 153594977      *           G                A             50
##   [3681]     chrX 153627839      *           C                T             50
##   [3682]     chrX 153629155      *           A                G             50
##   [3683]     chrX 153668757      *           G                A             50
##   [3684]     chrX 153764217      *           C                T             50
##                refDepth       altDepth   sampleNames softFilterMatrix |
##          <integerOrRle> <integerOrRle> <factorOrRle>         <matrix> |
##      [1]             20             30         CPTAC                  |
##      [2]             20             30         CPTAC                  |
##      [3]             20             30         CPTAC                  |
##      [4]             20             30         CPTAC                  |
##      [5]             20             30         CPTAC                  |
##      ...            ...            ...           ...              ... .
##   [3680]             20             30         CPTAC                  |
##   [3681]             20             30         CPTAC                  |
##   [3682]             20             30         CPTAC                  |
##   [3683]             20             30         CPTAC                  |
##   [3684]             20             30         CPTAC                  |
##                 revmap variantID       IMD putativeKataegis
##          <IntegerList> <integer> <integer>        <logical>
##      [1]             1         1    935222            FALSE
##      [2]             2         2     14386            FALSE
##      [3]             3         3     31523            FALSE
##      [4]             4         4      1591            FALSE
##      [5]             5         5    181293            FALSE
##      ...           ...       ...       ...              ...
##   [3680]          3683      3680       442            FALSE
##   [3681]          3684      3681     32862            FALSE
##   [3682]          3685      3682      1316            FALSE
##   [3683]          3686      3683     39602            FALSE
##   [3684]          3687      3684     95460            FALSE
##   -------
##   seqinfo: 23 sequences from an unspecified genome; no seqlengths
##   hardFilters: NULL
getSegments(kdVCF)
## GRanges object with 454 ranges and 7 metadata columns:
##         seqnames              ranges strand | sampleNames segmentID
##            <Rle>           <IRanges>  <Rle> | <character> <integer>
##     [1]     chr1           1-3389727      * |       CPTAC         1
##     [2]     chr1     3389728-3428608      * |       CPTAC         2
##     [3]     chr1    3428609-19199400      * |       CPTAC         3
##     [4]     chr1   19199401-19203725      * |       CPTAC         4
##     [5]     chr1   19203726-19635011      * |       CPTAC         5
##     ...      ...                 ...    ... .         ...       ...
##   [450]     chrX     3228145-3248104      * |       CPTAC         2
##   [451]     chrX   3248105-152721728      * |       CPTAC         3
##   [452]     chrX 152721729-153577918      * |       CPTAC         4
##   [453]     chrX 153577919-153594977      * |       CPTAC         5
##   [454]     chrX 153594978-153764217      * |       CPTAC         6
##         totalVariants firstVariantID lastVariantID    meanIMD mutationRate
##             <integer>      <integer>     <integer>  <numeric>    <numeric>
##     [1]            11              1            11  308157.00  3.24510e-06
##     [2]             4             12            15    9720.25  1.02878e-04
##     [3]            22             16            37  716854.18  1.39498e-06
##     [4]             4             38            41    1081.25  9.24855e-04
##     [5]             8             42            49   53910.75  1.85492e-05
##     ...           ...            ...           ...        ...          ...
##   [450]             3           3631          3633    6653.33  1.50301e-04
##   [451]            38           3634          3671 3933516.42  2.54225e-07
##   [452]             3           3672          3674  285396.67  3.50390e-06
##   [453]             6           3675          3680    2843.17  3.51720e-04
##   [454]             4           3681          3684   42310.00  2.36351e-05
##   -------
##   seqinfo: 23 sequences from an unspecified genome; no seqlengths
getKataegisFoci(kdVCF)
## GRanges object with 9 ranges and 6 metadata columns:
##       seqnames              ranges strand |    fociID sampleNames totalVariants
##          <Rle>           <IRanges>  <Rle> | <integer> <character>     <numeric>
##   [1]     chr3   58108856-58111467      * |         1       CPTAC             7
##   [2]     chr6   32489708-32489949      * |         2       CPTAC            13
##   [3]     chr6   32632598-32632770      * |         3       CPTAC             8
##   [4]     chr6 151669875-151674326      * |         4       CPTAC             7
##   [5]     chr8 144991205-144999107      * |         5       CPTAC            25
##   [6]    chr11   62285208-62298597      * |         6       CPTAC            25
##   [7]    chr14 105405599-105419557      * |         7       CPTAC            23
##   [8]    chr15   86122654-86124712      * |         8       CPTAC             6
##   [9]    chr19     4510560-4513559      * |         9       CPTAC            19
##       firstVariantID lastVariantID   meanIMD
##            <numeric>     <integer> <numeric>
##   [1]            782           788  435.1667
##   [2]           1251          1263   20.0833
##   [3]           1273          1280   24.5714
##   [4]           1358          1364  741.8333
##   [5]           1659          1683  329.2500
##   [6]           2112          2136  557.8750
##   [7]           2591          2613  634.4545
##   [8]           2687          2692  411.6000
##   [9]           3139          3157  166.6111
##   -------
##   seqinfo: 23 sequences from an unspecified genome; no seqlengths
getInfo(kdVCF)
## $sampleName
## [1] "CPTAC"
## 
## $totalGenomicVariants
## [1] 3684
## 
## $totalKataegisFoci
## [1] 9
## 
## $totalVariantsInKataegisFoci
## [1] 133
## 
## $version
## [1] "0.99.13"
## 
## $date
## [1] "Sun Sep 18 16:47:21 2022"
## 
## $parameters
## $parameters$minSizeKataegis
## [1] 6
## 
## $parameters$maxMeanIMD
## [1] 1000
## 
## $parameters$test.stat
## [1] "Exponential"
## 
## $parameters$penalty
## [1] "BIC"
## 
## $parameters$pen.value
## [1] 0
## 
## $parameters$minseglen
## [1] 2
## 
## $parameters$aggregateRecords
## [1] FALSE

5 Visualization of segmentation and kataegis foci

Per sample, we can visualize the IMD, detected segments and putative kataegis foci as a rainfall plot. In addition, this allows for a per-chromosome approach which can highlight the putative kataegis foci.

rainfallPlot(kdVCF)