Ex. 1.1: Parent Data

The simplest input format is a column containing the parent node of each individual node. (A node will only have one parent.) The root node will not have a parent, so a value of NA is used.

parent.only.tree <- SRCGrob(parent.only);

Ex. 1.2: Branch Lengths

It’s common to associate branch lengths with a the values of a particular variable (for example, PGA or SNVs). Up to two branch lengths can be specified. Including a length1 and/or length2 column will enable this branch scaling behaviour, and automatically add y-axis ticks and labels.

Multiple length values can be used together. All columns whose names contain length will be used. (For example, length1 and snv.length are both valid.) Multiple columns will result in multiple (distinctly coloured) parallel lines. Any branch length conflicts will be resolved automatically. For each branch, the next node will be placed at the end of the longest line.

branch.lengths.tree <- SRCGrob(branch.lengths);

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

grid.draw(branch.lengths.tree);

Ex. 1.3: Complex Trees

CEV provides several methods for refining the spacing and arrangement of a tree’s nodes. This is especially useful in complex trees, which often require more attention to avoid visual problems such as node collisions and uneven branch/level spacing. Here, we see a tree with many issues.

Consider this example tree.

Ex. 1.4: Styling the Tree

CEV gives the user control over numerous visual aspects of the tree. By specifying optional columns and values in the tree input data.frame, the user has individual control of the colour, width, and line type of each node, label border, and edge.

node.style.tree <- SRCGrob(node.style);

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

Ex. 1.5: Showing Cellular Prevalence

A cellular.prevalence column can also be added. These values must range between 0 and 1, and the sum of all child nodes must not be larger than their parent node’s value.

CP.tree <- SRCGrob(CP);

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

Ex. 1.6: Simplifying the Tree

Complex trees may benefit from simpler visual styles. For example, there may not be room to render the node ellipses. CEV provides node-by-node control with the draw.node column.

nodeless.tree <- SRCGrob(nodeless);

Ex. 6: Node Text

Each row must include a node ID for the text. Text will be stacked next to the specified node.

simple.text.tree <- SRCGrob(parent.only, simple.text.data);

grid.draw(simple.text.tree);

Ex. 7: Specifying Colour and Style

• An optional col column can be included to specify the colour of each text.
• A fontface column can be included to bold, italicize, etc. These values correspond to the standard R fontface values.
• NA values in each column will default to black and plain respectively.

full.text.tree <- SRCGrob(parent.only, simple.example$text);

grid.draw(full.text.tree);

Ex. 8: Plot Width with Horizontal Padding

Some plots require more or less horizontal padding between the x-axes and the tree itself. The horizontal.padding parameter scales the default padding proportionally. For example, horizontal.padding = -0.2 would reduce the padding by 20%.

padding.tree <- SRCGrob(
    branch.lengths,
    horizontal.padding = -0.8
    );

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

grid.draw(padding.tree);

Ex. 9: Branch Scaling

Branches are scaled automatically, but users can further scale each branch with the scale1 and scale2 parameters. These values scale each branch proportionally, so scale1 = 1.1 would make the first set of branch lengths 10% longer.

scaled.tree <- SRCGrob(
    branch.lengths,
    scale1 = 1.5,
    scale2 = 0.5
    );

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

grid.draw(scaled.tree);

Ex. 10: Plot Title

The main title of the plot is referred to as main in plot parameters. main sets the title text, main.cex sets the font size, and main.y is used to move the main title up if more space is required for the plot.

title.tree <- SRCGrob(
    parent.only,
    main = 'Example Plot'
    );

grid.draw(title.tree);

Ex. 11: Y-Axis

Ticks are placed automatically based on the plot size and the branch lengths.

Ex. 12: Axis Title

Axis titles are specified with the yaxis1.label and yaxis2.label parameters.

axis.title.tree <- SRCGrob(
    parent.only,
    yaxis1.label = 'SNVs',
    horizontal.padding = -0.6
    );

grid.draw(axis.title.tree);

Ex. 13: Axis Tick Placement

The default axis tick positions can be overridden with the yat parameter. This expects a list of vectors, each corresponding to the ticks on an x-axis.

xaxis1.ticks <- c(10, 20, 30, 35, 40);
xaxis2.ticks <- c(100, 250, 400);

yat.tree <- SRCGrob(
    branch.lengths,
    yat = list(
        xaxis1.ticks,
        xaxis2.ticks
        ),
    horizontal.padding = -0.4
    );

## Only the first 2 "length" columns will be used. More branch lengths will be supported in a future version.

## Warning in add.axes(clone.out, yaxis.position, scale1 = scale1, scale2 =
## scale2, : Missing second y-axis label

grid.draw(yat.tree);

Ex. 14: Normal

normal.tree <- SRCGrob(
    parent.only,
    add.normal = TRUE
    );

grid.draw(normal.tree);