beadarray (version 2.22.2)

BASH: BASH - BeadArray Subversion of Harshlight

Description

BASH is an automatic detector of physical defects on an array. It is designed to detect three types of defect - COMPACT, DIFFUSE and EXTENDED.

Usage

BASH(BLData, array, neighbours=NULL, transFun = logGreenChannelTransform, outlierFun = illuminaOutlierMethod, compn=3, wtsname=NULL, compact = TRUE,  diffuse = TRUE, extended = TRUE, cinvasions = 10, dinvasions = 15,  einvasions = 20, bgcorr = "median", maxiter = 10, compcutoff = 8,  compdiscard = TRUE, diffcutoff = 10, diffsig = 0.0001, diffn = 3,  difftwotail = FALSE, useLocs = TRUE, ...)

Arguments

BLData

BeadLevelList

array

integer specifying which section/array to plot.

neighbours

the user may specify the neighbours matrix, rather than have BASH calculate it. Time can be saved if using BASH and HULK, by calculating the neighbours matrix once and passing it to the two functions.

transFun

function to use to transform data prior to running BASH

outlierFun

the choice of outlier calling function to use.

compn

Numerical - when finding outliers in the compact analysis, how many MADs away from the median (for example) an intensity must be for it to be labelled an outlier.

wtsname

name under which bead weights are stored in the BLData object. It is only necessary to specify this if a) weights have already been set, and b) you wish BASH to observe them.

compact

Logical - Perform compact analysis?

diffuse

Logical - Perform diffuse analysis?

extended

Logical - Perform extended analysis?

cinvasions

Integer - number of invasions used whenever closing the image - see BASHCompact

dinvasions

Integer - number of invasions used in diffuse analysis, to find the kernel - see BASHDiffuse

einvasions

Integer - number of invasions used when filtering the error image - see BGFilter.

bgcorr

One of "none", "median", "medianMAD" - Used in diffuse analysis, this determines how we attempt to compensate for the background varying across an array. For example, on a SAM array this should be left at "median", or maybe even switched to "none", but if analysing a large beadchip then you might consider setting this to "medianMAD". (this code is passed to the method argument of BGFilter). Note that "none" may be the correct setting if HULK has already been applied.

maxiter

Integer - Used in compact analysis - the max number of iterations allowed. (Exceeding this results in a warning.)

compcutoff

Integer - the threshold used to determine whether a group of outliers is in a compact defect. In other words, if a group of at least this many connected outliers is found, then it is labelled as a compact defect.

compdiscard

Logical - should we discard compact defect beads before doing the diffuse analyis?

diffcutoff

Integer - this is the threshold used to determine the minimum size that clusters of diffuse defects must be.

diffsig

Probability - The significance level of the binomial test performed in the diffuse analysis.

diffn

Numerical - when finding outliers on the diffuse error image, how many MADs away from the median an intensity must be for it to be labelled an outlier.

difftwotail

Logical - If TRUE, then in the diffuse analysis, we consider the high outlier and low outlier images seperately.

useLocs

Logical - If TRUE then a .locs file corresponding to the array is sought and, if found, used to identify the neighbouring beads. If FALSE the neighbours are infered algorithmically. See generateNeighbours for more details.

...

Logical - Perform compact analysis?

Value

The output is a list with four attributes:wts: A vector of weights for the matrix.ext: A vector of extended scores (null if the extended analysis was disabled).QC: A summary of the extended score and the number of beads masked.call: The function you used to call BASH.

Details

The BASH pipeline function performs three types of defect analysis on an image.

The first, COMPACT DEFECTS, finds large clusters of outliers, as per BASHCompact. The outliers are found using findAllOutliers(). We then find which outliers are clustered together. This process is iterative - having found a compact defect, we remove it, and then see if any more defects are found.

The second, DIFFUSE DEFECTS, finds areas which are densely populated with outliers (which are not necessarily connected), as per BASHDiffuse. To make this type of defect more obvious, we first generate an ERROR IMAGE, and then find outliers based on this image. (The error image is calculated by using method = "median" and bgfilter = "medianMAD" in generateE, unless ebgcorr = FALSE in which case we use bgfilter = "median".) Now we consider a neighbourhood around each bead and count the number of outlier beads in this region. Using a binomial test we determine whether this is more that we would expect if the outliers were evenly spread over the entire array. If so, we mark it as a diffuse defect. (A clustering algorithm similar to the compact defect analysis is run to reduce false positives.)

After each of these two analyses, we "close" the image, filling in gaps.

The third, EXTENDED DEFECTS, returns a score estimating how much the background is changing across an array, as per BASHExtended. To estimate the background intensity, we generate an error image using the median filter (i.e. generateE with method = "median" and bgfilter = "median"). We divide the variance of this by the variance of an error image without using the median filter, to obtain our extended score.

It should be noted that to avoid repeated computation of distance, a "neighbours" matrix is used in the analysis. This matrix describes which beads are close to other beads. If a large number of beads are missing (for example, if beads with ProbeID = 0 were discarded) then this algorithm may be affected.

For more detailed descriptions of the algorithms, read the help files of the respective functions listed in "see also".

BASH is currently quite a slow, memory-intensive function. It will only run on a single array at a time, and for analysis of multiple arrays, we recommend parallelising the command. An example is shown using the base parallel package.

References

J. M. Cairns, M. J. Dunning, M. E. Ritchie, R. Russell, and A. G. Lynch (2008). BASH: a tool for managing BeadArray spatial artefacts. Bioinformatics 15; 24(24)

See Also

BASHCompact, BASHDiffuse, BASHExtended, generateNeighbours, HULK

Examples

## Not run: 
# 
# if(require(beadarrayExampleData)){
# 
# 	data(exampleBLData)
# 	output <- BASH(exampleBLData,array=1,useLocs=FALSE)
#         exampleBLData <- setWeights(exampleBLData, output$wts, array=1) #apply BASH weights to exampleBLData
# 	
# 	###BASH only accepts one array at a time, but it can be made to run in a parallel fashion
# 	library(parallel)
# 
# 	output <- mclapply(c(1,2), function(x) BASH(exampleBLData, array=x, useLocs=FALSE))
# 
# 	for(i in 1:2){
# 	  exampleBLData <- setWeights(exampleBLData, output[[i]]$wts, array=i) 
# 	}
#       
# 
# 	#diffuse test is stricter
# 	output <- BASH(exampleBLData, diffsig = 0.00001,array=1, useLocs=FALSE)
# 
# 	#more outliers on the error image are used in the diffuse analysis
# 	output <- BASH(exampleBLData, diffn = 2,array=1, useLocs=FALSE)
# 
# 	#only perform compact & diffuse analyses (we will only get weights)
# 	output <- BASH(exampleBLData, extended = FALSE,array=1, useLocs=FALSE)
# 
# 	#attempt to correct for background.
# 	output <- BASH(exampleBLData, bgcorr = "median",array=1, useLocs=FALSE)
# }
# 
# else{
#   
#   stop("You will need the beadarrayExampleData package to run this example")
# }
# 
# 
# 
# ## End(Not run)