\name{filter.probes}
\alias{filter.probes}
\title{ Filtering out probes }
\description{
	Filter out probes according to their Quality Flag
}
\usage{
filter.probes(ddNORM,control = NULL, wellaboveBG = NULL, isfound = NULL, wellaboveNEG = NULL, sat = NULL, PopnOL = NULL, NonUnifOL = NULL, nas = NULL, limWellAbove, limISF, limNEG, limSAT, limPopnOL, limNonUnifOL, limNAS, makePLOT, annotation.package, flag.counts = NULL, targets)
}
\arguments{
  \item{ddNORM}{An RGList in log2 scale to be FILTERED out according to a Quality FLAG }
  \item{control}{ LOGICAL: If True it removes controls }
  \item{wellaboveBG}{ LOGICAL: If True it filters by Well Above BG FLAG}
  \item{isfound}{ LOGICAL: If True it filters by Is Found FLAG}
  \item{wellaboveNEG}{ LOGICAL: If True it filters by Well Above NEG CTRLS}
  \item{sat}{ LOGICAL: If True it filters by Is Saturated FLAG}
  \item{PopnOL}{ LOGICAL: If True it filters by Population Outlier FLAG}
  \item{NonUnifOL}{ LOGICAL: If True it filters by Non Uniform Outlier FLAG}
  \item{nas}{ LOGICAL: If True it removes NAs}
  \item{limWellAbove}{for a given spot xi accros samples, is the 
		minimum % of probes of the spot xi  that is demanded to remain 
		in a experimental condition with a wellaboveBG-FLAG = 1 (Is Well Above BG)
		 }
  \item{limISF}{for a given feature xi accros samples, is the
                minimum % of spots for that feature that is demanded to remain
                in a experimental condition with a isfound-FLAG = 1 (Is Found)
  }
  \item{limNEG}{ for a given feature xi accros samples, is the
                minimum % of spots for that feature that is demanded to remain
                in a experimental condition with a intensity > Limit established
		for negative controls (Mean + 1.5 x SD) 
 }
  \item{limSAT}{for a given feature xi accros samples, is the
                minimum % of spots for that feature that is demanded to remain
                in a experimental condition with a saturation-FLAG = 0 (Non Saturated)
  }
  \item{limPopnOL}{for a given feature xi accros samples, is the
                minimum % of spots for that feature that can be seen 
                in a experimental condition with a saturation-FLAG = 1 (Is Pop OL)  }
  \item{limNonUnifOL}{ for a given feature xi accros samples, is the
                minimum % of spots for that feature that can be seen
                in a experimental condition with a saturation-FLAG = 1 (Is Non Uni OL) }
  \item{limNAS}{for a given feature xi accros samples, is the
                minimum % of NAs spots for that feature that is demanded to remain
                in a experimental condition 
  }
  \item{makePLOT}{LOGICAL: If True it makes QC graphs filtering  }
  \item{annotation.package}{  a character specifying the AGI annotation package: 'hgug4112a.db','mgug4122a.db' }
  \item{flag.counts}{LOGICAL: If True it runs the countFLAG function  }
  \item{targets}{ data.frame with the target structure }
}
\details{
	Agilent Feature Extraction software provides a flag for each spot 
	that identifies different quantification errors of the signal.
	Quantification flags were used to filter out signals that did not reach 
	a minimum established criterion of quality.
	Data were filtered at a probe level according to the following criteria.
	a- To keep features within the dynamic range of the scanner:
		For a spot = xi accross all the samples, we demand that at least p %  of the 
		probes of the spot xi in at least one experimental condition had a 
		quantification flag denoting that the signal is distinguishable from 
		background. The same criterion is applied independently for the 'IsFound'
		flag and for signal saturation. 
	b- To keep good quality features, we filtered out probes that had more than y % of the replicates 
        in at least one experimental condition flagged as Outliers.
}
\value{
	The function returns a RGList containing with the FILTERED data eliminated
	In order to allow the tracking of features that may have been filtered out from 
	the original raw data, the following files are given:   

	RawDataNOCtrl.txt: contains all the features included in the array once 
		the internal controls have been removed. Internal controls are removed 
		prior to any preprocessing step.

	IsNOTWellAboveBG.txt: contains the features that have been filtered out because 
		they are not distinguishable from the local background signal.

		We uses a Boolean flag indicating if a feature is WellAbove 
		Background (Flag = 1) or not (Flag = 0). A feature reaches a 
		Flag = 1 if IsPosAndSignif and additionally the gBGSubSignal 
		is greater than 2.6*g(r)BG\_SD.

		IsPosAndSignif uses a Boolean flag, established via a 2-sided t-test, 
		indicates whether the mean signal of a feature is greater than the 
		corresponding background. 1 indicates feature is positive and 
		significant above background

	IsNOTFound.txt: contains features that have been filtered out because 
		were NOT FOUND. A feature is considered Found if two conditions 
		are true: 1- the difference between the feature signal and the 
		local background signal is more than 1.5 times the local background 
		noise and 2- the spot diameter is at least 0.30 times the nominal 
		spot diameter. A Boolean variable is used to flag found features. 1 = IsFound

	IsSaturated.txt: contains the features that are saturated.  A feature is 
		saturated IF 50 % of its pixels are above the saturation 
		threshold. 1 = Saturated

	IsFeatNonUnifOL.txt: contains the features that are considered Non Uniformity
		 Outlier. A feature is non-uniform if the pixel noise of feature 
		exceeds a threshold established for a uniform feature. 1 indicates Feature 
		is a non-uniformity outlier.

	IsFeatPopnOL.txt: contains the features that are considered Population Outlier. 
		A feature is a population outlier if its signal intensity is lower than a lower 
		threshold or exceeds an upper threshold determined using a multiplier 
		(1.42) times the interquartile range of the population. 1 indicates 
		Feature is a population outlier

	IsNOTWellAboveNEG.txt: Besides, for each feature we can demand a minimum signal value 
		that have to be reached at least for a p % of the replicates of the features 
		in one of the experimental conditions. The minimum limit has been established as  
		Mean Negative Controls  + 1.5*(Std. dev.Negative Controls). 
		Normally, after filtering by WellAboveBG and IsFound criteria, 
		all probes are well above negative controls.

	In addition to all files indicated above we have added ACCNUM, GENE SYMBOL,
	ENTREZID reference and gene DESCRIPTION corresponding to each manufacturer probe code
	in the corresponding annotation package.
	
}
\author{ Pedro Lopez-Romero }
\examples{
\dontrun{
	 data(dd)
	 data(targets)
	 library(hgug4112a.db)
	 ddNORM=BGandNorm(dd,BGmethod='half',NORMmethod='quantile',
                        foreground='MeanSignal',background='BGMedianSignal',
                        offset=50,makePLOTpre=FALSE,makePLOTpost=FALSE)
	 ddFILT=filter.probes(ddNORM,
                control=TRUE,
                wellaboveBG=TRUE,
                isfound=TRUE,
                wellaboveNEG=TRUE,
                sat=TRUE,
                PopnOL=TRUE,
                NonUnifOL=TRUE,
                nas=TRUE,
                limWellAbove=75,
                limISF=75,
                limNEG=75,
                limSAT=75,
                limPopnOL=75,
                limNonUnifOL=75,
                limNAS=100,
                makePLOT=TRUE,annotation.package="hgug4112a.db",flag.counts=TRUE,targets)
}
}
\keyword{documentation}
\keyword{utilities}