"trackStyle"trackStyle-class.RdAn object of class "trackStyle" represents track style.
An object of class "track" bundles the genomic data to be
plotted together with the style used to draw it. A track is the basic
unit accepted by viewTracks; several of them are collected into
a trackList for a multi-panel figure.
# S4 method for class 'track'
seqlevels(x)
# S4 method for class 'track'
seqlevelsStyle(x)
# S4 method for class 'track'
seqlevelsStyle(x) <- value
# S4 method for class 'track'
show(object)
# S4 method for class 'track'
x$name
# S4 method for class 'track'
x$name <- value
# S3 method for class 'track'
.DollarNames(x, pattern = "")
# S3 method for class 'trackStyle'
.DollarNames(x, pattern = "")
setTrackStyleParam(ts, attr, value)
# S4 method for class 'track,character'
setTrackStyleParam(ts, attr, value)
setTrackXscaleParam(ts, attr, value)
# S4 method for class 'track,character'
setTrackXscaleParam(ts, attr, value)
setTrackYaxisParam(ts, attr, value)
# S4 method for class 'track,character'
setTrackYaxisParam(ts, attr, value)An object of class track with the modified style,
returned invisibly. The variable supplied as ts is updated as a side
effect.
An object of class track with the modified
xscale, returned invisibly. The variable supplied as ts is
updated as a side effect.
An object of class track with the modified
yaxis, returned invisibly. The variable supplied as ts is
updated as a side effect.
The validity method enforces the type-specific requirements summarised above;
the most common errors are a missing score or feature metadata
column, a lollipop range wider than one base, and a dat2 whose length
does not match dat for interaction data.
Note that dat and dat2 are plain GRanges objects, so the
seqlevel style of the track must match that of the other tracks and of the
plotting range. seqlevelsStyle and its replacement method are
defined for track and rename both dat and dat2 at once.
setTrackStyleParam changes one styling slot of the
trackStyle object held in ts@style. It accepts only the
slots that are plain values; the two compound slots have their own setters,
setTrackXscaleParam for xscale and
setTrackYaxisParam for yaxis. Passing any other name,
including "xscale" or "yaxis", raises an error.
Accepted values of attr:
tracktype"character". How the data is drawn. For
"data" tracks use "peak" (the default), "line",
"histogram" or "annotation", the last marking peak regions
rather than plotting their scores. For "interactionData" tracks use
"heatmap" or "link".
color"character" vector of colors. Give two values
when the track has both dat and dat2, the first for the
positive side and the second for the negative side of the baseline.
height"numeric" between 0 and 1, the fraction of the
figure given to this track. Note that trackList rewrites this
slot for every element it is given, so set it after building the list, not
before.
marginTop, marginBottom"numeric", space left
above and below the drawing region of the track, as a fraction of its
height. Defaults are 0 and 0.05.
ylim"numeric" of length 2 fixing the y-axis range.
Useful for making two tracks directly comparable, since the range is
otherwise taken from the data in the current view.
ylabpos"character", one of "left",
"right", "topleft", "bottomleft", "topright",
"bottomright", "abovebaseline", "underbaseline" or
"none"; for gene-type tracks also "upstream" or
"downstream".
ylablas"numeric" in {0, 1, 2, 3}, the rotation of
the y label. See par:las.
ylabgp"list" of graphical parameters for the y label,
converted to gpar, e.g. list(cex=.8, col="gray30").
breaks"numeric" breaks for the color key of
interaction data.
NAcolor"character", the color used for missing cells
of an interaction heatmap. Default "white".
ysplit"numeric", where to split the y region for
back-to-back interaction plots. Default 0.5 splits it evenly; it has no
effect on other layouts.
The value is assigned with check = TRUE, so the validity method of
trackStyle runs on every call and an out-of-range value (an
unknown tracktype, an ylablas outside 0:3, an unrecognized
ylabpos) fails immediately rather than at plotting time.
setTrackXscaleParam changes the x-scale bar of a track, stored as an
xscale object at ts@style@xscale. The x-scale bar is a
short horizontal ruler drawn inside the track's own panel, independent of
the shared genomic x-axis of the whole figure, typically used to show a
distance such as "1K" next to a zoomed-in feature.
attr can be any slot of xscale, or the convenience
name "position":
from, toObjects of class pos, the two
endpoints of the scale bar. Because these are pos objects rather
than bare numbers, setting them directly means constructing the object
yourself, e.g. new("pos", x=12345678, y=0.5, unit="native") for a
point given in native (genomic) coordinates, or a fraction with
unit="npc" for a position relative to the panel. Most callers will
find attr="position" (below) more convenient than setting
from and to separately, since it keeps them centered and in
sync with the label.
label"character", the text drawn on the scale bar,
e.g. "500 bp". Set directly this is used verbatim.
gp"list" of graphical parameters for the scale bar
and its label, converted to gpar, e.g.
list(cex=.5, col="black", lwd=2).
draw"logical", whether the scale bar is drawn at
all. Default FALSE; set to TRUE even from/to
(or position) have been set, the scale bar will show.
positionA shortcut that sets from, to and
label together from a single scale length, instead of requiring two
pos objects. value must be a "list" with named
elements x, y and label:
x, y — the native-coordinate of the bar
(genomic position and track-relative y, respectively). The bar is
drawn symmetrically about this point.
label — the width the bar should represent.
A label that cannot be coerced to numeric (NA after
as.numeric) is rejected before any slot is touched.
As with the other slots of xscale, updated values are assigned
with check = TRUE, so the pos validity method (checking
the unit string) still applies when from/to are set
through "position".
setTrackYaxisParam changes the y-axis of a track, stored as a
yaxisStyle object at ts@style@yaxis. This is the axis
drawn alongside the track's own data panel (score, coverage, etc.), separate
from the shared genomic x-axis of the whole figure.
Accepted values of attr, all slots of yaxisStyle:
at"numeric" vector of y-values at which tick marks
are drawn, e.g. c(0, 25, 50). If left at its default
(numeric(0)), tick positions are chosen automatically from the
plotted range.
label"logical", whether the numeric value of each
tick in at is printed next to it. Default FALSE, i.e. ticks
are drawn without their values; set to TRUE to show them.
gp"list" of graphical parameters for the axis line,
ticks and labels, converted to gpar, e.g.
list(cex=.6, col="blue", lwd=1.5).
draw"logical", whether the y-axis is drawn at all.
Default TRUE.
main"logical", which side of the panel the axis is
drawn on: TRUE (the default) draws it on the left of the track,
FALSE on the right. Useful for telling apart the axes of two
adjacent or back-to-back tracks at a glance.
Any other value of attr, including "xscale" or a slot name
belonging to trackStyle itself (like "color" or
"height"), is rejected, use setTrackStyleParam for the
plain style slots and setTrackXscaleParam for the x-scale bar.
Values are assigned with check = TRUE, so an ill-typed value (for
example a non-logical passed to "draw") fails immediately rather than
at plotting time.
tracktype"character" track type, could be peak,
line, histogram, or annotation.
Default is "peak". "annotation" is used to mark the peak regions.
For interaction data,
it could be "heatmap" or "link".
color"character" track color. If the track has dat and dat2 slot,
it should have two values.
NAcolor"character" NA color for interactionData.
breaks"numeric" breaks for color keys of interactionData.
height"numeric" track height. It should be a value between 0 and 1
marginTop"numeric" track top margin
marginBottom"numeric" track bottom margin
xscaleobject of xscale, describe the details of x-scale
yaxisobject of yaxisStyle, describe the details of y-axis
ylim"numeric" y-axis range
ylabpos"character", ylable postion, ylabpos should
be 'left', 'right', 'topleft', 'bottomleft', 'topright', 'bottomright',
'abovebaseline', 'underbaseline', or 'none'.
For gene type track, it also could be 'upstream' or 'downstream'
ylablas"numeric" y lable direction. It should
be a integer 0-3. See par:las
ylabgpA "list" object, It will convert to an object of
class gpar. This is basically a list of graphical
parameter settings of y-label.
ysplitA "numeric" to split y plot region for interaction data.
Default is 0.5, which will split the region half to half. It will only work
for back to back plot.
datObject of class GRanges,
the primary data of the track. The metadata columns it must carry depend on
type (see ‘Details’): coverage-like tracks
("data", "scSeq"), "lollipopData" and
"interactionData" require a score column, whereas
"gene" and "transcript" tracks require a feature column.
dat2Object of class GRanges,
the optional second data set of the track; leave it as a zero-length
GRanges when unused. Its meaning depends on type:
for "data", "scSeq" and "lollipopData" tracks it
is drawn back-to-back with dat: dat above the baseline and
dat2 below it as -1 * score, which is the usual way to
compare two samples or the two strands of one sample in a single panel;
for "interactionData" it holds the second anchor of each
interaction, so it must either be the same length as dat (anchors
matched element-wise) or carry a target metadata column.
When supplied it must contain a score column, and for lollipop data
every range must have width 1, exactly as for dat.
typeThe type of track, one of:
"data"continuous or interval scores — coverage, signal,
peaks. Drawn as a peak, line or histogram depending on
style@tracktype.
"gene"gene models. dat must have a feature
column describing each range (for example "exon", "CDS",
"utr5", "utr3").
"transcript"transcript models; same feature
requirement as "gene", but isoforms are drawn on separate rows.
"scSeq"single-cell signal. Validated like "data",
i.e. a format and a numeric score are required.
"lollipopData"point features such as variants or
modification sites. Every range in dat (and dat2) must have
width 1; ranges wider than one base are rejected.
"interactionData"chromatin interactions, for example from
Hi-C or 4C. Drawn as a heatmap or as arcs according to
style@tracktype.
formatThe format the data was imported from: "BED",
"bedGraph", "WIG", "BigWig" or "BAM". It is
required, and must be a single string, for "data" and "scSeq"
tracks; other types ignore it. For every format except "WIG" the
score column must be numeric or integer. "WIG" is
the exception: because a WIG file has no fixed step boundaries until it is
plotted, score is stored as a
CompressedCharacterList and is
converted on the fly — see importScore.
styleObject of class trackStyle controlling color,
height, margins, y-axis, x-scale and the drawing mode. Do not assign to its
slots directly; use setTrackStyleParam,
setTrackXscaleParam and setTrackYaxisParam, which
validate the value and update the object in the calling frame.
nameunused yet
Unlike most R functions, setTrackStyleParam modifies its first
argument in place: it assigns the updated track back to the variable that was
passed in, so setTrackStyleParam(fox2, "color", "red") is enough and
fox2 <- setTrackStyleParam(...) is not needed. This works only when
ts is given as a name or a subsettable expression that can be assigned
to; calling it on a temporary value, for example
setTrackStyleParam(importScore(f), "color", "red"), updates nothing
the caller can see. Inside lapply and friends the assignment targets
the loop variable, which is discarded, so use the returned object there
instead — it is returned invisibly and carries the same change.
Like setTrackStyleParam, this method assigns the updated track
back to the variable passed as ts in the caller's environment, so
setTrackXscaleParam(fox2, "draw", TRUE) is sufficient and the result
need not be re-assigned. It is also returned invisibly for use in contexts
(such as lapply) where the calling-frame assignment has no visible
target.
Like setTrackStyleParam and setTrackXscaleParam,
this method assigns the updated track back to the variable passed as
ts in the caller's environment, so
setTrackYaxisParam(fox2, "draw", FALSE) is sufficient on its own. It
is also returned invisibly for use in contexts, such as lapply, where
that calling-frame assignment has no visible target.
Please try to use importScore and importBam to
generate the object.
setTrackXscaleParam, setTrackYaxisParam,
trackStyle
xscale, pos,
setTrackStyleParam,
setTrackYaxisParam
yaxisStyle, setTrackStyleParam,
setTrackXscaleParam
extdata <- system.file("extdata", package="trackViewer",
mustWork=TRUE)
fox2 <- importScore(file.path(extdata, "fox2.bed"), format="BED")
setTrackStyleParam(fox2, "color", c("red","green"))
setTrackXscaleParam(fox2, "gp", list(cex=.5))
setTrackYaxisParam(fox2, "gp", list(col="blue"))
fox2$dat <- GRanges(score=numeric(0))
## inspect and change the style
fox2$type
#> [1] "data"
fox2$style$tracktype
#> [1] "peak"
setTrackStyleParam(fox2, "tracktype", "histogram")
setTrackStyleParam(fox2, "height", .2)
extdata <- system.file("extdata", package="trackViewer", mustWork=TRUE)
fox2 <- importScore(file.path(extdata, "fox2.bed"), format="BED")
## the track is updated in place; no re-assignment needed
setTrackStyleParam(fox2, "tracktype", "histogram")
setTrackStyleParam(fox2, "color", c("#E69F00", "#56B4E9"))
setTrackStyleParam(fox2, "ylim", c(0, 50))
setTrackStyleParam(fox2, "ylabpos", "topleft")
setTrackStyleParam(fox2, "ylabgp", list(cex=.8, col="gray30"))
fox2$style$tracktype
#> [1] "histogram"
## inside lapply, use the returned value
trs <- lapply(list(a=fox2, b=fox2), function(.ele){
setTrackStyleParam(.ele, "height", .25)
})
## invalid values are rejected straight away
if (FALSE) { # \dontrun{
setTrackStyleParam(fox2, "ylablas", 5) # must be 0:3
setTrackStyleParam(fox2, "xscale", list()) # use setTrackXscaleParam
} # }
extdata <- system.file("extdata", package="trackViewer", mustWork=TRUE)
fox2 <- importScore(file.path(extdata, "fox2.bed"), format="BED")
## simplest way: give a centre point and a width in bases
setTrackXscaleParam(fox2, "position",
list(x=122929675, y=4, label=500))
setTrackXscaleParam(fox2, "draw", TRUE)
## style the bar itself
setTrackXscaleParam(fox2, "gp", list(cex=.5, col="gray30"))
## equivalent, done by hand with explicit pos objects
setTrackXscaleParam(fox2, "from",
new("pos", x=122929675-500, y=4, unit="native"))
#> Found more than one class "pos" in cache; using the first, from namespace 'trackViewer'
#> Also defined by ‘motifStack’
setTrackXscaleParam(fox2, "to",
new("pos", x=122929675+500, y=4, unit="native"))
#> Found more than one class "pos" in cache; using the first, from namespace 'trackViewer'
#> Also defined by ‘motifStack’
setTrackXscaleParam(fox2, "label", "1K")
if (FALSE) { # \dontrun{
## rejected: label can't be parsed as a number
setTrackXscaleParam(fox2, "position",
list(x=122929675, y=4, label="five hundred"))
} # }
extdata <- system.file("extdata", package="trackViewer", mustWork=TRUE)
fox2 <- importScore(file.path(extdata, "fox2.bed"), format="BED")
## show tick values at chosen positions
setTrackYaxisParam(fox2, "at", c(0, 25, 50))
setTrackYaxisParam(fox2, "label", TRUE)
## style the axis and move it to the right-hand side
setTrackYaxisParam(fox2, "gp", list(cex=.6, col="blue"))
setTrackYaxisParam(fox2, "main", FALSE)
## hide the axis entirely
setTrackYaxisParam(fox2, "draw", FALSE)
if (FALSE) { # \dontrun{
## rejected: "color" belongs to trackStyle, not yaxisStyle
setTrackYaxisParam(fox2, "color", "red")
} # }