intra-range-methods {GenomicAlignments} | R Documentation

## Intra range transformations of a GAlignments or GAlignmentsList object

### Description

This man page documents intra range transformations of a GAlignments or GAlignmentsList object.

See `?`intra-range-methods`` and `?`inter-range-methods`` in the IRanges package for a quick introduction to intra range and inter range transformations.

Intra range methods for GRanges and GRangesList objects are defined and documented in the GenomicRanges package.

### Usage

    ## S4 method for signature 'GAlignments'
    narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
    ## S4 method for signature 'GAlignmentsList'
    narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)

    ## S4 method for signature 'GAlignments'
    qnarrow(x, start=NA, end=NA, width=NA)
    ## S4 method for signature 'GAlignmentsList'
    qnarrow(x, start=NA, end=NA, width=NA)

### Arguments

`x` | A GAlignments or GAlignmentsList object.
`start, end, width` | Vectors of integers. NAs and negative values are accepted and "solved" according to the rules of the SEW (Start/End/Width) interface (see `?solveUserSEW` for more information about the SEW interface). See `?`intra-range-methods`` for more information about the `start`, `end`, and `width` arguments.
`use.names` | See `?`intra-range-methods``.

### Details

- () `narrow` on a GAlignments object behaves like on a IntegerRanges object. See `?`intra-range-methods`` for the details.

  A major difference though is that it returns a GAlignments object instead of a IntegerRanges object.

  Unlike with `qnarrow` (see below), the `start`/`end`/`width` arguments here describe the narrowing on the reference side, not the query side.

- () `qnarrow` on a GAlignments object behaves like `narrow` except that the `start`/`end`/`width` arguments here specify the narrowing with respect to the query sequences.

  `qnarrow` on a GAlignmentsList object returns a GAlignmentsList object.

### Value

An object of the same class as, and parallel to (i.e. same length and names as), the original object `x`.

### Note

There is no difference between `narrow` and `qnarrow` when all the alignments have a simple CIGAR (i.e. no indels or junctions).

### Author(s)

Hervé Pagès and V. Obenchain <Valerie.Obenchain@RoswellPark.org>

### See Also

- GAlignments and GAlignmentsList objects.

- The intra-range-methods man page in the IRanges package.

- The intra-range-methods man page in the GenomicRanges package.

### Examples

    ## ---------------------------------------------------------------------
    ## A. ON A GAlignments OBJECT
    ## ---------------------------------------------------------------------
    ex1_file <- system.file("extdata", "ex1.bam", package="Rsamtools")
    param <- ScanBamParam(what=c("seq", "qual"))
    gal <- readGAlignments(ex1_file, param=param)
    gal

    ## This trims 3 nucleotides on the left and 5 nucleotides on the right
    ## of each alignment:
    gal2 <- qnarrow(gal, start=4, end=-6)
    gal2

    ## Note that the 'start' and 'end' values are relative to the query
    ## sequences and specify the query substring that must be kept for each
    ## alignment. Negative values are relative to the right end of the query
    ## sequence.

    ## Also note that the metadata columns on 'gal' are propagated as-is so
    ## the "seq" and "qual" matadata columns must be adjusted "by hand" with
    ## narrow();
    mcols(gal2)$seq <- narrow(mcols(gal)$seq, start=4, end=-6)
    mcols(gal2)$qual <- narrow(mcols(gal)$qual, start=4, end=-6)
    gal2

    ## Sanity checks:
    stopifnot(identical(qwidth(gal2), width(mcols(gal2)$seq)))
    stopifnot(identical(qwidth(gal2), width(mcols(gal2)$qual)))

    ## ---------------------------------------------------------------------
    ## B. ON A GAlignmentsList OBJECT
    ## ---------------------------------------------------------------------
    gal1 <- GAlignments(
        seqnames=Rle(factor(c("chr1", "chr2", "chr1", "chr3")),
            c(1, 3, 2, 4)),
        pos=1:10, cigar=paste0(10:1, "M"),
        strand=Rle(strand(c("-", "+", "*", "+", "-")), c(1, 2, 2, 3, 2)),
        names=head(letters, 10), score=1:10)

    gal2 <- GAlignments(
        seqnames=Rle(factor(c("chr2", "chr4")), c(3, 4)), pos=1:7,
        cigar=c("5M", "3M2N3M2N3M", "5M", "10M", "5M1N4M", "8M2N1M", "5M"),
        strand=Rle(strand(c("-", "+")), c(4, 3)),
        names=tail(letters, 7), score=1:7)

    galist <- GAlignmentsList(noGaps=gal1, Gaps=gal2)
    galist

    qnarrow(galist)

[Package GenomicAlignments version 1.20.1 Index]