rtracklayer (version 1.32.0)

WIGFile-class: WIG Import and Export

Description

These functions support the import and export of the UCSC WIG (Wiggle) format.

Usage

## S3 method for class 'WIGFile,ANY,ANY':
import(con, format, text, genome = NA,
                    trackLine = TRUE, which = NULL, seqinfo = NULL, ...)
import.wig(con, ...)
## S3 method for class 'ANY,WIGFile,ANY':
export(object, con, format, ...)
## S3 method for class 'GenomicRanges,WIGFile,ANY':
export(object, con, format,
                   dataFormat = c("auto", "variableStep", "fixedStep"),
                   writer = .wigWriter, append = FALSE, ...)
## S3 method for class 'GenomicRangesList,WIGFile,ANY':
export(object, con, format, ...)
## S3 method for class 'UCSCData,WIGFile,ANY':
export(object, con, format,
                   trackLine = TRUE, ...)
export.wig(object, con, ...)

Arguments

con

A path, URL, connection or WIGFile object. For the functions ending in .wig, the file format is indicated by the function name. For the base export and import functions, the format must be indicated another way. If con is a path, URL or connection, either the file extension or the format argument needs to be wig. Compressed files (gz, bz2 and xz) are handled transparently.

object

The object to export, should be a GRanges or something coercible to a GRanges. For exporting multiple tracks, in the UCSC track line metaformat, pass a GenomicRangesList, or something coercible to one.

format

If not missing, should be wig.

text

If con is missing, a character vector to use as the input

trackLine

Whether to parse/output a UCSC track line. An imported track line will be stored in a TrackLine object, as part of the returned UCSCData.

genome

The identifier of a genome, or NA if unknown. Typically, this is a UCSC identifier like hg19. An attempt will be made to derive the seqinfo on the return value using either an installed BSgenome package or UCSC, if network access is available.

seqinfo

If not NULL, the Seqinfo object to set on the result. If the genome argument is not NA, it must agree with genome(seqinfo).

which

A range data structure like RangesList or GRanges. Only the intervals in the file overlapping the given ranges are returned. This is inefficient; use BigWig for efficient spatial queries.

append

If TRUE, and con points to a file path, the data is appended to the file. Obviously, if con is a connection, the data is always appended.

dataFormat

Probably best left to auto. Exists only for historical reasons.

writer

Function for writing out the blocks; for internal use only.

...

Arguments to pass down to methods to other methods. For import, the flow eventually reaches the WIGFile method on import. When trackLine is TRUE, the arguments are passed through export.ucsc, so track line parameters are supported.

Value

• A GRanges with the score values in the score metadata column, which is accessible via the score function.

WIGFile objects

The WIGFile class extends RTLFile and is a formal represention of a resource in the WIG format. To cast a path, URL or connection to a WIGFile, pass it to the WIGFile constructor.

Details

The WIG format is a text-based format for efficiently representing a dense genome-scale score vector. It encodes, for each feature, a range and score. Features from the same sequence (chromosome) are grouped together into a block, with a single block header line indicating the chromosome. There are two block formats: fixed step and variable step. For fixed step, the number of positions (or step) between intervals is the same across an entire block. For variable step, the start position is specified for each feature. For both fixed and variable step, the span (or width) is specified in the header and thus must be the same across all features. This requirement of uniform width dramatically limits the applicability of WIG. For scored features of variable width, consider BEDGraph or BigWig, which is generally preferred over both WIG and BEDGraph. To efficiently convert an existing WIG or BEDGraph file to BigWig, call wigToBigWig. Neither WIG, BEDGraph nor BigWig allow overlapping features.

References

http://genome.ucsc.edu/goldenPath/help/wiggle.html

Examples

test_path <- system.file("tests", package = "rtracklayer")
  test_wig <- file.path(test_path, "step.wig")

  ## basic import calls
  test <- import(test_wig)
  test
  import.wig(test_wig)
  test_wig_file <- WIGFile(test_wig)
  import(test_wig_file)
  test_wig_con <- file(test_wig)
  import(test_wig_con, format = "wig")
  close(test_wig_con)
  test_wig_con <- file(test_wig)
  import(WIGFile(test_wig_con))
  close(test_wig_con)

  ## various options
  import(test_wig, genome = "hg19")
  import(test_wig, trackLine = FALSE)
  which <- as(test[3:4,], "RangesList")
  import(test_wig, which = which)

## basic export calls
  test_wig_out <- file.path(tempdir(), "test.wig")
  export(test, test_wig_out)
  export.wig(test, test_wig_out)
  test_foo_out <- file.path(tempdir(), "test.foo")
  export(test, test_foo_out, format = "wig")
  test_wig_out_file <- WIGFile(test_wig_out)
  export(test, test_wig_out_file)

  ## appending
  test2 <- test
  metadata(test2)$trackLine <- initialize(metadata(test)$trackLine,
                                          name = "test2")
  export(test2, test_wig_out_file, append = TRUE)

  ## passing track line parameters
  export(test, test_wig_out, name = "test2")

  ## no track line
  export(test, test_wig_out, trackLine = FALSE)
  
  ## gzip
  test_wig_gz <- paste(test_wig_out, ".gz", sep = "")
  export(test, test_wig_gz)