readBamGappedAlignments {Rsamtools}R Documentation

Reading GappedAlignments or GappedReads objects from a BAM file

Description

Read a BAM file as a GappedAlignments or GappedReads object.

Usage

readBamGappedAlignments(file, index=file, use.names=FALSE, param=NULL)
readBamGappedReads(file, index=file, use.names=FALSE, param=NULL)

Arguments

file

The character(1) file name of the ‘BAM’ file to be processed.

index

The character(1) name of the index file of the 'BAM' file being processed; this is given without the '.bai' extension.

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.

param

NULL or an instance of ScanBamParam. Like for scanBam, this influences what fields and which records are imported. However, please note that the fields specified thru this ScanBamParam object will be loaded in addition to any field required for generating the returned object (GappedAlignments or GappedReads object) and will be stored in its elementMetadata part. By default (i.e. param=NULL), no additional field is loaded and the flag used is 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 ?GappedAlignments-class for a description of GappedAlignments objects.

See ?GappedReads-class for a description of GappedReads objects.

See ?scanBam for a description of the arguments.

Value

A GappedAlignments object for readBamGappedAlignments.

A GappedReads object for readBamGappedReads.

Note

BAM records corresponding to unmapped reads or to reads that are PCR or optical duplicates are always ignored.

Author(s)

H. Pages

See Also

GappedAlignments-class, GappedReads-class, scanBam, 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))

[Package Rsamtools version 1.6.3 Index]