\name{dyebias.apply.correction} \alias{dyebias.apply.correction} \title{Perform dye bias correction using the GASSCO method} \description{Corrects the gene- and slide specific dye bias in a data set, using the GASSCO method by Margaritis et al. } \synopsis{dyebias.apply.correction(data.norm, iGSDBs, estimator.subset=TRUE, application.subset=TRUE, dyebias.percentile=5, minmaxA.perc=25, minA.abs=NULL, maxA.abs=NULL, verbose=FALSE) } \arguments{ \item{data.norm}{ A \code{marrayNorm} object containing the data whose dye bias should be corrected. This object must be a complete \code{marrayNorm} object. In particular, \code{maLabels(maGnames(data.norm))} should be set and indicate the identities of the spots. Spots with the same ID should contain the same oligo or cDNA sequence, and will receive the same dye bias correction. } \item{iGSDBs}{ A data frame with the intrinsic gene specific dye bias per reporter (i.e., oligo or cDNA). The data frame would typically have come from a call to \code{\link{dyebias.estimate.iGSDBs}}, but this is not necessary; other estimates can also be used. The data frame must have (at least) the following columns: \itemize{ \item{reporterId}{The name of the reporter. This must match the IDs in %% cannot use \cr for some reason here; hence the new paragraph. \code{maLabels(maGnames(data.norm))} } \item{dyebias}{ An estimate of the dye bias } \item{A}{ The average expression value \eqn{A} of this reporter. (\eqn{A = (log_2(R)+log_2(G))/2 = (log_2(Cy5)+log_2(Cy3))/2 }). The \eqn{A}-value is used to base exclusions on. If you don't have it, you can use any value (but realize that the \code{minmaxA.perc, minA.abs, maxA.abs} arguments are still applied). } } % itemize The order of the rows in this data frame is irrelevant. There must be no rows with duplicate \code{reporterId} in this frame. For any reporter in \code{data.norm} that is not in the \code{iGSDBs} data frame, an iSGDB of 0.00 is used, i.e. data from such reporters is not dye bias-corrected. } \item{estimator.subset}{ An index indicating which reporters are fit to be used as estimators of the slide bias. This set of reporters is used throughout the whole data set. Reporters that are typically excluded are those corresponding to parasitic DNA elements or mitochondrial genes. } \item{application.subset}{ An index indicating which values must be dye bias-corrected. It should be either a vector with as many values as spots, or a matrix of the same dimensions as \code{maM(data.norm)}. In former case, the selected spots on all slides with be dye bias-corrected; in the latter, selected spots on selected slides will corrected. Often it is prudent not to dye bias-correct measurements that are close to the detection limit or close to signal saturation. A convenience function for this is provided; see \cr \code{\link{dyebias.application.subset}}. } \item{dyebias.percentile}{ The slide bias estimation uses a small subset of reporters having the strongest green or red iGSDB, as specified by this percentile. The default should suffice in practically all cases. } \item{minmaxA.perc}{ To obtain a robust estimate of the slide bias, the range of the average expression \eqn{A} is trimmed by \code{minmaxA.perc} percent on both sides; only reporters lying inside this trimmed range are considered as estimators of the slide bias. The default value is 25, meaning that only probes with an average expression within the interquartile range are considered as estimator genes (from these, the top \code{dyebias.percentile} red- and green-biased are then actually used). The default value should suffice in practically all cases. } \item{minA.abs}{ If specified, reporters with an average expression (\eqn{A}) lower than this value are never considered as estimators of the slide bias. If not specified, reporters with an \eqn{A}-percentile < \code{minmaxA.perc} are not considered. } \item{maxA.abs}{ If specified, reporters with an average expression (\eqn{A}) greater than this are never considered as estimators of the slide bias. If not specified, reporters with an \eqn{A}-percentile < \code{100-minmaxA.perc} are not considered.} \item{verbose}{ Logical speficying whether to be verbose or not } } \value{ The data returned is a list wit the following elements \item{data.corrected}{A \code{marrayNorm} object of the same 'shape' as the input \code{data.norm}, but with corrected \eqn{M} values. } \item{estimators}{Another list, containing the details of the reporters that were used to obtain an estimate of the slide bias. The contents of the \code{estimators} list are: \itemize{ \item{green.ids}{The IDs of the reporters having the strongest green effect.} \item{green.cutoff}{All reporters in green.ids have an iGSDB below this value.} \item{green.subset}{An index into the reporters having the strongest green effect.} \item{green.iGSDBs}{The corresponding iGSDBs} \item{red.ids}{The IDs of the reporters having the strongest red effect.} \item{red.cutoff}{All reporters in green.ids have an iGSDB above this value.} \item{red.subset}{An index into the reporters having the strongest red effect.} \item{red.iGSDBs}{The corresponding iGSDBs} } } \item{summary}{ A data frame summarizing the correction process per slide. It consist of the following columns: \itemize{ \item{slide}{The slide number} \item{file}{Which file it came from} \item{green.correction}{The slide bias based on only the green bias of this slide} \item{red.correction}{The slide bias based on only the red bias of this slide} \item{avg.correction}{The total correction factor of this slide. This is in fact the slide bias} \item{var.ratio}{The ratio of the variance of \eqn{M} after and before the correction. The smaller this number, the smaller the variance of \eqn{M} around the mean has become, providing a measure of the success of the dye bias correction. Only data points that were in the \code{application.subset} are considered.} \item{reduction.perc}{As \code{var.ratio}, but expressed as a percentage. The larger this value, the greater the correction.} \item{p.value}{The p-value for the signficance of the reduction in variance (\eqn{F}-test; \eqn{H_0}: variances before and after correction are identical)} } } \item{data.uncorrected}{The uncorrected input \code{marrayNorm}, for convenience} } \details{ This function corrects the gene-specific dye bias of two-colour microarrays with the GASSCO method. This method is general, robust and fast, and is based on the observation that the total bias per gene is the product of a slide-specific factor (strongly related to the labeling percentage) and an intrinsic gene-specific factor (iGSDB), which is strongly related to the probe sequence. The slide bias is estimated from the total bias of the \code{dyebias.percentile} percentage of reporters having the strongest iGSDB. The iGSDBs can be estimated with \cr \code{\link{dyebias.estimate.iGSDBs}}. If the signal of certain oligos is too weak, or in contrast, tends to be saturated, they are no good estimator of the slide bias. Therefore, only reporters with an average expression level \eqn{A} that is not too extreme are allowed to be slide bias estimators. (This is the reason for the \code{A}-column in the \code{iGSDBs} data frame). Full control over which reporters to allow as slide bias estimators is given by the arguments \code{minmaxA.perc}, \code{minA.abs}, and \code{maxA.abs}; see there for details. To not exclude any reporter (e.g., when \eqn{A} is not available and therefore artificially set), you can use \code{minA.abs= -Inf} and \code{maxA.abs = Inf}. For further details concerning the method, see the \code{dyebias} vignette and the publication. If your research benefits from using this package, we kindly request that you cite this work. } \author{Philip Lijnzaad \email{p.lijnzaad@umcutrecht.nl} } \note{ Note that the input data should be normalized, and that the dye swaps should \strong{not} have been swapped back (if needed, this can of course be done afterwards). } \seealso{ \code{\link{dyebias.estimate.iGSDBs}}, \code{\link{dyebias.application.subset}}, \code{\link{dyebias.rgplot}}, \code{\link{dyebias.maplot}}, \code{\link{dyebias.boxplot}}, \code{\link{dyebias.trendplot}} } \examples{ ## First load data and estimate the iGSDBs ## (see dyebias.estimate.iGSDBs) \dontshow{ options(stringsAsFactors = FALSE) library(dyebias) library(dyebiasexamples) data(data.raw) data(data.norm) ### obtain estimate for the iGSDBs: iGSDBs.estimated <- dyebias.estimate.iGSDBs(data.norm, is.balanced=TRUE, verbose=FALSE) } % dontshow ### choose the estimators and which spots to correct: estimator.subset <- dyebias.umcu.proper.estimators(maInfo(maGnames(data.norm))) ### choose which genes to dye bias correct: application.subset <- (maW(data.norm) == 1 & dyebias.application.subset(data.raw=data.raw, use.background=TRUE)) ### do the correction: correction <- dyebias.apply.correction(data.norm=data.norm, iGSDBs = iGSDBs.estimated, estimator.subset=estimator.subset, application.subset = application.subset, verbose=FALSE) \dontrun{ edit(correction$summary) } ## give overview: correction$summary[,c("slide", "file", "avg.correction", "reduction.perc", "p.value")] ## and summary: summary(as.numeric(correction$summary[, "reduction.perc"])) } \references{ Margaritis, T., Lijnzaad, P., van Leenen, D., Bouwmeester, D., Kemmeren, P., van Hooff, S.R and Holstege, F.C.P. (2009). Adaptable gene-specific dye bias correction for two-channel DNA microarrays. \emph{Molecular Systems Biology}, 5:266, 2009. doi: 10.1038/msb.2009.21. } % Add one or more standard keywords, see file 'KEYWORDS' in the % R documentation directory. \keyword{misc} % silly, but one keyword is compulsary