Range transformations of a GenomicRanges object for optimal file queries.

Description

Given a GRanges object, pack produces a GRangesList of the same ranges grouped and re-ordered.

Usage

## S4 method for signature 'GRanges'
pack(x, ..., range_len = 1e9, inter_range_len = 1e7)

Arguments

Details

Packing ranges

The pack method attempts to re-package ranges in optimal form for extracting data from files. Ranges are not modified (made shorter or longer) but re-ordered and / or re-grouped according to the following criteria.

• order: Ranges are ordered by genomic position within chromosomes.

• distance: Ranges separted by a distance greater than the inter_range_len are packed in groups around the gap separating the distant ranges.

• length: Ranges longer than range_len are packed ‘individually’ (i.e., retrived from the file as a single range vs grouped with other ranges).

Utilities

isPacked(x, ...): Returns a logical indicating if the ranges in x are packed. x must be a GRangesList object.

Value

A GRanges object.

See Also

• unpack for unpacking the result obtained with ‘packed’ ranges.

Examples

  ## Ranges are ordered by position within chromosome.
  gr1 <- GRanges("chr1", IRanges(5:1*5, width = 3)) 
  pack(gr1)
  
  ## Ranges separated by > inter_range_len are partitioned
  ## into groups defined by the endpoints of the gap.
  gr2 <- GRanges("chr2", IRanges(c(1:3, 30000:30003), width = 1000))
  pack(gr2, inter_range_len = 20000)
  
  ## Ranges exceeding 'range_len' are isolated in a single element
  ## of the GRangesList.
  gr3 <- GRanges("chr3", IRanges(c(1:4), width=c(45, 1e8, 45, 45)))
  width(gr3)
  pack(gr3, range_len = 1e7)

Results

R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(GenomicFiles)
Loading required package: BiocGenerics
Loading required package: parallel

Attaching package: 'BiocGenerics'

The following objects are masked from 'package:parallel':

    clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
    clusterExport, clusterMap, parApply, parCapply, parLapply,
    parLapplyLB, parRapply, parSapply, parSapplyLB

The following objects are masked from 'package:stats':

    IQR, mad, xtabs

The following objects are masked from 'package:base':

    Filter, Find, Map, Position, Reduce, anyDuplicated, append,
    as.data.frame, cbind, colnames, do.call, duplicated, eval, evalq,
    get, grep, grepl, intersect, is.unsorted, lapply, lengths, mapply,
    match, mget, order, paste, pmax, pmax.int, pmin, pmin.int, rank,
    rbind, rownames, sapply, setdiff, sort, table, tapply, union,
    unique, unsplit

Loading required package: GenomicRanges
Loading required package: S4Vectors
Loading required package: stats4

Attaching package: 'S4Vectors'

The following objects are masked from 'package:base':

    colMeans, colSums, expand.grid, rowMeans, rowSums

Loading required package: IRanges
Loading required package: GenomeInfoDb
Loading required package: SummarizedExperiment
Loading required package: Biobase
Welcome to Bioconductor

    Vignettes contain introductory material; view with
    'browseVignettes()'. To cite Bioconductor, see
    'citation("Biobase")', and for packages 'citation("pkgname")'.

Loading required package: BiocParallel
Loading required package: Rsamtools
Loading required package: Biostrings
Loading required package: XVector
Loading required package: rtracklayer
> png(filename="/home/ddbj/snapshot/RGM3/R_BC/result/GenomicFiles/pack-methods.Rd_%03d_medium.png", width=480, height=480)
> ### Name: pack
> ### Title: Range transformations of a 'GenomicRanges' object for optimal
> ###   file queries.
> ### Aliases: pack isPacked pack,GRanges-method
> ### Keywords: methods
> 
> ### ** Examples
> 
>   ## Ranges are ordered by position within chromosome.
>   gr1 <- GRanges("chr1", IRanges(5:1*5, width = 3)) 
>   pack(gr1)
GRangesList object of length 1:
[[1]] 
GRanges object with 5 ranges and 0 metadata columns:
      seqnames    ranges strand
         <Rle> <IRanges>  <Rle>
  [1]     chr1  [ 5,  7]      *
  [2]     chr1  [10, 12]      *
  [3]     chr1  [15, 17]      *
  [4]     chr1  [20, 22]      *
  [5]     chr1  [25, 27]      *

-------
seqinfo: 1 sequence from an unspecified genome; no seqlengths
>   
>   ## Ranges separated by > inter_range_len are partitioned
>   ## into groups defined by the endpoints of the gap.
>   gr2 <- GRanges("chr2", IRanges(c(1:3, 30000:30003), width = 1000))
>   pack(gr2, inter_range_len = 20000)
GRangesList object of length 2:
[[1]] 
GRanges object with 3 ranges and 0 metadata columns:
      seqnames    ranges strand
         <Rle> <IRanges>  <Rle>
  [1]     chr2 [1, 1000]      *
  [2]     chr2 [2, 1001]      *
  [3]     chr2 [3, 1002]      *

[[2]] 
GRanges object with 4 ranges and 0 metadata columns:
      seqnames         ranges strand
  [1]     chr2 [30000, 30999]      *
  [2]     chr2 [30001, 31000]      *
  [3]     chr2 [30002, 31001]      *
  [4]     chr2 [30003, 31002]      *

-------
seqinfo: 1 sequence from an unspecified genome; no seqlengths
>   
>   ## Ranges exceeding 'range_len' are isolated in a single element
>   ## of the GRangesList.
>   gr3 <- GRanges("chr3", IRanges(c(1:4), width=c(45, 1e8, 45, 45)))
>   width(gr3)
[1]        45 100000000        45        45
>   pack(gr3, range_len = 1e7)
GRangesList object of length 3:
[[1]] 
GRanges object with 1 range and 0 metadata columns:
      seqnames    ranges strand
         <Rle> <IRanges>  <Rle>
  [1]     chr3   [1, 45]      *

[[2]] 
GRanges object with 1 range and 0 metadata columns:
      seqnames         ranges strand
  [1]     chr3 [2, 100000001]      *

[[3]] 
GRanges object with 2 ranges and 0 metadata columns:
      seqnames  ranges strand
  [1]     chr3 [3, 47]      *
  [2]     chr3 [4, 48]      *

-------
seqinfo: 1 sequence from an unspecified genome; no seqlengths
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>