R/normn_MA.R

In Rundmus/BAf-R_package: Binder Array data hanlding package in facility

# -----------------------------------------------------------------------------#
#' Multi-dimensional MA normalization for plate effect
#' 
#' Normalize data to minimize the difference among the subgroups of the samples 
#' generated by experimental factor such as multiple plates (batch effects)\cr
#'  - the primary method is Multi-MA, but other fitting function, \emph{f} in 
#'    the reference (e.g. loess) is available, too.\cr
#'  This method is based on the assumptions stated below\cr
#'  \enumerate{
#'  \item The geometric mean value of the samples in each subgroup (or plate) 
#'        for a single target is ideally same as those from the other subgroups.
#'  \item The subgroup (or plate) effects that influence those mean values for 
#'        multiple observed targets are dependent on the values themselves. 
#'        (intensity dependent effects)
#'  }\cr
#' This function calls the \code{normn_MA} of the package \code{MDimNormn}.
#' 
#' @param baf a \code{\link{BAf-class}} object
#' @param expGroupVar the column name in @sinfo which contains the experimental 
#'            factor to be used for grouping 
#' @param represent_FUN a \code{function} that computes representative values 
#'                      for each experimental group (e.g. plate). The default is
#'                      mean ignoring any NA 
#' @param fitting_FUN \code{NULL} or a \code{function} that fits to data in 
#'                    MA-coordinates.\cr 
#'        If it is \code{NULL} as the default, 'Multi-MA' method is employed.\cr
#'        If a \code{function} is used, two arguments of \code{m_j} and \code{A}
#'        are required, which are \eqn{\mathbf{m}_j}{m_j} coordinate in 
#'        \eqn{M_d} and \eqn{A} coordinate, respectively. 
#' @param isLog TRUE or FALSE, if the normalization should be conducted after 
#'              log-transformation. The affinity proteomics data from suspension
#'              bead arrays is recommended to be normalized using the default,
#'              \code{isLog = TRUE}.
#' 
#' @return The \code{\link{BAf-class}} object with normalized values
#' 
#' @references Hong M-G, Lee W, Nilsson P, Pawitan Y, & Schwenk JM (2016) 
#' 	Multidimensional normalization to minimize plate effects of suspension 
#'  bead array data. \emph{J. Proteome Res.}, 15(10) pp 3473-80.
#' 
#' @author Mun-Gwan Hong \email{mun-gwan.hong@scilifelab.se}
#' @examples
#' data(sba)
#' B <- sba[sba@sinfo$cohort != "EMPTY", ]
#' C <- normn_MA(B)		# normalize excluding "EMPTY"
#' 
#' i_rnd <- sample(1:ncol(C), 1)
#' sd(log(sX(B)[, i_rnd]))
#' sd(log(sX(C)[, i_rnd]))         # reduced variation
#' 
#' # MA-loess normalization
#' C1 <- normn_MA(B, fitting_FUN= function(m_j, A) loess(m_j ~ A)$fitted)
#' 
#' # On MA coordinates, weighted linear regression normalization
#' C2 <- normn_MA(B, fitting_FUN= function(m_j, A) {
#' 	beta <- lm(m_j ~ A, weights= 1/A)$coefficients
#' 	beta[1] + beta[2] * A
#' })
#' 
#' # On MA coordinates, robust linear regression normalization
#' if(any(search() == "package:MASS")) {	# excutable only when MASS package was loaded.
#'   C3 <- normn_MA(B, fitting_FUN= function(m_j, A) {
#' 		 beta <- rlm(m_j ~ A, maxit= 100)$coefficients
#' 		 beta[1] + beta[2] * A
#' 	 })
#' }
#' 
#' @importFrom MDimNormn normn_MA
#' @export
# -----------------------------------------------------------------------------#

normn_MA <- function(baf, expGroupVar= batch_colname(baf, "sample"), 
                     represent_FUN= function(x) mean(x, na.rm= T), 
                     fitting_FUN= NULL, isLog= TRUE) {
    stopifnot(inherits(baf, "BAf"),
              expGroupVar %in% colnames(baf@sinfo)) 

    baf@.Data <- MDimNormn::normn_MA(mD= baf@.Data, 
                                     expGroup= baf@sinfo[[expGroupVar]], 
                                     represent_FUN= represent_FUN, 
                                     fitting_FUN= fitting_FUN, 
                                     isLog= isLog)
    return(baf)
}