Gviz (version 1.16.1)

AnnotationTrack-class: AnnotationTrack class and methods

Description

A fairly generic track object for arbitrary genomic range annotations, with the option of grouped track items. The extended DetailsAnnotationTrack provides a more flexible interface to add user-defined custom information for each range.

Usage

AnnotationTrack(range=NULL, start=NULL, end=NULL, width=NULL, feature,
                group, id, strand, chromosome, genome,
                stacking="squish", name="AnnotationTrack", fun,
                selectFun, importFunction, stream=FALSE, ...)

Arguments

range

An optional meta argument to handle the different input types. If the range argument is missing, all the relevant information to create the object has to be provided as individual function arguments (see below).

The different input options for range are:

[object Object],[object Object],[object Object],[object Object],[object Object]

start, end, width

Integer vectors, giving the start and the end end coordinates for the individual track items, or their width. Two of the three need to be specified, and have to be of equal length or of length one, in which case this single value will be recycled. Otherwise, the usual R recycling rules for vectors do not apply here.

feature

Factor (or other vector that can be coerced into one), giving the feature types for the individual track items. When plotting the track to the device, if a display parameter with the same name as the value of feature is set, this will be used as the track item's fill color. See grouping for details. Needs to be of equal length as the provided genomic coordinates, or of length 1.

group

Factor (or other vector that can be coerced into one), giving the group memberships for the individual track items. When plotting to the device, all items in the same group will be connected. See grouping for details. Needs to be of equal length as the provided genomic coordinates, or of length 1.

id

Character vector of track item identifiers. When plotting to the device, it's value will be used as the identifier tag if the display parameter showFeatureId=TRUE. Needs to be of equal length as the provided genomic ranges, or of length 1.

strand

Character vector, the strand information for the individual track items. It may be provided in the form + for the Watson strand, - for the Crick strand or * for either one of the two. Needs to be of equal length as the provided genomic coordinates, or of length 1. Please note that grouped items need to be on the same strand, and erroneous entries will result in casting of an error.

chromosome

The chromosome on which the track's genomic ranges are defined. A valid UCSC chromosome identifier if options(ucscChromosomeNames=TRUE). Please note that in this case only syntactic checking takes place, i.e., the argument value needs to be an integer, numeric character or a character of the form chrx, where x may be any possible string. The user has to make sure that the respective chromosome is indeed defined for the the track's genome. If not provided here, the constructor will try to construct the chromosome information based on the available inputs, and as a last resort will fall back to the value chrNA. Please note that by definition all objects in the Gviz package can only have a single active chromosome at a time (although internally the information for more than one chromosome may be present), and the user has to call the chromosome<- replacement method in order to change to a different active chromosome.

genome

The genome on which the track's ranges are defined. Usually this is a valid UCSC genome identifier, however this is not being formally checked at this point. If not provided here the constructor will try to extract this information from the provided input, and eventually will fall back to the default value of NA.

stacking

The stacking type for overlapping items of the track. One in c(hide, dense, squish, pack,full). Currently, only squish (make best use of the available space), dense (no stacking, collapse overlapping ranges), and hide (do not show any track items at all) are implemented.

name

Character scalar of the track's name used in the title panel when plotting.

fun

A function that is being called for each entry in the AnnotationTrack object. See section 'Details' and 'Examples' for further information. When called internally by the plotting machinery, a number of arguments are automatically passed on to this function, and the user needs to make sure that they can all be digested (i.e., either have all of them as formal named function arguments, or gobble up everything that is not needed in ...). These arguments are:

• start: the genomic start coordinate of the range item.

end: the genomic end coordinates of the range item. strand: the strand information for the range item. chromosome: the chromosome of the range item. identifier: the identifier of the range item, i.e., the result of calling identifier(DetailsAnnotationTrack, lowest=TRUE). Typically those identifiers are passed on to the object constructor during instantiation as the id argument.

index: a counter enumerating the ranges. The AnnotationTrack object is sorted internally for visibility, and the index argument refers to the index of plotting.

GdObject: a reference to the currently plotted DetailsAnnotationTrack object.

GdObject.original: a reference to the DetailsAnnotationTrack before any processing like item collapsing has taken place. Essentially, this is the track object as it exists in your working environment.

Value

• The return value of the constructor function is a new object of class AnnotationTrack or of class DetailsAnnotationTrack, depending on the constructor arguments. Typically the user will not have to be troubled with this distinction and can rely on the constructor to make the right choice.

Objects from the class

Objects can be created using the constructor function AnnotationTrack.

item

• selectFun
• importFunction
• stream
• ...

code

settings

Extends

Class "StackedTrack", directly. Class "RangeTrack", by class "StackedTrack", distance 2. Class "GdObject", by class "StackedTrack", distance3.

DetailsAnnotationTrack directly extends AnnotationTrack.

Details

The DetailsAnnotationTrack class directly extends AnnotationTrack. The purpose of this track type is to add an arbitrarily detailed plot section (typically consisting of additional quantitative data) for each range element of an AnnotationTrack. This allows a locus wide view of annotation elements together with any kind of details per feature or element that may for instance provide insight on how some complex quantitative measurements change accoring to their position in a locus. If the quantitative data is too complex for a DataTrack e.g. because it requires extra space or a trellis-like representation, a DetailsAnnotationTrack can be used instead. Example: An AnnotationTrack shows the positions of a number of probes from a microarray, and you want a histogram of the signal intensity distribution derived from all samples at each of these probe location. Another example usage would be to show for each element of an AnnotationTrack an xy-plot of the signal against some clinical measurement such as blood preassure. The limitation for applications of this type of track is basically only the available space of the device you are plotting to.

This flexibility is possible by utilizing a simple function model to perform all the detailed plotting. The functionality of this plotting function fun is totally up to the user, and the function environment is prepared in a way that all necessary information about the plotted annotation feature is available. To restrict the details section to only selected number of annotation features one can supply another function selectFun, which decides for each feature separatly whether details are available or not. Finally, an arbitrary number of additional arguments can be passed on to these two function by means of the detailsFunArgs display parameter. This is expected to be a named list, and all list elements are passed along to the plotting function fun and to the selector function selectFun as additional named arguments. Please note that some argument names like start, end or identifier are reserved and can not be used in the detailsFunArgs list. For examples of plotting functions, see the 'Examples' section.

See Also

DisplayPars

GdObject

GRanges

ImageMap

IRanges

RangeTrack

StackedTrack

collapsing

DataTrack

grouping

panel.grid

plotTracks

settings

Examples

## An empty object
AnnotationTrack()

## Construct from individual arguments
st <- c(2000000, 2070000, 2100000, 2160000)
ed <- c(2050000, 2130000, 2150000, 2170000)
str <- c("-", "+", "-", "-")
gr <- c("Group1","Group2","Group1", "Group3")

annTrack <- AnnotationTrack(start=st, end=ed, strand=str, chromosome=7, genome="hg19", feature="test",
                            group=gr, id=paste("annTrack item", 1:4), name="generic annotation", stacking="squish")

## Or from a data.frame
df <- data.frame(start=st, end=ed, strand=str, id=paste("annTrack item", 1:4), feature="test",
                 group=gr)
annTrack <- AnnotationTrack(range=df, genome="hg19", chromosome=7, name="generic annotation", 
                             stacking="squish")

## Or from a GRanges object
gr <- GRanges(seqnames="chr7", range=IRanges(start=df$start, end=df$end), strand=str)
genome(gr) <- "hg19"
mcols(gr) <- df[,-(1:3)]
annTrack <- AnnotationTrack(range=gr, name="generic annotation", stacking="squish")

## Finally from a GRangesList
grl <- split(gr, values(gr)$group)
AnnotationTrack(grl)

## For some annoying reason the postscript device does not know about
## the sans font
if(!interactive())
{
font <- ps.options()$family
displayPars(annTrack) <- list(fontfamily=font, fontfamily.title=font)
}

## Plotting
plotTracks(annTrack)

## Track names
names(annTrack)
names(annTrack) <- "foo"
plotTracks(annTrack)

## Subsetting and splitting
subTrack <- subset(annTrack, to=2155000)
length(subTrack)
subTrack[1:2]
split(annTrack, c(1,2,1,2))

## Accessors
start(annTrack)
end(annTrack)
width(annTrack)
position(annTrack)
width(subTrack) <- width(subTrack)+1000

strand(annTrack)
strand(subTrack) <- "-"

chromosome(annTrack)
chromosome(subTrack) <- "chrX"

genome(annTrack)
genome(subTrack) <- "mm9"

range(annTrack)
ranges(annTrack)

## Annotation
identifier(annTrack)
identifier(annTrack, "lowest")
identifier(subTrack) <- "bar"

feature(annTrack)
feature(subTrack) <- "foo"

values(annTrack)

## Grouping
group(annTrack)
group(subTrack) <- "Group 1"
chromosome(subTrack) <- "chr7"
plotTracks(subTrack)

## Stacking
stacking(annTrack)
stacking(annTrack) <- "dense"
plotTracks(annTrack)

## coercion
as(annTrack, "data.frame")
as(annTrack, "UCSCData")

## HTML image map
coords(annTrack)
tags(annTrack)
annTrack <- plotTracks(annTrack)$foo
coords(annTrack)
tags(annTrack)

## DetailsAnnotationTrack
library(lattice) # need to use grid grapics

## generate two random distributions per row (probe/feature)
## the difference between the distributions increases from probe 1 to 4
m <- matrix(c(rgamma(400, 1)), ncol=100)
m[,51:100] <- m[,51:100] + 0:3
## rownames must be accessible by AnnotationTrack element identifier
rownames(m) <- identifier(annTrack, "lowest")

## create a lattice density plot for the values (signals) of the two groups
## as the chart must be placed into a pre-set grid view port we have to use
## print without calling plot.new! Note, use a common prefix for all lattice.
## Avoid wasting space by removing y-axis decorations.

## Note, in this example 'm' will be found in the environment the 'details'
## function is defined in. To avoid overwriting 'm' you should use a closure
## or environment to access 'm'. 
details <- function(identifier, ...) {
	d = data.frame(signal=m[identifier,], group=rep(c("grp1","grp2"), each=50))
    print(densityplot(~signal, group=group, data=d, main=identifier,
	scales=list(draw=FALSE, x=list(draw=TRUE)), ylab="", xlab="",
	), newpage=FALSE, prefix="plot")
}

deTrack <- AnnotationTrack(range=gr, genome="hg19", chromosome=7,
   name="generic annotation with details per entry", stacking="squish",
   fun=details, details.ratio=1)

plotTracks(deTrack)

set.seed(1234)
deTrack <- AnnotationTrack(range=gr, genome="hg19", chromosome=7,
   name="generic annotation with details per entry",
   stacking="squish",fun=details,
    details.ratio=1, selectFun=function(...){sample(c(FALSE, TRUE), 1)})

plotTracks(deTrack)