\name{ShortRead-methods}
\docType{methods}
\alias{barcodePlot}
\alias{barcodePlot,AlignedRead-method}
\alias{barcodePlot,DNAStringSet-method}
\alias{barcodePlot,ShortReadQ-method}
\alias{chastityFilter}
\alias{chastityFilter,SRFilter-method}
\alias{naPositionFilter}
\alias{naPositionFilter,SRFilter-method}
\alias{demultiplex}
\alias{demultiplex,AlignedRead-method}
\alias{demultiplex,DNAStringSet-method}
\alias{demultiplex,ShortReadQ-method}

\title{ Methods extending the ShortRead package functionalities}

\description{
These are functions extending the ShortRead packages capabilities:

      \itemize{
	\item{\code{barcodePlot}} Creates a plot showing the barcode distribution of a multiplexed sequencing library.
 	\item{\code{chastityFilter}} Creates a \code{\linkS4class{SRFilter}} instance that filters SolexaExport read according to the chastity filtering value. 
	\item{\code{demultiplex}} Split a single \code{\linkS4class{AlignedRead}} object into a list of \code{\linkS4class{AlignedRead}} objects according to the barcodes provided by the user.
 	\item{\code{naPositionFilter}} Creates a \code{\linkS4class{SRFilter}} instance that filters SolexaExport read having an NA position.
	}

}

\usage{
barcodePlot(obj,barcodes=c(),type=c("independant","within"),barcode.length=6,show.barcode=20,...)
chastityFilter(.name="Illumina Chastity Filter")
demultiplex(obj,barcodes=c(),barcodes.qty=12,
		barcode.length=6, edition.dist=2,
		type = c("independant","within"), 
		index.only = FALSE)
naPositionFilter(.name="NA Position Filter")
}

\arguments{
 \item{.name}{An internal string describing the filter}
 \item{obj}{An object derived from class \code{\linkS4class{AlignedRead}}}
 \item{barcodes}{A character vector describing the multiplex (i.e. barcode) sequences used in the experiment.}
 \item{barcodes.qty}{An integer describing the number of barcodes}
 \item{barcode.length}{An integer describing the barcode length in bp}
 \item{edition.dist}{The maximal edition distance (i.e. the number of changes to apply), to accept an incorrectly sequenced barcode.}
 \item{index.only}{simply return the index and not the barcode themselves.}
 \item{show.barcode}{An integer specifying how many barcodes should be displayed in the final output.}
 \item{type}{The type of barcode used. \code{independent} represents barcodes generated by the illumina protocol; i.e. a separate additional sequencing step performed once the first mate has been sequenced. \code{within} represents barcodes that are part of the sequenced reads as established by Lefrancois P et al., BMC Genomics, 2009}
 \item{\dots}{additional graphic parameters}
}

\details{
	When demultiplexing, the function if provided with just the \code{\linkS4class{AlignedRead}} will try to
	find out how many barcodes were used and what they are. This is unwise to do as many barcodes will get wrongly sequenced and not always the most frequent ones are the one you used! It's therefore strongly advised to specify the barcodes' sequences that were used.
}

\value{
	\itemize{
	\item{\code{barcodePlot}} returns invisibly the barcode frequencies.
 	\item{\code{chastityFilter}} returns a \code{\linkS4class{SRFilter}} instance. 
	\item{\code{demultiplex}} returns a list of \code{\linkS4class{AlignedRead}} objects.
 	\item{\code{naPositionFilter}} returns a \code{\linkS4class{SRFilter}} instance. 
	}
}

\author{
	Nicolas Delhomme
}

\seealso{
	\code{\linkS4class{SRFilter}}
	\code{\linkS4class{AlignedRead}}
}
\examples{
	\dontrun{
	## the barcode
	barcodes=c("ACACTG","ACTAGC","ATGGCT","TTGCGA")

	## the multiplexed data
	alns <- readAligned(
                    system.file(
                                "extdata",
                                package="RnaSeqTutorial"),
                    pattern="multiplex_export",
                    filter=compose(
                      chastityFilter(),
                      nFilter(2),
                      chromosomeFilter(regex="chr")),
                    type="SolexaExport",
                    withAll=TRUE)
	
	## barcode plot
	barcodePlot(alns,
            barcodes=barcodes,
            type="within",
            barcode.length=6,
            show.barcode=20,
            main="All samples",
            xlim=c(0,0.5))

	## demultiplexing
	dem.alns <- demultiplex(alns,
                        barcodes=barcodes,
                        edition.dist=2,
                        barcodes.qty=4,
                        type="within")
	
	## plotting again
	par(mfrow=c(2,2))
	barcode.frequencies <- lapply(
                              names(dem.alns$barcodes),
                              function(barcode,alns){                                
                                barcodePlot(
                                            alns$barcodes[[barcode]],
                                            barcodes=barcode,
                                            type="within",barcode.length=6,
                                            show.barcode=20,
                                            main=paste(
                                              "Expected barcode:",
                                              barcode))
                              },dem.alns)
	}
}

\keyword{methods}