Attempt in a resolution for #40.

DESCRIPTION

@@ -69,4 +69,4 @@ biocViews: CopyNumberVariation, Software, Sequencing,
     VariantAnnotation, VariantDetection, Coverage, ImmunoOncology
 NeedsCompilation: no
 ByteCompile: yes
-RoxygenNote: 7.2.3.9000
+RoxygenNote: 7.3.1

NAMESPACE

@@ -1,5 +1,6 @@
 # Generated by roxygen2: do not edit by hand
 
+export(adjustLogRatio)
 export(annotateTargets)
 export(bootstrapResults)
 export(calculateBamCoverageByInterval)

NEWS

@@ -1,6 +1,12 @@
 Changes in version 2.10.0
 -------------------------
 
+NEW FEATURES
+    o adjustLogRatio function for adjusting a tumor vs normal coverage
+      ratio for purity and ploidy. Useful for downstream tools that
+      expect ratios instead of absolute copy numbers such as GISTIC.
+      Thanks @tedtoal (#40).
+
 SIGNIFICANT USER-VISIBLE CHANGES
 
     o Provide interval-level likelihood scores in runAbsoluteCN return

R/adjustLogRatio.R

@@ -0,0 +1,40 @@
+#' Adjust tumor vs. normal coverage log ratio for tumor purity and ploidy
+#' 
+#' This function can be used to adjust the log ratio for tumor purity and
+#' ploidy for downstream tools that expect a log2 ratio (for example GISTIC).
+#' 
+#' 
+#' @param ratio Vector of log2 tumor vs normal coverage ratios. 
+#' @param purity Purity of sample.
+#' @param ploidy Ploidy of sample.
+#' @param is.log2 \code{log.ratio} is \code{log2} transformed. 
+#' @param min.ratio Minimum (non-log2-transformed) ratio. Set to approx -8
+#' \code{log2} adjusted.
+#' @return \code{numeric(length(log.ratio))}, \code{log.ratio} adjusted 
+#' for \code{purity} and \code{ploidy} 
+#' @author Markus Riester
+#' @references
+#   * Zack et al. (2012), Pan-cancer patterns of somatic copy number alteration 
+#'    Nature Biotechnology.
+#'  * Toal (2018), https://github.com/lima1/PureCN/issues/40
+#' 
+#' @examples
+#' 
+#' normal.coverage.file <- system.file("extdata", "example_normal.txt.gz", 
+#'     package = "PureCN")
+#' tumor.coverage.file <- system.file("extdata", "example_tumor.txt.gz", 
+#'     package = "PureCN")
+#' normal <- readCoverageFile(normal.coverage.file)
+#' tumor <- readCoverageFile(tumor.coverage.file)
+#' log.ratio <- calculateLogRatio(normal, tumor)
+#' log.ratio.adjusted <- adjustLogRatio(log.ratio, 0.65, 1.73)
+#' 
+#' @export adjustLogRatio
+adjustLogRatio <- function(ratio, purity, ploidy, is.log2 = TRUE, min.ratio = 0.004) {
+    if (is.log2) ratio <- 2^ratio
+    adjusted <- (purity * ploidy * ratio + 2 * (1 - purity) * ratio - 2 * (1 - purity)) / (purity * ploidy)
+    adjusted <- pmax(min.ratio, adjusted)
+    if (is.log2) adjusted <- log2(adjusted)
+    return(adjusted)
+}
+

tests/testthat/test_adjustLogRatio.R

@@ -0,0 +1,15 @@
+context("adjustLogRatio")
+
+test_that("Function returns expected values for example coverage", {
+     data(purecn.example.output)
+     log.ratio <- purecn.example.output$results[[1]]$seg$seg.mean   
+     purity <- purecn.example.output$results[[1]]$purity
+     ploidy <- purecn.example.output$results[[1]]$ploidy
+     log.ratio.adjusted <- adjustLogRatio(log.ratio, purity, ploidy)
+     total.ploidy <- 1.73
+     p <- 1
+     opt.C <- (2^(log.ratio.adjusted + log.ratio.offset) *  total.ploidy)/p - ((2 * (1 - p))/p)
+     expect_lt(abs(min(log.ratio.adjusted, na.rm=TRUE) - log2(0.004)), 0.001)
+     expect_lt(median(abs(opt.C - purecn.example.output$results[[1]]$seg$C)), 0.1)  
+})
+