PhyloPlots.jl
PhyloPlots is a Julia package to plot phylogenetic trees and networks.
PhyloNetworks objects can be displayed through R via RCall.
Click here to go to the documentation for the latest stable release.'; + div.appendChild(closer); + document.body.appendChild(div); +} + +if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", maybeAddWarning); +} else { + maybeAddWarning(); +} diff --git a/v1.0.1/index.html b/v1.0.1/index.html new file mode 100644 index 0000000..e684a49 --- /dev/null +++ b/v1.0.1/index.html @@ -0,0 +1,2 @@ + +
Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
internal documentation
Documentation for PhyloPlots's internal functions. Those functions are not exported, but can still be used (like: PhyloPlots.foo() for a function named foo()).
index
PhyloPlots.check_nodedataframePhyloPlots.edgenode_coordinatesPhyloPlots.prepare_edgedataframePhyloPlots.prepare_nodedataframePhyloPlots.rexport
functions
PhyloPlots.check_nodedataframe — Methodcheck_nodedataframe(net, nodelabel)Check data frame for node annotations:
- check that the data has at least 2 columns (if it has any)
- check that the first column has integers (to serve as node numbers)
- remove rows with no node numbers
- warning if some node numbers in the data are not in the network.
PhyloPlots.edgenode_coordinates — Methodedgenode_coordinates(net, useedgelength::Bool, useSimpleHybridLines::Bool)Calculate coordinates for plotting later with Gadfly or RCall.
Actually modifies some (minor) attributes of the network, as it calls directEdges! and preorder!.
output: tuple with the following elements, in which the order of nodes corresponds to the order in net.node, and the order of edges corresponds to that in net.edge (filtered to minor edges as needed).
edge_xB: x coordinate for the Beginning and ...edge_xE: ... End of each edge, in the same order as innet.edgeedge_yB: y coordinate for edges, Begin ...edge_yE: ... and End. Each major edge is drawn as a single horizontal line. Minor hybrid edges are drawn as: a single diagonal segment ifuseSimpleHybridLinesis true, or as 2 connected segments otherwise: one horizontal (whose length on the x axis can be used to represent the edge length), and the other diagonal to connect the horizontal segment to the child node.edge_*contains the coordinates for the horizontal segment only, which is reduced to a single point (Begin = End) when using "SimpleHybridLines".minoredge_*(see below) contains information for the diagonal segment. Agreed,edge_yB=edge_yEalways (relic from before v0.3: no minoredge output back then, and simple diagonal lines only)node_x: x and ...node_y: ... y coordinate at the middle of the vertical bar that represents a node. The (or each) parent edge of the node connects to this middle point, but the node itself is drawn as a vertical bar connected to all it children edges. order: same as innet.nodenode_yB: y coordinates of the Beginning and the ...node_yE: ... End of the vertical bar representing each node. The x coordinate (Begin & End) of the end points of the vertical bar is the same as that of the mid-point, given bynode_x.minoredge_xB: x coordinate for the Beginning and ...minoredge_xE: ... End of the diagonal segment of each minor hybrid edge, in the same order as infilter(e -> !e.isMajor, net.edge).minoredge_yB: y coordinate for the beginning and ...minoredge_yE: ... end of the diagonal segment of each minor hybrid edge.
13-16. xmin, xmax, ymin, ymax: ranges for the x and y axes.
PhyloPlots.prepare_edgedataframe — Methodprepare_edgedataframe(net, edgelabel::DataFrame, style::Symbol,
+ edge_xB, edge_xE, edge_yB, edge_yE,
+ minoredge_xB, minoredge_xE, minoredge_yB, minoredge_yE)Check data frame for edge annotation. edge_*: Float64 vectors giving the coordinates for the beginning and end of edges. Return data frame with columns
- x, y: coordinates on the plots
- len: node name
- gam: gamma (inheritance value)
- num: node number
- lab: node label
- hyb: is hybrid?
- min: is minor?
PhyloPlots.prepare_nodedataframe — Methodprepare_nodedataframe(net, nodelabel::DataFrame,
+ shownodenumber::Bool, shownodename::Bool, labelnodes::Bool,
+ node_x, node_y)Make data frame for node annotation. node_* should be Float64 vectors. nodelabel should have columns as required by check_nodedataframe. shownodename is to show the name of internal nodes. Leaf names are always included.
Columns of output data frame:
- x, y: coordinates on the plots (from
node_*) - name: node name
- num: node number
- lab: node label
- lea: is leaf?
PhyloPlots.rexport — Methodrexport(net::HybridNetwork; maintree=false, useedgelength=true)Create an RObject of class phylo (and evonet depending on the number of hybridizations) recognized by the ape library in R (S3 object). This RObject can be evaluated using the tools available in the ape library in R. For example, we can visualize the network using ape's plot function.
not exported: sexp is the best way to go.
Arguments
- useedgelength: if true, export edge lengths from
net. - maintree: if true, minor hybrid edges are omitted.
Examples
julia> net = readTopology("(((A,(B)#H1:::0.9),(C,#H1:::0.1)),D);");
+
+julia> phy = PhyloPlots.rexport(net)
+RObject{VecSxp}
+
+ Evolutionary network with 1 reticulation
+
+ --- Base tree ---
+Phylogenetic tree with 4 tips and 5 internal nodes.
+
+Tip labels:
+ A, B, C, D
+
+Rooted; no branch lengths.
+
+julia> using RCall
+
+julia> R"library(ape)";
+
+julia> phy
+RObject{VecSxp}
+
+ Evolutionary network with 1 reticulation
+
+ --- Base tree ---
+Phylogenetic tree with 4 tips and 5 internal nodes.
+
+Tip labels:
+ A, B, C, D
+
+Rooted; no branch lengths.
+
+R> phy
+
+ Evolutionary network with 1 reticulation
+
+ --- Base tree ---
+Phylogenetic tree with 4 tips and 5 internal nodes.
+
+Tip labels:
+ A, B, C, D
+
+Rooted; no branch lengths.
+
+R> str(phy)
+List of 5
+ $ Nnode : int 5
+ $ edge : int [1:8, 1:2] 5 5 6 6 7 8 8 9 6 4 ...
+ $ tip.label : chr [1:4] "A" "B" "C" "D"
+ $ reticulation : int [1, 1:2] 7 9
+ $ reticulation.gamma: num 0.1
+ - attr(*, "class")= chr [1:2] "evonet" "phylo"Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
public documentation
Documentation for PhyloPlots's public (exported) functions.
index
functions
PhyloPlots.plot — Methodplot(net::HybridNetwork)Plot a network using R graphics. Optional arguments are listed below.
lines forming the network:
useedgelength = false: if true, the tree edges and major hybrid edges are drawn proportionally to their length. Minor hybrid edges are not, however. Note that edge lengths in coalescent units may scale very poorly with time.style = :fulltree: symbol indicating the style of the diagram:majortreewill simply draw minor edges onto the major tree.:fulltreewill draw minor edges as their own branches in the tree, in the same style used by icytree. This is useful for overlapping or confusing networks.
arrowlen: the length of the arrow tips in the full tree style. ifstyle = :fulltree, thenarrowlen = 0.2. otherwise,arrowlen = 0, which makes the arrows appear as segments.edgewidth=1: width of horizontal (not diagonal) edges. To vary them, use a dictionary to map the number of each edge to its desired witdth.xlim,ylim: array of 2 values, to determine the axes limits
tip annotations:
showtiplabel = true: if true, taxon labels (names) are shown.tipoffset = 0.0: to offset tip labelstipcex=1.0: character expansion for tip and internal node names
nodes & edges annotations:
shownodelabel = false: if true, internal nodes are labelled with their names. Useful for hybrid nodes, which do have tags like 'H1'.shownodenumber = false: if true, nodes are labelled with the number used internally.showedgenumber = false: if true, edges are labelled with the number used internally.showedgelength = false: if true, edges are labelled with their length (above)showgamma = false: if true, hybrid edges are labelled with their heritability (below)edgelabel = DataFrame(): dataframe with two columns: the first with edge numbers, the second with labels (like bootstrap values) to annotate edges. empty by default.nodelabel = DataFrame(): dataframe with two columns: the first with node numbers, the second with labels (like bootstrap values for hybrid relationships) to annotate nodes. empty by default.nodecex=1.0: character expansion for labels in thenodelabeldata frameedgecex=1.0: character expansion for labels in theedgelabeldata frame
colors:
edgecolor = "black": color for tree edges.majorhybridedgecolor = "deepskyblue4": color for major hybrid edgesminorhybridedgecolor = "deepskyblue": color for minor hybrid edgesedgenumbercolor = "grey": color for edge numbersedgelabelcolor = "black": color for labels in theedgelabeldata framenodelabelcolor = "black": color for labels in thenodelabeldata frame
Output the following tuple, that can be used for downstream plot annotations with RCall:
(xmin, xmax, ymin, ymax,
+ node_x, node_y, node_yB, node_yE,
+ edge_xB, edge_xE, edge_yB, edge_yE,
+ ndf, edf)xmin: minimum x value of the plotxmax: maximum x value of the plotymin: minimum y value of the plotymax: maximum y value of the plotnode_x: x values of the nodes in net.node in their respective ordernode_y: y values of the nodesnode_yB: y value of the beginning of the verticle barnode_yE: y value of the end of the verticle baredge_xB: x value of the beginning of the edges in net.edge in their respective orderedge_xE: x value of the end of the edgesedge_yB: y value of the beginning of the edgesedge_yE: y value of the end of the edgesndf: node data frame: see section Adding labels for moreedf: edge data frame
Note that plot actually modifies some (minor) attributes of the network, as it calls directEdges! and preorder!.
If hybrid edges cross tree and major edges, you may choose to rotate some tree edges to eliminate crossing edges, using rotate! (in PhyloNetworks).
Alternative: a tree or network can be exported with sexp and then displayed with R's "plot" and all its options.
PhyloPlots.plot — Methodplot(model::TwoBinaryTraitSubstitutionModel)Display substitution rates for a trait evolution model for two possibly dependent binary traits; using R via RCall. Adapted from fitPagel functions found in the R package phytools.
Examples
julia> using PhyloNetworks
+
+julia> m = TwoBinaryTraitSubstitutionModel([2.0,1.2,1.1,2.2,1.0,3.1,2.0,1.1],
+ ["carnivory", "noncarnivory", "wet", "dry"])
+Substitution model for 2 binary traits, with rate matrix:
+ carnivory-wet carnivory-dry noncarnivory-wet noncarnivory-dry
+ carnivory-wet * 1.0000 2.0000 0.0000
+ carnivory-dry 3.1000 * 0.0000 1.1000
+ noncarnivory-wet 1.2000 0.0000 * 2.0000
+ noncarnivory-dry 0.0000 2.2000 1.1000 *
+
+julia> plot(m);RCall.sexp — Methodfunction sexp(net::HybridNetwork)Export a HybridNework object to the R language as either phylo or evonet object (depending on degree of hybridization) recognized by the R package ape. Used by the $object syntax and by @rput to use a Julia object in R: see the examples below. Makes it easy to plot a Julia tree or network using plotting facilities in R.
code inspired from Phylo.jl
Examples
julia> using RCall
+julia> using PhyloNetworks
+julia> net = readTopology("(((A:.2,(B:.1)#H1:.1::0.9):.1,(C:.11,#H1:.01::0.1):.19):.1,D:.4);");
+R> library(ape); # type $ to switch from julia to R
+R> $net
+
+ Evolutionary network with 1 reticulation
+
+ --- Base tree ---
+Phylogenetic tree with 4 tips and 5 internal nodes.
+
+Tip labels:
+ A, B, C, D
+
+Rooted; includes branch lengths.
+
+julia> @rput net; # press the delete key to switch from R back to julia
+
+R> net
+
+ Evolutionary network with 1 reticulation
+
+ --- Base tree ---
+Phylogenetic tree with 4 tips and 5 internal nodes.
+
+Tip labels:
+ A, B, C, D
+
+Rooted; includes branch lengths.
+
+R> str(net)
+List of 7
+ $ edge : int [1:8, 1:2] 5 5 6 6 7 8 8 9 6 4 ...
+ $ reticulation.length: num 0.01
+ $ Nnode : int 5
+ $ edge.length : num [1:8] 0.1 0.4 0.1 0.19 0.11 0.2 0.1 0.1
+ $ reticulation : int [1, 1:2] 7 9
+ $ reticulation.gamma : num 0.1
+ $ tip.label : chr [1:4] "A" "B" "C" "D"
+ - attr(*, "class")= chr [1:2] "evonet" "phylo"
+
+R> plot(net)Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
Adding data
In this section, we look over ways of adding extra information or data to a plot.
Adding labels
For demonstration purposes, we walk through the process of adding labels to edges, with notes on how to do the same for nodes in parentheses.
To add labels on edges (or nodes), we need to know their numbers. We can use the showedgenumber = true option for this. (Use shownodenumber = true to see node numbers).
plot(net, showedgenumber=true);
+plot(net, showedgenumber=true, edgenumbercolor="red4");
Edge numbers are shown in grey by default (to avoid mistaking them for edge lengths), but their color can be adjusted as shown above.
We then need to define a DataFrame with two columns of information: the number of the edge (or node), and the label that goes on it, like this:
| number | label |
|---|---|
| 1 | "edge number 1" |
| 2 | "edge # 2" |
After including the DataFrames package, we can define it as so:
julia> using DataFramesjulia> DataFrame(number=[1,2], label=["edge number 1","edge # 2"])2×2 DataFrame + Row │ number label + │ Int64 String +─────┼─────────────────────── + 1 │ 1 edge number 1 + 2 │ 2 edge # 2
Using this data frame as input to the edgelabel option (nodelabel for nodes) puts the text on the correct edges:
plot(net, edgelabel=DataFrame(number = [1,2],
+ label = ["edge number 1", "edge # 2"]),
+ edgelabelcolor="orangered", edgecex=[0.9,1.1]);
Adding other annotations using R
We can use the return values of plot to get information on the coordinates of different elements of the plot. Using this, we can add any other information we want.
The plot function returns the following tuple:
(xmin, xmax, ymin, ymax,
+ node_x, node_y, node_yB, node_yE,
+ edge_xB, edge_xE, edge_yB, edge_yE,
+ nodedataframe, edgedataframe)See the documentation for descriptions of these elements: plot
Side clade bars example
Here's example code that adds bars to denote clades in the margin:
net = readTopology("(((((((1,2),3),4),5),(6,7)),(8,9)),10);");
+plot(net, xlim=(1,10))
+using RCall # to send any R command, to make further plot modifications
+R"segments"([9, 9, 9], [0.8, 7.8, 9.8], [9, 9, 9], [7.2, 9.2, 10.2])
+R"text"([9.5, 9.5, 9.5], [4, 8.5, 10], ["C", "B", "A"])
Let's break this down step by step. First, we read the topology, and plot the graph normally. plot actually returns a value, from which we can get useful information. Below, we store the plot output in res, then check its first two values because they contain the default range of the x axis; xmin and xmax.
res = plot(net);
+res[1:2](0.29999999999999993, 8.77)Looking at xmin and xmax returned by default, we can see that the x range is about (0.3, 9). To give us extra space to work with, we can set xlim to (0.3,10), forcing the range to be wider on the right, for annotations. We can also see that in this case there is some extra white space on the left, so that we can increase xmin a little bit, finally settling on xlim=(1,10).
plot(net, xlim=(1, 10));Knowing the coordinates, we can now add more information to the plot through RCall. For this, I use the R functions segments and text to add side bars with text on them.
using RCall # add (install) the RCall package prior to 'using' it
+R"segments"([9, 9, 9], [0.8, 7.8, 9.8], [9, 9, 9], [7.2, 9.2, 10.2])
+R"text"([9.5, 9.5, 9.5], [4, 8.5, 10], ["C", "B", "A"])Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
Better edges
Different hybrid edge styles
We can use the style option to visualize minor hybrid edges as simple lines, unlike the icytree style visualization. style is by default :fulltree, but by switching it to :majortree, we can draw minor hybrid edges as diagonal lines.
plot(net, style=:majortree);
Using edge lengths
We can use useedgelength=true to draw a plot that uses the network's edge lengths to determine the lengths of the lines. For this, we'll use a network that has branch lengths:
net = readTopology("(A:3.3,((B:1.5,#H1:0.5):1.5,((C:1)#H1:1.8,D:1.1):.2):0.3);")
I used a DataFrame (not shown) to add the label "N" to the plot. For more on this, see the Adding labels section.
If branch lengths represent time, D could represent a fossil, or a virus strain sequenced a year before the others. Seeing this visually is the advantage of useedgelength=true.
This network happens to be time consistent, because the distance along the time (x) axis from node N to the hybrid node H1 is the same both ways.
A network is time-consistent if all the paths between 2 given nodes all have the same length. Time inconsistency can occur when branch lengths are not measured in calendar time, such as if branch lengths are in substitutions per site (some paths might evolve with more substitutions than others), or in number of generations (some lineages might have 1 generation per year, others more or fewer generations per year), or in coalescent units (number of generations / effective population size).
A time-consistent network may be ultrametric (the distance between the root and the tips is the same across all tips), or not like the network above.
Time-inconsistent networks like these ones below might cause confusion:
net1 = readTopology("(A:3.3,((B:1.5,#H1:1.2):1.5,((C:1.8)#H1:1,D:1.1):.2):0.3);");
+net2 = readTopology("(A:3.3,((B:1.5,#H1:0.2):1.5,((C:1)#H1:1.8,D:1.1):.2):0.3);");
It may be useful to consider using style=:majortree if it causes too much confusion, since the :majortree style doesn't visually represent minor edge lengths. Because of this, I used the showedgelength=true option to see the information anyway.
R"layout"([1 2])
+plot(net1, useedgelength=true, style = :majortree, showedgelength=true, arrowlen=0.1);
+plot(net2, useedgelength=true, style = :majortree, showedgelength=true, arrowlen=0.1);
I also used the arrowlen=0.1 option to show the arrow tips to show the direction of minor edges, which are hidden by default when using the style=:majortree option.
Varying edge widths
We can vary edge widths to show population sizes for example. First we need to map each edge number to the desired width for that edge. We do this with a dictionary.
julia> using RCall # to send any command to R, to modify the plotjulia> R"par"(mar=[.1,.1,.1,.1]); R"layout"([1 2]);julia> plot(net1, showedgenumber=true);julia> R"mtext"("edge numbers, used\nas keys in edgewidth", side=1, line=-1);julia> log_populationsize = Dict(e.number => log10(1_000) for e in net1.edge); # pop size on log scalejulia> log_populationsize[9] = log10(100_000); # larger populations on edges 9 and 1julia> log_populationsize[1] = log10(100_000);julia> log_populationsizeDict{Int64, Float64} with 9 entries: + 5 => 3.0 + 4 => 3.0 + 6 => 3.0 + 7 => 3.0 + 2 => 3.0 + 9 => 5.0 + 8 => 3.0 + 3 => 3.0 + 1 => 5.0julia> plot(net1, edgewidth=log_populationsize);
Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
Getting started
To demonstrate, we will plot the simple network: (A,((B,#H1),(C,(D)#H1)));
To start plotting, use the packages:
julia> using PhyloNetworksjulia> using PhyloPlots
Then read the topology
julia> net = readTopology("(A,((B,#H1),(C,(D)#H1)));")HybridNetwork, Rooted Network +9 edges +9 nodes: 4 tips, 1 hybrid nodes, 4 internal tree nodes. +tip labels: A, B, C, D +(A,((B,#H1),(C,(D)#H1)));
and call plot, as shown below.
plot(net);
For the function's full documentation, see here: plot.
Compared to v0.3, v1 does not support the Gadfly-based plots, and uses small-case-only argument names.
The v0.3 syntax plot(net, :R; ...) still works in v1.0 but is deprecated, and will be removed in a future release. For example, you can still use plot(net, :R; showNodeNumber=true), but you should instead start using plot(net; shownodenumber=true).
Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
Installation
For information on how to install Julia and PhyloNetworks, see here. PhyloPlots depends on PhyloNetworks, and has further dependencies like RCall.
To install PhyloPlots in the Julia REPL, enter package mode with ], and:
add PhyloPlotsOr in julian mode:
using Pkg
+Pkg.add("PhyloPlots")Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.
Untangling the network
This plot may not be the easiest to read, as the hybrid edge crosses over C's edge:
To fix this, we can to rotate C and D's edges around their parent node.
First we need to know the number of this parent node. By showing node numbers with the shownodenumber = true option, we can find the number of the node whose child edges we should rotate.
plot(net, shownodenumber=true);
As we can see, rotating edges around node -5 will make for a prettier network.
rotate!(net, -5)
+plot(net)
This may seem unnecessary for a small network as shown, but it is a useful tool for plotting large networks.
Settings
This document was generated with Documenter.jl version 1.4.1 on Thursday 16 May 2024. Using Julia version 1.10.3.