R/correctEdgeEffect.R

In lujunyan1118/DrugScreenExplorer_dev: A pipeline for processing drug sensitivity screen data

#' Estimate and correct edge effect for each screen plate
#'
#' This function subtract the incubation (or edge) effect from the observed signal intensity to recover the true signal intensity.
#' If the incubation effect has already been estimated by \code{fitEdgeEffect()} function, the values in the edgeFactor column will be used.
#' Otherwise, this function will first call \code{fitEdgeEffect()} function to estimate the edge effect.
#'
#'
#' @param screenData a data frame containing screening results generated by \code{readScreen()} function. In order for the edge effect estimate algorithm to work,
#' plate normalization needs to be performed first.
#' @param estimateMethod a character string specifying the method used for estimating the shape and strength of edge effect.
#' Currently two methods are supported: 'loess', which uses a local regression model to estimate edge effect;
#' 'sigmoid', an experimental feature, which uses use a 2D-sigmoid model to estimate edge effect.
#' The "loess" method is suitable for both regular incubation effect, such as edge effect, and irregular incubation effect. But sometimes it tends to over-smooth the edge effect
#' when the edge effect is rectangular. In this case, "sigmoid" method can better capture the shape of edge effect. But the "sigmoid" method can not deal with incubation effect with irregular shape.
#' @param useNeg a logical value. If TRUE, only negative controls are used to estimate edge effect. Otherwise, all the wells are used for edge effect estimation.
#' @param useLowConcentrations a integer value. In addition to negative controls,
#' sample wells with low concentrations of compounds can be considered as 'de facto' negative controls and included in edge effect estimation.
#' The default value is 0, means no sample wells are used. If the value n >= 1, the n lowest concentrations will be used.
#' @param span a numeric value. The span parameter for \code{loess} method, which controls the degree of smoothing.
#' @param correctMethod a character string specifying the method used for subtracting the edge effect. Currently two methods 'bliss' and 'linear' are supported.
#' If \code{bliss} is selected, the corrected values are simply the normalized signal intensity values divided by the estimated incubation/edge effect intensity.
#' If \code{linear} is selected, the correction process will be smoothed by a linear function depends on the original normalized signal intensity. This option is
#' suitable for the situation when the edge effect is very strong and results in instability in the correction process.
#' @param exclude a list of samples that should be excluded when performing edge effect correction
#' @export
#' @import dplyr
#' @return This function will add one column, \code{normVal.cor}, which is the normalized viability corrected for incubation/edge effect, to the input data frame.
#' @examples
#' # load drug screen dataset
#' data('screenData_normalized')
#' screenData_corrected <- correctEdgeEffect(screenData_normalized, estimateMethod = 'loess',
#'     useNeg = TRUE, useLowConcentrations = 0, span =1, correctMethod = 'bliss')

correctEdgeEffect <- function(screenData, estimateMethod = "loess", useNeg = TRUE, useLowConcentrations = 0, span = 1,
                              correctMethod = "bliss", exclude = c()) {

  if ("sampleID" %in% colnames(screenData)) {
    exclude <- c(exclude, dplyr::filter(screenData, sampleID %in% exclude)$fileName)
  }

  if (!"edgeFactor" %in% colnames(screenData)) {
    # edge effect estimation hasn't been performed. Estiamte the edge effect first
    screenData <- fitEdgeEffect(screenData, method = estimateMethod,
                                useNeg = useNeg, useLowConcentrations = useLowConcentrations,
                                span = span, exclude = exclude)
  }

  if (correctMethod == "bliss") {
    screenData <- dplyr::mutate(screenData, normVal.cor = normVal/edgeFactor)

  } else if (correctMethod == "linear") {
    screenData <- dplyr::mutate(screenData, normVal.cor = corEdgeLinear(normVal, edgeFactor))

  } else stop("Not a valid choice for edge effect correction method")

  return(screenData)
}