\name{readBamGappedAlignments}
\Rdversion{1.1}

\alias{readBamGappedAlignments}
\alias{readBamGappedAlignments,character-method}
\alias{readBamGappedReads}
\alias{readBamGappedReads,character-method}

\title{Reading GappedAlignments or GappedReads objects from a BAM file}

\description{
Read a BAM file as a \link[GenomicRanges]{GappedAlignments}
or \link[ShortRead]{GappedReads} object.
}

\usage{
readBamGappedAlignments(file, index=file, use.names=FALSE, param=NULL)
readBamGappedReads(file, index=file, use.names=FALSE, param=NULL)
}

\arguments{

  \item{file}{The character(1) file name of the `BAM' file to be processed.}
  
  \item{index}{The character(1) name of the index file of the 'BAM' file
    being processed; this is given \emph{without} the '.bai' extension.}

  \item{use.names}{Use the query template names (QNAME field) as the
    names of the returned object? If not (the default), then the returned
    object has no names.}

  \item{param}{\code{NULL} or an instance of \code{\linkS4class{ScanBamParam}}.
    Like for \code{\link{scanBam}}, this influences what fields and which
    records are imported. However, please note that the fields specified
    thru this \code{\linkS4class{ScanBamParam}} object will be loaded
    \emph{in addition} to any field required for generating the returned
    object (\link[GenomicRanges]{GappedAlignments} or
    \link[ShortRead]{GappedReads} object) and will be stored in its
    elementMetadata part.
    By default (i.e. \code{param=NULL}), no additional field is loaded and
    the flag used is \code{scanBamFlag(isUnmappedQuery=FALSE,
    isDuplicate=FALSE)} (i.e. all the records corresponding to mapped reads
    that are not PCR or optical duplicates are loaded).}
}

\details{
  
  See \code{?\link[GenomicRanges]{GappedAlignments-class}} for a
  description of \link[GenomicRanges]{GappedAlignments} objects.

  See \code{?\link[ShortRead]{GappedReads-class}} for a
  description of \link[ShortRead]{GappedReads} objects.

  See \code{?\link{scanBam}} for a description of the arguments.

}

\value{
  A \link[GenomicRanges]{GappedAlignments} object for
  \code{readBamGappedAlignments}.

  A \link[ShortRead]{GappedReads} object for \code{readBamGappedReads}.
}

\note{
  BAM records corresponding to unmapped reads or to reads that are PCR
  or optical duplicates are always ignored.
}

\author{H. Pages}

\seealso{
  \link[GenomicRanges]{GappedAlignments-class},
  \link[ShortRead]{GappedReads-class},
  \code{\link{scanBam}},
  \code{\link{ScanBamParam}}
}

\examples{
## Simple use:
bamfile <- system.file("extdata", "ex1.bam", package="Rsamtools")
galn1 <- readBamGappedAlignments(bamfile)
galn1
names(galn1)

## Using the 'use.names' arg:
galn2 <- readBamGappedAlignments(bamfile, use.names=TRUE)
galn2
head(names(galn2))

## Using the 'param' arg to load additional BAM fields:
param <- ScanBamParam(what=c("qual", "flag"))
galn3 <- readBamGappedAlignments(bamfile, param=param)
galn3
elementMetadata(galn3)

## Using the 'param' arg to load reads from particular regions.
## Note that if we weren't providing a 'what' argument here, all the
## BAM fields would be loaded:
which <- RangesList(seq1=IRanges(1000, 2000),
                    seq2=IRanges(c(100, 1000), c(1000, 2000)))
param <- ScanBamParam(which=which)
galn4 <- readBamGappedAlignments(bamfile, param=param)
galn4

## Note that a given record is loaded one time for each region it
## belongs to (this is a scanBam() feature, readBamGappedAlignments()
## is based on scanBam()):
which <- IRangesList(seq2=IRanges(c(1563, 1567), width=1))
param <- ScanBamParam(which=which)
galn5 <- readBamGappedAlignments(bamfile, param=param)
galn5

## Using the 'param' arg to load tags. Except for MF and Aq, the tags
## specified below are predefined tags (see the SAM Spec for the list
## of predefined tags and their meaning).
param <- ScanBamParam(tag=c("MF", "Aq", "NM", "UQ", "H0", "H1"),
                      what="isize")
galn6 <- readBamGappedAlignments(bamfile, param=param)
elementMetadata(galn6)  # "tag" cols always after "what" cols

## readBamGappedReads():
greads1 <- readBamGappedReads(bamfile)
greads1
names(greads1)
qseq(greads1)
greads2 <- readBamGappedReads(bamfile, use.names=TRUE)
greads2
head(names(greads2))
}

\keyword{methods}
\keyword{classes}