rtracklayer (version 1.26.3)

GFFFile-class: GFFFile objects

Description

These functions support the import and export of the GFF format, of which there are three versions and several flavors.

Usage

"import"(con, format, text, version = c("", "1", "2", "3"), genome = NA, asRangedData = FALSE, colnames = NULL, which = NULL, feature.type = NULL)
import.gff(con, ...)
import.gff1(con, ...)
import.gff2(con, ...)
import.gff3(con, ...)
"export"(object, con, format, ...)
"export"(object, con, format, version = c("1", "2", "3"), source = "rtracklayer", append = FALSE, index = FALSE)
"export"(object, con, format, ...)
export.gff(object, con, ...)
export.gff1(object, con, ...)
export.gff2(object, con, ...)
export.gff3(object, con, ...)

Arguments

con

A path, URL, connection or GFFFile object. For the functions ending in .gff, .gff1, etc, 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 one of “gff”, “gff1” “gff2”, “gff3”, “gvf”, or “gtf”. Compressed files (“gz”, “bz2” and “xz”) are handled transparently.

object

The object to export, should be a GRanges or something coercible to a GRanges. If the object has a method for asGFF, it is called prior to coercion. This makes it possible to export a GRangesList or TxDb in a way that preserves the hierarchical structure. For exporting multiple tracks, in the UCSC track line metaformat, pass a GenomicRangesList, or something coercible to one.

format

If not missing, should be one of “gff”, “gff1” “gff2”, “gff3”, “gvf”, or “gtf”.

version

If the format is given as “gff”, i.e., it does not specify a version, then this should indicate the GFF version as one of “” (for import only, from the gff-version directive in the file or “1” if none), “1”, “2” or “3”.

text

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

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.

asRangedData

If TRUE, a RangedData is returned, instead of a GRanges.

colnames

A character vector naming the columns to parse. These should name either fixed fields, like source or strand, or, for GFF2 and GFF3, any attribute.

which

A range data structure like RangesList or GRanges. Only the intervals in the file overlapping the given ranges are returned. This is much more efficient when the file is indexed with the tabix utility.

feature.type

NULL (the default) or a character vector of valid feature types. If not NULL, then only the features of the specified type(s) are imported.

source

The value for the source column in GFF. This is typically the name of the package or algorithm that generated the feature.

index

If TRUE, automatically compress and index the output file with bgzf and tabix. Note that tabix indexing will sort the data by chromosome and start. Does not work when exporting a RangedDataList with multiple elements; tabix supports a single track in a file.

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.

...

Arguments to pass down to methods to other methods. For import, the flow eventually reaches the GFFFile method on import. For export, the RangedData, GFFFile method on export is the sink. When trackLine is TRUE or the target format is BED15, the arguments are passed through export.ucsc, so track line parameters are supported.

Value

A GRanges (or RangedData if asRangedData is TRUE), with the metadata columns described in the details.

GFFFile objects

The GFFFile class extends RTLFile and is a formal represention of a resource in the GFF format. To cast a path, URL or connection to a GFFFile, pass it to the GFFFile constructor. The GFF1File, GFF2File, GFF3File, GVFFile and GTFFile classes all extend GFFFile and indicate a particular version of the format. It has the following utility methods:

genome: Gets the genome identifier from the “genome-build” header directive.

Details

The Generic Feature Format (GFF) format is a tab-separated table of intervals. There are three different versions of GFF, and they all have the same number of columns. In GFF1, the last column is a grouping factor, whereas in the later versions the last column holds application-specific attributes, with some conventions defined for those commonly used. This attribute support facilitates specifying extensions to the format. These include GTF (Gene Transfer Format, an extension of GFF2) and GVF (Genome Variation Format, an extension of GFF3). The rtracklayer package recognizes the “gtf” and “gvf” extensions and parses the extra attributes into columns of the result; however, it does not perform any extension-specific processing. Both GFF1 and GFF2 have been proclaimed obsolete; however, the UCSC Genome Browser only supports GFF1 (and GTF), and GFF2 is still in broad use.

GFF is distinguished from the simpler BED format by its flexible attribute support and its hierarchical structure, as specified by the group column in GFF1 (only one level of grouping) and the Parent attribute in GFF3. GFF2 does not specify a convention for representing hierarchies, although its GTF extension provides this for gene structures. The combination of support for hierarchical data and arbitrary descriptive attributes makes GFF(3) the preferred format for representing gene models.

Although GFF features a score column, large quantitative data belong in a format like BigWig and alignments from high-throughput experiments belong in BAM. For variants, the VCF format (supported by the VariantAnnotation package) seems to be more widely adopted than the GVF extension.

A note on the UCSC track line metaformat: track lines are a means for passing hints to visualization tools like the UCSC Genome Browser and the Integrated Genome Browser (IGB), and they allow multiple tracks to be concatenated in the same file. Since GFF is not a UCSC format, it is not common to annotate GFF data with track lines, but rtracklayer still supports it. To export or import GFF data in the track line format, call export.ucsc or import.ucsc. The following is the mapping of GFF elements to a GRanges or RangedData object. NA values are allowed only where indicated. These appear as a “.” in the file. GFF requires that all columns are included, so export generates defaults for missing columns.

seqid, start, end

the ranges component.

source

character vector in the source column; defaults to “rtracklayer” on export.

type

character vector in the type column; defaults to “sequence_feature” in the output, i.e., SO:0000110.

score

numeric vector (NA's allowed) in the score column, accessible via the score accessor; defaults to NA upon export.

strand

strand factor (NA's allowed) in the strand column, accessible via the strand accessor; defaults to NA upon export.

phase

integer vector, either 0, 1 or 2 (NA's allowed); defaults to NA upon export.

group

a factor (GFF1 only); defaults to the seqid (e.g., chromosome) on export.

In GFF versions 2 and 3, attributes map to arbitrary columns in the result. In GFF3, some attributes (Parent, Alias, Note, DBxref and Ontology_term) can have multiple, comma-separated values; these columns are thus always CharacterList objects.

References

GFF1, GFF2

http://www.sanger.ac.uk/resources/software/gff/spec.html

GFF3

http://www.sequenceontology.org/gff3.shtml

GVF

http://www.sequenceontology.org/resources/gvf.html

GTF

http://mblab.wustl.edu/GTF22.html

Examples

  test_path <- system.file("tests", package = "rtracklayer")
  test_gff3 <- file.path(test_path, "genes.gff3")

  ## basic import
  test <- import(test_gff3, asRangedData = FALSE)
  test

  ## import.gff functions
  import.gff(test_gff3, asRangedData = FALSE)
  import.gff3(test_gff3, asRangedData = FALSE)

  ## GFFFile derivatives
  test_gff_file <- GFF3File(test_gff3)
  import(test_gff_file, asRangedData = FALSE)
  test_gff_file <- GFFFile(test_gff3)
  import(test_gff_file, asRangedData = FALSE)
  test_gff_file <- GFFFile(test_gff3, version = "3")
  import(test_gff_file, asRangedData = FALSE)

  ## from connection
  test_gff_con <- file(test_gff3)
  test <- import(test_gff_con, format = "gff", asRangedData = FALSE)
  close(test_gff_con)

  ## various arguments
  import(test_gff3, genome = "hg19", asRangedData = FALSE)
  import(test_gff3, colnames = character(), asRangedData = FALSE)
  import(test_gff3, colnames = c("strand", "geneName"), asRangedData = FALSE)

  ## 'which'
  which <- RangesList(chr10 = IRanges(90000, 93000))
  import(test_gff3, which = which, asRangedData = FALSE)

## Not run: 
#   ## 'append'
#   test_gff3_out <- file.path(tempdir(), "genes.gff3")
# 
#   export(test[seqnames(test) == "chr10"], test_gff3_out)
#   export(test[seqnames(test) == "chr12"], test_gff3_out, append = TRUE)
#   import(test_gff3_out, asRangedData = FALSE)
#   
#   ## 'index'
#   export(test, test_gff3_out, index = TRUE)
#   test_bed_gz <- paste(test_gff3_out, ".gz", sep = "")
#   import(test_bed_gz, which = which, asRangedData = FALSE)
# 
#   ## RangedDataList  
#   rdl <-
#     RangedDataList(new("UCSCData", test[1],
#                        trackLine = new("BasicTrackLine", name = "chr10")),
#                    new("UCSCData", test[2],
#                        trackLine = new("BasicTrackLine", name = "chr12")))
#   names(rdl) <- names(test)
#   export(rdl, test_gff3_out)
#   import.ucsc(test_gff3_out, asRangedData = FALSE)
# ## End(Not run)