DataTrack-class: DataTrack class and methods

In Gviz: Plotting data and annotation information along genomic coordinates

Description

A class to store numeric data values along genomic coordinates. Multiple samples as well as sample groupings are supported, with the restriction of equal genomic coordinates for a single observation across samples.

Usage

DataTrack(range=NULL, start=NULL, end=NULL, width=NULL, data, chromosome, strand, genome,
name="DataTrack", importFunction, stream=FALSE, ...)

Arguments

We tried to keep instantiation of DataTrack objects as flexible as possible to accomodate different use cases. For instance, one natural way to create a DataTrack is from an existing GRanges object. In other cases it might be more appropriate to build the object using individual function 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: A GRanges object: essentially all the necessary information to create a DataTrack can be contained in a single GRanges object. The track's coordinates are taken from the start, end and seqnames slots, the genome information from the genome slot, and the numeric data values can be extracted from additional metadata columns columns (please note that non-numeric columns are being ignored with a warning). As a matter of fact, calling the constructor on a GRanges object without further arguments, e.g. DataTrack(range=obj) is equivalent to calling the coerce method as(obj, "DataTrack"). Alternatively, the GRanges object may only contain the coordinate information, in which case the numeric data part is expected to be present in the separate data argument, and the ranges have to match the dimensions of the data matrix. If data is not NULL, this will always take precedence over anything defined in the range argument. See below for details. An IRanges object: this is very similar to the above case, except that the numeric data part now always has to be provided in the separate data argument. Also the chromosome information must be provided in the chromosome argument, because neither of the two can be directly encoded in an IRange object. A data.frame object: the data.frame needs to contain at least the two mandatory columns start and end with the range coordinates. It may also contain a chromosome column with the chromosome information for each range. If missing it will be drawn from the separate chromosome argument. All additional numeric columns will be interpreted as data columns, unless the data argument is explicitely provided. A character scalar: in this case the value of the range argument is considered to be a file path to an annotation file on disk. A range of file types are supported by the Gviz package as identified by the file extension. See the importFunction documentation below for further details.
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 the single value will be recycled accordingly. Otherwise, the usual R recycling rules for vectors do not apply and the function will cast an error.
data	A numeric matrix of data points with the number of columns equal to the number of coordinates in range, or a numeric vector of appropriate length that will be coerced into such a one-row matrix. Each individual row is supposed to contain data for a given sample, where the coordinates for each single observation are constant across samples. Depending on the plotting type of the data (see 'Details' and 'Display Parameters' sections), sample grouping or data aggregation may be available. Alternatively, this can be a character vector of column names that point into the element metadata of the range object for subsetting. Naturally, this is only supported when the range argument is of class GRanges.
strand	Character vector, the strand information for the individual track items. Currently this has to be unique for the whole track and doesn't really have any visible consequences, but we might decide to make DataTracks strand-specific at a later stage.
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.
name	Character scalar of the track's name used in the title panel when plotting.
importFunction	A user-defined function to be used to import the data from a file. This only applies when the range argument is a character string with the path to the input data file. The function needs to accept an argument file containing the file path and has to return a proper GRanges object with the data part attached as numeric metadata columns. Essentially the process is equivalent to constructing a DataTrack directly from a GRanges object in that non-numeric columns will be dropped, and further subsetting can be archived by means of the data argument. A set of default import functions is already implemented in the package for a number of different file types, and one of these defaults will be picked automatically based on the extension of the input file name. If the extension can not be mapped to any of the existing import function, an error is raised asking for a user-defined import function. Currently the following file types can be imported with the default functions: wig, bigWig/bw, bedGraph and bam. Some file types support indexing by genomic coordinates (e.g., bigWig and bam), and it makes sense to only load the part of the file that is needed for plotting. To this end, the Gviz package defines the derived ReferenceDataTrack class, which supports streaming data from the file system. The user typically does not have to deal with this distinction but may rely on the constructor function to make the right choice as long as the default import functions are used. However, once a user-defined import function has been provided and if this function adds support for indexed files, you will have to make the constructor aware of this fact by setting the stream argument to TRUE. Please note that in this case the import function needs to accept a second mandatory argument selection which is a GRanges object containing the dimensions of the plotted genomic range. As before, the function has to return an appropriate GRanges object.
stream	A logical flag indicating that the user-provided import function can deal with indexed files and knows how to process the additional selection argument when accessing the data on disk. This causes the constructor to return a ReferenceDataTrack object which will grab the necessary data on the fly during each plotting operation.
...	Additional items which will all be interpreted as further display parameters.

Details

Depending on the setting of the type display parameter, the data can be plotted in various different forms as well as combinations thereof. Supported plotting types are:

p: simple xy-plot.

l: lines plot. In the case of multiple samples this plotting type is not overly usefull since the points in the data matrix are connected in column-wise order. Type a might be more appropriate in these situations.

b: combination of xy-plot and lines plot.

a: lines plot of the column-wise average values.

s: sort and connect data points along the x-axis

S: sort and connect data points along the y-axis

g: add grid lines. To ensure a consitant look and feel across multiple tracks, grid lines should preferentially be added by using the grid display parameter.

r: add a regression line to the plot.

h: histogram-like vertical lines centered in the middle of the coordinate ranges.

smooth: add a loess fit to the plot. The following display parameters can be used to control the loess calculation: span, degree, family, evaluation. See panel.loess for details.

histogram: plot data as a histogram, where the width of the histogram bars reflects the width of the genomic ranges in the range slot.

mountain: plot a smoothed version of the data relative to a baseline, as defined by the baseline display parameter. The following display parameters can be used to control the smoothing: span, degree, family, evaluation. See panel.loess for details. The layout of the plot can be further customized via the following display parameters: col.mountain, lwd.mountain, lty.mountain, fill.mountain.

polygon: plot data as a polygon (similar to mountain-type but without smoothing). Data are plotted relative to a baseline, as defined by the baseline display parameter. The layout of the plot can be further customized via the following display parameters: col.mountain, lwd.mountain, lty.mountain, fill.mountain.

boxplot: plot the data as box-and-whisker plots. The layout of the plot can be further customized via the following display parameters: box.ratio, box.width, varwidt, notch, notch.frac, levels.fos, stats, coef, do.out. See panel.bwplot for details.

gradient: collapse the data across samples and plot this average value as a color-coded gradient. Essenitally this is similar to the heatmap-type plot of a single sample. The layout of the plot can be further customized via the display parameters ncolor and gradient which control the number of gradient colors as well as the gradient base colors, respectively.

heatmap: plot the color-coded values for all samples in the form of a heatmap. The data for individual samples can be visually separated by setting the separator display parameter. It's value is taken as the amount of spacing in pixels in between two heatmap rows. The layout of the plot can be further customized via the display parameters ncolor and gradient which control the number of gradient colors as well as the gradient base colors, respectively.

horizon: plot continuous data by cutting the y range into segments and overplotting them with color representing the magnitude and direction of deviation. This is particularly useful when comparing multiple samples, in which case the horizon strips are stacked. See horizonplot for details. Please note that the origin and horizonscale arguments of the Lattice horizonplot function are available as display parameters horizon.origin and horizon.scale.

For some of the above plotting-types the groups display parameter can be used to indicate sample sub-groupings. Its value is supposed to be a factor vector of similar length as the number of samples. In most cases, the groups are shown in different plotting colors and data aggregation operations are done in a stratified fashion.

The window display parameter can be used to aggregate the data prior to plotting. Its value is taken as the number of equal-sized windows along the genomic coordinates of the track for which to compute average values. The special value auto can be used to automatically determine a reasonable number of windows which can be particularly useful when plotting very large genomic regions with many data points.

The aggregation parameter can be set to define the aggregation function to be used when averaging in windows or across collapsed items. It takes the form of either a function which should condense a numeric vector into a single number, or one of the predefined options as character scalars "mean", "median" or "sum" for mean, median or summation, respectively. Defaults to computing mean values for each sample. Note that the predefined options can be much faster because they are optimized to work on large numeric tables.

Value

The return value of the constructor function is a new object of class DataTrack or ReferenceDataTrack.

Objects from the class

Objects can be created using the constructor function DataTrack.

Slots

data:

Object of class "matrix", containing the data values to be plotted. Individual rows of the matrix correspond to individual samples, and the number of columns has to be identical to the feature number of the GRanges object in the range slot.

strand:

Object of class "character", the strand information for the track, in the form '+' for the Watson strand, '-' for the Crick strand or '*' for either of the two.

range:

Object of class IRanges, inherited from class RangeTrack. The genomic coordinates for the data values. The length of the object needs to be identical to the number of columns of the data matrix in the data slot.

chromosome:

Object of class "character", inherited from class RangeTrack

genome:

Object of class "character", inherited from class RangeTrack

dp:

Object of class DisplayPars, inherited from class GdObject

name:

Object of class "character", inherited from class GdObject

imageMap:

Object of class ImageMap, inherited from class GdObject

Extends

Class "NumericTrack", directly.

Class "RangeTrack", by class "NumericTrack", distance 2.

Class "GdObject", by class "NumericTrack", distance 3.

Methods

In the following code chunks, obj is considered to be an object of class DataTrack.

Exported in the name space:

[

signature(x="DataTrack"): subsetting of the object, either to a subet of coordinates, or to a subset of samples.

Additional Arguments:

i, j: subsetting indices for coordinates (i) or samples (j).

Examples:

obj[1:3,]

obj[,2:4]

values

signature(x="DataTrack"): return the raw data values of the object, i.e., the data matrix in the data slot.

Usage:

values(x)

Examples:

values(obj)

values<-

signature(x="DataTrack"): replace the data matrix in the data slot.

Usage:

values<-(x, value)

Additional Arguments:

value: replacement value.

Examples:

values(obj) <- matrix(1:10, ncol=2)

score

signature(x="DataTrack"): return processed data values of the object exactly like they would be plotted to the device (modulo any potential aggregration or collapsing), i.e., the raw data with optional transformations applied.

Usage:

score(x, from=NULL, to=NULL, sort=FALSE, transformation=TRUE)

Additional Arguments:

from, to: restrict to data within a certain coordinates range.

sort: sort the return values by coordinates. This is usually not necessary since the data should already be ordererd, however this is not formaly checked anywhere and some operations strictly depend on ordered data.

transformation: apply a data transformation in case one is defined as the transformation display parameter.

Examples:

score(obj)

score(obj, from=100, to=10000)

score(obj, sort=TRUE, transformation=FALSE)

split

signature(x="DataTrack"): split a DataTrack object by an appropriate factor vector (or another vector that can be coerced into one). The output of this operation is a list of DataTrack objects.

Usage:

split(x, f, ...)

Additional Arguments:

f: the splitting factor.

...: all further arguments are ignored.

Examples:

split(obj, c("a", "a", "b", "c", "a"))

range, ranges

signature(x="DataTrack"): return the genomic coordinates for the track as an object of class IRanges.

Usage:

range(x)

ranges(x)

Examples:

range(obj)

ranges(obj)

strand

signature(x="DataTrack"): return a vector of strand specifiers for all track items, in the form '+' for the Watson strand, '-' for the Crick strand or '*' for either of the two.

Usage:

strand(x)

Examples:

strand(obj)

strand<-

signature(x="DataTrack"): replace the strand information for the track items. The replacement value needs to be an appropriate scalar or vector of strand values.

Usage:

strand<-(x, value)

Additional Arguments:

value: replacement value.

Examples:

strand(obj) <- "+"

feature

signature(GdObject="DataTrack"): returns NULL since there is no grouping information for the ranges in a DataTrack.

Usage:

feature(GdObject)

Examples:

feature(obj)

feature<-

signature(gdObject="DataTrack", value="character"): this return the unaltered input object since there is no grouping information for the ranges in a DataTrack.

Usage:

feature<-(GdObject, value)

Additional Arguments:

value: replacement value.

Examples:

feature(obj) <- c("a", "a", "b", "c", "a")

Internal methods:

collapseTrack

signature(gdObject="DataTrack"): preprocess the track before plotting. This will collapse overlapping track items based on the available resolution and increase the width and height of all track objects to a minimum value to avoid rendering issues. See collapsing for details.

Usage:

collapseTrack(GdObject, diff=.pxResolution(coord="x"))

Additional Arguments:

diff: the minimum pixel width to display, everything below that will be inflated to a width of diff.

Examples:

Gviz:::collapseTrack(obj)

drawGD

signature(GdObject="DataTrack"): plot the object to a graphics device. The return value of this method is the input object, potentially updated during the plotting operation. Internally, there are two modes in which the method can be called. Either in 'prepare' mode, in which case no plotting is done but the object is preprocessed based on the available space, or in 'plotting' mode, in which case the actual graphical output is created. Since subsetting of the object can be potentially costly, this can be switched off in case subsetting has already been performed before or is not necessary.

Usage:

drawGD(GdObject, minBase, maxBase, prepare=FALSE, subset=TRUE, ...)

Additional Arguments:

minBase, maxBase: the coordinate range to plot.

prepare: run method in preparation or in production mode.

subset: subset the object to the visible region or skip the potentially expensive subsetting operation.

...: all further arguments are ignored.

Examples:

Gviz:::drawGD(obj)

Gviz:::drawGD(obj, minBase=1, maxBase=100)

Gviz:::drawGD(obj, prepare=TRUE, subset=FALSE)

drawAxis

signature(GdObject="DataTrack"): add a y-axis to the title panel of a track.

Usage:

drawAxis(GdObject, from, to, ...)

Additional Arguments:

from, to: compute axis range from the data within a certain coordinates range only.

...: all further arguments are ignored.

Examples:

Gviz:::drawAxis(obj)

initialize

signature(.Object="DataTrack"): initialize the object

show

signature(object="DataTrack"): show a human-readable summary of the object

Inherited methods:

drawGrid

signature(GdObject="DataTrack"): superpose a grid on top of a track.

Usage:

drawGrid(GdObject, from, to, ...)

Additional Arguments:

from, to: integer scalars, restrict to coordinate range before computing the grid lines.

Examples:

Gviz:::drawGrid(obj)

chromosome

signature(GdObject="DataTrack"): return the currently active chromosome for which the track is defined. For consistancy with other Bioconductor packages, the isActiveSeq alias is also provided.

Usage:

chromosome(GdObject)

Examples:

chromosome(obj)

chromosome<-

signature(GdObject="DataTrack"): replace the value of the track's active chromosome. This has to be a valid UCSC chromosome identifier or an integer or character scalar that can be reasonably coerced into one, unless options(ucscChromosomeNames=FALSE). For consistancy with other Bioconductor packages, the isActiveSeq<- alias is also provided.

Usage:

chromosome<-(GdObject, value)

Additional Arguments:

value: replacement value.

Examples:

chromosome(obj) <- "chr12"

start, end, width

signature(x="DataTrack"): the start or end coordinates of the track items, or their width in genomic coordinates.

Usage:

start(x)

end(x)

width(x)

Examples:

start(obj)

end(obj)

width(obj)

start<-, end<-, width<-

signature(x="DataTrack"): replace the start or end coordinates of the track items, or their width.

Usage:

start<-(x, value)

end<-(x, value)

width<-(x, value)

Additional Arguments:

value: replacement value.

Examples:

start(obj) <- 1:10

end(obj) <- 20:30

width(obj) <- 1

position

signature(GdObject="DataTrack"): the arithmetic mean of the track item's coordionates, i.e., (end(obj)-start(obj))/2.

Usage:

position(GdObject)

Examples:

position(obj)

genome

signature(x="DataTrack"): return the track's genome.

Usage:

genome(x)

Examples:

genome(obj)

genome<-

signature(x="DataTrack"): set the track's genome. Usually this has to be a valid UCSC identifier, however this is not formally enforced here.

Usage:

genome<-(x, value)

Additional Arguments:

value: replacement value.

Examples:

genome(obj) <- "mm9"

length

signature(x="DataTrack"): return the number of items in the track.

Usage:

length(x)

Examples:

length(obj)

coerce

signature(from="DataTrack", to="data.frame"): coerce the GRanges object in the range slot into a regular data.frame.

Examples:

as(obj, "data.frame")

subset

signature(x="DataTrack"): subset a NumericTrack by coordinates and sort if necessary.

Usage:

subset(x, from, to, sort=FALSE, drop=TRUE, ...)

Additional Arguments:

from, to: the coordinates range to subset to.

sort: sort the object after subsetting. Usually not necessary.

drop: drop unused regions on the other, non-active chromosomes.w

...: additional arguments are ignored.

Examples:

subset(obj, from=10, to=20, sort=TRUE)

displayPars

signature(x="DataTrack", name="character"): list the value of the display parameter name. See settings for details on display parameters and customization.

Usage:

displayPars(x, name)

Examples:

displayPars(obj, "col")

displayPars

signature(x="DataTrack", name="missing"): list the value of all available display parameters. See settings for details on display parameters and customization.

Examples:

displayPars(obj)

getPar

signature(x="DataTrack", name="character"): alias for the displayPars method. See settings for details on display parameters and customization.

Usage:

getPar(x, name)

Examples:

getPar(obj, "col")

getPar

signature(x="DataTrack", name="missing"): alias for the displayPars method. See settings for details on display parameters and customization.

Examples:

getPar(obj)

displayPars<-

signature(x="DataTrack", value="list"): set display parameters using the values of the named list in value. See settings for details on display parameters and customization.

Usage:

displayPars<-(x, value)

Examples:

displayPars(obj) <- list(col="red", lwd=2)

setPar

signature(x="DataTrack", value="character"): set the single display parameter name to value. Note that display parameters in the DataTrack class are pass-by-reference, so no re-assignmnet to the symbol obj is necessary. See settings for details on display parameters and customization.

Usage:

setPar(x, name, value)

Additional Arguments:

name: the name of the display parameter to set.

Examples:

setPar(obj, "col", "red")

setPar

signature(x="DataTrack", value="list"): set display parameters by the values of the named list in value. Note that display parameters in the DataTrack class are pass-by-reference, so no re-assignmnet to the symbol obj is necessary. See settings for details on display parameters and customization.

Examples:

setPar(obj, list(col="red", lwd=2))

group

signature(GdObject="DataTrack"): return grouping information for the individual items in the track. Unless overwritten in one of the sub-classes, this usualy returns NULL.

Usage:

group(GdObject)

Examples:

group(obj)

names

signature(x="DataTrack"): return the value of the name slot.

Usage:

names(x)

Examples:

names(obj)

names<-

signature(x="DataTrack", value="character"): set the value of the name slot.

Usage:

names<-(x, value)

Examples:

names(obj) <- "foo"

coords

signature(ImageMap="DataTrack"): return the coordinates from the internal image map.

Usage:

coords(ImageMap)

Examples:

coords(obj)

tags

signature(x="DataTrack"): return the tags from the internal image map.

Usage:

tags(x)

Examples:

tags(obj)

Display Parameters

The following display parameters are set for objects of class DataTrack upon instantiation, unless one or more of them have already been set by one of the optional sub-class initializers, which always get precedence over these global defaults. See settings for details on setting graphical parameters for tracks.

aggregateGroups=FALSE: Logical scalar. Aggregate the values within a sample group using the aggregation funnction specified in the aggregation parameter.

aggregation="mean": Function or character scalar. Used to aggregate values in windows or for collapsing overlapping items. The function has to accept a numeric vector as a single input parameter and has to return a numeric scalar with the aggregated value. Alternatively, one of the predefined options mean, median sum, min, max or extreme can be supplied as a character scalar. Defaults to mean.

alpha.confint=0.3: Numeric scalar. The transparency for the confidence intervalls in confint-type plots.

amount=NULL: Numeric scalar. Amount of jittering in xy-type plots. See panel.xyplot for details.

baseline=NULL: Numeric scalar. Y-axis position of an optional baseline. This parameter has a special meaning for mountain-type and polygon-type plots, see the 'Details' section in DataTrack for more information.

box.legend=FALSE: Logical scalar. Draw a box around a legend.

box.ratio=1: Numeric scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

box.width=NULL: Numeric scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

cex=0.7: Numeric scalar. The default pixel size for plotting symbols.

cex.legend=0.8: Numeric scalar. The size factor for the legend text.

cex.sampleNames=NULL: Numeric scalar. The size factor for the sample names text in heatmap or horizon plots. Defaults to an automatic setting.

coef=1.5: Numeric scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

col=c("#0080ff", "#ff00ff", "darkgreen", "#ff0000", "orange", "#00ff00", "brown"): Character or integer vector. The color used for all line and symbol elements, unless there is a more specific control defined elsewhere. Unless groups are specified, only the first color in the vector is usually regarded.

col.baseline=NULL: Character scalar. Color for the optional baseline, defaults to the setting of col.

col.boxplotFrame="#808080": Character scalar. Line color of the frame around grouped boxplots.

col.confint: Character vector. Border colors for the confidence intervals for confint-type plots.

col.histogram="#808080": Character scalar. Line color in histogram-type plots.

col.horizon: The line color for the segments in the horizon-type plot. See horizonplot for details.

col.mountain=NULL: Character scalar. Line color in mountain-type and polygon-type plots, defaults to the setting of col.

col.sampleNames="white": Character or integer scalar. The color used for the sample names in heatmap plots.

collapse=FALSE: Logical scalar. Collapse overlapping ranges and aggregate the underlying data.

degree=1: Numeric scalar. Parameter controlling the loess calculation for smooth and mountain-type plots. See panel.loess for details.

do.out=TRUE: Logical scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

evaluation=50: Numeric scalar. Parameter controlling the loess calculation for smooth and mountain-type plots. See panel.loess for details.

factor=0.5: Numeric scalar. Factor to control amount of jittering in xy-type plots. See panel.xyplot for details.

family="symmetric": Character scalar. Parameter controlling the loess calculation for smooth and mountain-type plots. See panel.loess for details.

fill.confint=NULL: Character vector. Fill colors for the confidence intervals for confint-type plots.

fill.histogram=NULL: Character scalar. Fill color in histogram-type plots, defaults to the setting of fill.

fill.horizon=c("#B41414", "#E03231", "#F7A99C", "#9FC8DC", "#468CC8", "#0165B3"): The fill colors for the segments in the horizon-type plot. This should be a vector of length six, where the first three entries are the colors for positive changes, and the latter three entries are the colors for negative changes. Defaults to a red-blue color scheme. See horizonplot for details.

fill.mountain=c("#CCFFFF", "#FFCCFF"): Character vector of length 2. Fill color in mountain-type and polygon-type plots.

fontcolor.legend="#808080": Integer or character scalar. The font color for the legend text.

fontface.legend=NULL: Integer or character scalar. The font face for the legend text.

fontfamily.legend=NULL: Integer or character scalar. The font family for the legend text.

fontsize.legend=NULL: Numeric scalar. The pixel size for the legend text.

gradient=c("#F7FBFF", "#DEEBF7", "#C6DBEF", "#9ECAE1", "#6BAED6", "#4292C6", "#2171B5", "#08519C", "#08306B"): Character vector. The base colors for the gradient plotting type or the heatmap type with a single group. When plotting heatmaps with more than one group, the col parameter can be used to control the group color scheme, however the gradient will always be from white to 'col' and thus does not offer as much flexibility as this gradient parameter.

grid=FALSE: Logical vector. Draw a line grid under the track content.

groups=NULL: Vector coercable to a factor. Optional sample grouping. See 'Details' section in DataTrack for further information.

horizon.origin=0: The baseline relative to which changes are indicated on the horizon-type plot. See horizonplot for details.

horizon.scale=NULL: The scale for each of the segments in the horizon-type plot. Defaults to 1/3 of the absolute data range. See horizonplot for details.

jitter.x=FALSE: Logical scalar. Toggle on jittering on the x axis in xy-type plots. See panel.xyplot for details.

jitter.y=FALSE: Logical scalar. Toggle off jittering on the y axis in xy-type plots. See panel.xyplot for details.

legend=TRUE: Boolean triggering the addition of a legend to the track to indicate groups. This only has an effect if at least two groups are present.

levels.fos=NULL: Numeric scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

lineheight.legend=NULL: Numeric scalar. The line height for the legend text.

lty.baseline=NULL: Character or numeric scalar. Line type of the optional baseline, defaults to the setting of lty.

lty.mountain=NULL: Character or numeric scalar. Line type in mountain-type and polygon-type plots, defaults to the setting of lty.

lwd.baseline=NULL: Numeric scalar. Line width of the optional baseline, defaults to the setting of lwd.

lwd.mountain=NULL: Numeric scalar. Line width in mountain-type and polygon-type plots, defaults to the setting of lwd.

min.distance=0: Numeric scalar. The mimimum distance in pixel below which to collapse ranges.

missingAsZero=TRUE: Logical scalar. Defines how the missing values are treated in the aggregation procedure with running window. Setting it to TRUE fills empty positions with zeros, which is default. FALSE fills empty positions with NA.

na.rm=FALSE: Boolean controlling whether to discard all NA values when plotting or to keep empty spaces for NAs

ncolor=100: Integer scalar. The number of colors for the 'gradient' plotting type

notch=FALSE: Logical scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

notch.frac=0.5: Numeric scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

pch=20: Integer scalar. The type of glyph used for plotting symbols.

separator=0: Numeric scalar. Number of pixels used to separate individual samples in heatmap- and horizon-type plots.

showColorBar=TRUE: Boolean. Indicate the data range color mapping in the axis for 'heatmap' or 'gradient' types.

showSampleNames=FALSE: Boolean. Display the names of the individual samples in a heatmap or a horizon plot.

size=NULL: Numeric scalar. The relative size of the track. Can be overridden in the plotTracks function. By default the size will be set automatically based on the selected plotting type.

span=0.2: Numeric scalar. Parameter controlling the loess calculation for smooth and mountain-type plots. See panel.loess for details.

stackedBars=TRUE: Logical scalar. When there are several data groups, draw the histogram-type plots as stacked barplots or grouped side by side.

stats=function: Function. Parameter controlling the boxplot appearance. See panel.bwplot for details.

transformation=NULL: Function. Applied to the data matrix prior to plotting or when calling the score method. The function should accept exactly one input argument and its return value needs to be a numeric vector which can be coerced back into a data matrix of identical dimensionality as the input data.

type="p": Character vector. The plot type, one or several in p,l, b, a, a_confint, s, g, r, S, confint, smooth, histogram, mountain, polygon, h, boxplot, gradient, heatmap, horizon. See 'Details' section in DataTrack for more information on the individual plotting types.

varwidth=FALSE: Logical scalar. Parameter controlling the boxplot appearance. See panel.bwplot for details.

window=NULL: Numeric or character scalar. Aggregate the rows values of the data matrix to window equally sized slices on the data range using the method defined in aggregation. If negative, apply a running window of size windowSize using the same aggregation method. Alternatively, the special value auto causes the function to determine the optimal window size to avoid overplotting, and fixed uses fixed-size windows of size windowSize.

windowSize=NULL: Numeric scalar. The size of the running window when the value of window is negative.

ylim=NULL: Numeric vector of length 2. The range of the y-axis scale.

yTicksAt=NULL: Numeric vector. The points at which y-axis tick-marks are to be drawn. By default, when NULL, tickmark locations are computed.

Additional display parameters are being inherited from the respective parent classes. Note that not all of them may have an effect on the plotting of DataTrack objects.

GdObject:

alpha=1: Numeric scalar. The transparency for all track items.

alpha.title=NULL: Numeric scalar. The transparency for the title panel.

background.legend="transparent": Integer or character scalar. The background color for the legend.

background.panel="transparent": Integer or character scalar. The background color of the content panel.

background.title="lightgray": Integer or character scalar. The background color for the title panel.

cex.axis=NULL: Numeric scalar. The expansion factor for the axis annotation. Defaults to NULL, in which case it is automatically determined based on the available space.

cex.title=NULL: Numeric scalar. The expansion factor for the title panel. This effects the fontsize of both the title and the axis, if any. Defaults to NULL, which means that the text size is automatically adjusted to the available space.

col.axis="white": Integer or character scalar. The font and line color for the y axis, if any.

col.border.title="white": Integer or character scalar. The border color for the title panels.

col.frame="lightgray": Integer or character scalar. The line color used for the panel frame, if frame==TRUE

col.grid="#808080": Integer or character scalar. Default line color for grid lines, both when type=="g" in DataTracks and when display parameter grid==TRUE.

col.line=NULL: Integer or character scalar. Default colors for plot lines. Usually the same as the global col parameter.

col.symbol=NULL: Integer or character scalar. Default colors for plot symbols. Usually the same as the global col parameter.

col.title="white" (Aliases: fontcolor.title): Integer or character scalar. The border color for the title panels

fill="lightgray": Integer or character scalar. Default fill color setting for all plotting elements, unless there is a more specific control defined elsewhere.

fontcolor="black": Integer or character scalar. The font color for all text, unless a more specific definition exists.

fontface=1: Integer or character scalar. The font face for all text, unless a more specific definition exists.

fontface.title=2: Integer or character scalar. The font face for the title panels.

fontfamily="sans": Integer or character scalar. The font family for all text, unless a more specific definition exists.

fontfamily.title="sans": Integer or character scalar. The font family for the title panels.

fontsize=12: Numeric scalar. The font size for all text, unless a more specific definition exists.

frame=FALSE: Boolean. Draw a frame around the track when plotting.

h=-1: Integer scalar. Parameter controlling the number of horizontal grid lines, see panel.grid for details.

lineheight=1: Numeric scalar. The font line height for all text, unless a more specific definition exists.

lty="solid": Numeric scalar. Default line type setting for all plotting elements, unless there is a more specific control defined elsewhere.

lty.grid="solid": Integer or character scalar. Default line type for grid lines, both when type=="g" in DataTracks and when display parameter grid==TRUE.

lwd=1: Numeric scalar. Default line width setting for all plotting elements, unless there is a more specific control defined elsewhere.

lwd.border.title=1: Integer scalar. The border width for the title panels.

lwd.grid=1: Numeric scalar. Default line width for grid lines, both when type=="g" in DataTracks and when display parameter grid==TRUE.

lwd.title=1: Integer scalar. The border width for the title panels

min.height=3: Numeric scalar. The minimum range height in pixels to display. All ranges are expanded to this size in order to avoid rendering issues. See collapsing for details.

min.width=1: Numeric scalar. The minimum range width in pixels to display. All ranges are expanded to this size in order to avoid rendering issues. See collapsing for details.

reverseStrand=FALSE: Logical scalar. Set up the plotting coordinates in 3' -> 5' direction if TRUE. This will effectively mirror the plot on the vertical axis.

rotation=0: The rotation angle for all text unless a more specific definiton exists.

rotation.title=90 (Aliases: rotation.title): The rotation angle for the text in the title panel. Even though this can be adjusted, the automatic resizing of the title panel will currently not work, so use at own risk.

showAxis=TRUE: Boolean controlling whether to plot a y axis (only applies to track types where axes are implemented).

showTitle=TRUE: Boolean controlling whether to plot a title panel. Although this can be set individually for each track, in multi-track plots as created by plotTracks there will still be an empty placeholder in case any of the other tracks include a title. The same holds true for axes. Note that the the title panel background color could be set to transparent in order to completely hide it.

v=-1: Integer scalar. Parameter controlling the number of vertical grid lines, see panel.grid for details.

Author(s)

Florian Hahne

See Also

DataTrack

DisplayPars

GdObject

GRanges

ImageMap

IRanges

NumericTrack

RangeTrack

collapsing

grouping

horizonplot

panel.bwplot

panel.grid

panel.loess

panel.xyplot

plotTracks

settings

Examples

## Object construction:

## An empty object
DataTrack()

## from individual arguments
dat <- matrix(runif(400), nrow=4)
dtTrack <- DataTrack(start=seq(1,1000, len=100), width=10, data=dat,
chromosome=1, genome="mm9", name="random data")

## from GRanges
library(GenomicRanges)
gr <- GRanges(seqnames="chr1", ranges=IRanges(seq(1,1000, len=100),
width=10))
values(gr) <- t(dat)
dtTrack <- DataTrack(range=gr, genome="mm9", name="random data")

## from IRanges
dtTrack <- DataTrack(range=ranges(gr), data=dat, genome="mm9",
name="random data", chromosome=1)

## from a data.frame
df <- as.data.frame(gr)
colnames(df)[1] <- "chromosome"
dtTrack <- DataTrack(range=df,  genome="mm9", name="random data")



## Plotting
plotTracks(dtTrack)

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

## Subsetting and splitting
subTrack <- subset(dtTrack, from=100, to=300)
length(subTrack)
subTrack[1:2,]
subTrack[,1:2]
split(dtTrack, rep(1:2, each=50))

## Accessors
start(dtTrack)
end(dtTrack)
width(dtTrack)
position(dtTrack)
width(subTrack) <- width(subTrack)-5

strand(dtTrack)
strand(subTrack) <- "-"

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

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

range(dtTrack)
ranges(dtTrack)

## Data
values(dtTrack)
score(dtTrack)

## coercion
as(dtTrack, "data.frame")

Gviz documentation built on March 16, 2021, 6:01 p.m.