diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 4cf3c41..9333c8a 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-10T15:09:14","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.2","generation_timestamp":"2024-12-10T22:29:36","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 25e2d23..81b4b36 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -home · PhyloPlots.jl
GitHub

PhyloPlots.jl

PhyloPlots is a Julia package to plot phylogenetic trees and networks.

PhyloNetworks objects can be displayed through R via RCall.

manual outline

library outline

functions

+home · PhyloPlots.jl
GitHub

PhyloPlots.jl

PhyloPlots is a Julia package to plot phylogenetic trees and networks.

PhyloNetworks objects can be displayed through R via RCall.

manual outline

library outline

functions

diff --git a/dev/lib/internals/index.html b/dev/lib/internals/index.html index 64efda1..975539e 100644 --- a/dev/lib/internals/index.html +++ b/dev/lib/internals/index.html @@ -1,9 +1,9 @@ -internals · PhyloPlots.jl
GitHub

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

functions

PhyloPlots.check_nodedataframe — Method
check_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.
source
PhyloPlots.edgenode_coordinates — Method
edgenode_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).

  1. edge_xB: x coordinate for the Beginning and ...
  2. edge_xE: ... End of each edge, in the same order as in net.edge
  3. edge_yB: y coordinate for edges, Begin ...
  4. edge_yE: ... and End. Each major edge is drawn as a single horizontal line. Minor hybrid edges are drawn as: a single diagonal segment if useSimpleHybridLines is 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_yE always (relic from before v0.3: no minoredge output back then, and simple diagonal lines only)
  5. node_x: x and ...
  6. 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 in net.node
  7. node_yB: y coordinates of the Beginning and the ...
  8. 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 by node_x.
  9. minoredge_xB: x coordinate for the Beginning and ...
  10. minoredge_xE: ... End of the diagonal segment of each minor hybrid edge, in the same order as in filter(e -> !e.ismajor, net.edge).
  11. minoredge_yB: y coordinate for the beginning and ...
  12. 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.

source
PhyloPlots.prepare_edgedataframe — Method
prepare_edgedataframe(net, edgelabel::DataFrame, style::Symbol,
+internals · PhyloPlots.jl
GitHub
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
functions
PhyloPlots.check_nodedataframe — Method
check_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.
source
PhyloPlots.edgenode_coordinates — Method
edgenode_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).
  1. edge_xB: x coordinate for the Beginning and ...
  2. edge_xE: ...  End of each edge, in the same order as in net.edge
  3. edge_yB: y coordinate for edges, Begin ...
  4. edge_yE: ... and End. Each major edge is drawn as a single horizontal line. Minor hybrid edges are drawn as: a single diagonal segment if useSimpleHybridLines is 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_yE always (relic from before v0.3: no minoredge output back then, and simple diagonal lines only)
  5. node_x: x and ...
  6. 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 in net.node
  7. node_yB: y coordinates of the Beginning and the ...
  8. 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 by node_x.
  9. minoredge_xB: x coordinate for the Beginning and ...
  10. minoredge_xE: ... End of the diagonal segment of each minor hybrid edge, in the same order as in filter(e -> !e.ismajor, net.edge).
  11. minoredge_yB: y coordinate for the beginning and ...
  12. 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.
source
PhyloPlots.prepare_edgedataframe — Method
prepare_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?
source
PhyloPlots.prepare_nodedataframe — Method
prepare_nodedataframe(net, nodelabel::DataFrame,
+    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?
source
PhyloPlots.prepare_nodedataframe — Method
prepare_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?
source
PhyloPlots.rexport — Method
rexport(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 = readnewick("(((A,(B)#H1:::0.9),(C,#H1:::0.1)),D);");
+    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?
source
PhyloPlots.rexport — Method
rexport(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 = readnewick("(((A,(B)#H1:::0.9),(C,#H1:::0.1)),D);");
 
 julia> phy = PhyloPlots.rexport(net)
 RObject{VecSxp}
@@ -54,4 +54,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"
source

+ - attr(*, "class")= chr [1:2] "evonet" "phylo"
source
diff --git a/dev/lib/public/index.html b/dev/lib/public/index.html index 6535522..bde4e55 100644 --- a/dev/lib/public/index.html +++ b/dev/lib/public/index.html @@ -2,7 +2,7 @@ public · PhyloPlots.jl
GitHub

public documentation

Documentation for PhyloPlots's public (exported) functions.

index

functions

PhyloPlots.plot — Method
plot(net::HybridNetwork)

Plot a network with edges going from left to right and taxa (leaves) placed on the right, 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
    • :majortree will simply draw minor edges onto the major tree.
    • :fulltree will 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. The default is 0.1 if style = :fulltree, and 0 if style = :majortree (making 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 width.
  • xlim, ylim: array of 2 values, to determine the axes limits.

tip annotations:

  • showtiplabel = true: if true, taxon labels (names) are shown.
  • tipoffset = 0: to offset tip labels.
  • tipcex = 1: 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: character expansion for labels in the nodelabel data frame.
  • edgecex = 1: character expansion for labels in the edgelabel data frame.

colors:

  • edgecolor = "black": color for tree edges.
  • majorhybridedgecolor = "deepskyblue4": color for major hybrid edges.
  • minorhybridedgecolor = "deepskyblue": color for minor hybrid edges.
  • edgenumbercolor = "grey": color for edge numbers.
  • edgelabelcolor = "black": color for labels in the edgelabel data frame.
  • nodelabelcolor = "black": color for labels in the nodelabel data frame.

Output the following named tuple, that can be used for downstream plot annotations with RCall:

(xmin, xmax, ymin, ymax,
  node_x,    node_y,    node_y_lo, node_y_hi,
  edge_x_lo, edge_x_hi, edge_y_lo, edge_y_hi,
- node_data, edge_data)
  1. :xmin: minimum x value of the plot
  2. :xmax: maximum x value of the plot
  3. :ymin: minimum y value of the plot
  4. :ymax: maximum y value of the plot
  5. :node_x: x values of the nodes in net.node in their respective order
  6. :node_y: y values of the nodes
  7. :node_y_lo: y value of the beginning of the vertical bar representing the clade at each node
  8. :node_y_hi: y value of the end of the vertical bar
  9. :edge_x_lo: x value of the beginning of the edges in net.edge in their respective order
  10. :edge_x_hi: x value of the end of the edges
  11. :edge_y_lo: y value of the beginning of the edges
  12. :edge_y_hi: y value of the end of the edges
  13. :node_data: node data frame: see section Adding labels for more
  14. :edge_data: edge data frame

Note that plot actually modifies some (minor) attributes of the network, as it calls PhyloNetworks.directedges! and PhyloNetworks.preorder!.

If hybrid edges cross tree and major edges, you may choose to rotate some tree edges to eliminate crossing edges, using PhyloNetworks.rotate!.

Alternative: a tree or network can be exported with sexp and then displayed with R's "plot" and all its options.

source
RCall.sexp — Method
function 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.

Examples

julia> using RCall
+ node_data, edge_data)
  1. :xmin: minimum x value of the plot
  2. :xmax: maximum x value of the plot
  3. :ymin: minimum y value of the plot
  4. :ymax: maximum y value of the plot
  5. :node_x: x values of the nodes in net.node in their respective order
  6. :node_y: y values of the nodes
  7. :node_y_lo: y value of the beginning of the vertical bar representing the clade at each node
  8. :node_y_hi: y value of the end of the vertical bar
  9. :edge_x_lo: x value of the beginning of the edges in net.edge in their respective order
  10. :edge_x_hi: x value of the end of the edges
  11. :edge_y_lo: y value of the beginning of the edges
  12. :edge_y_hi: y value of the end of the edges
  13. :node_data: node data frame: see section Adding labels for more
  14. :edge_data: edge data frame

Note that plot actually modifies some (minor) attributes of the network, as it calls PhyloNetworks.directedges! and PhyloNetworks.preorder!.

If hybrid edges cross tree and major edges, you may choose to rotate some tree edges to eliminate crossing edges, using PhyloNetworks.rotate!.

Alternative: a tree or network can be exported with sexp and then displayed with R's "plot" and all its options.

source
RCall.sexp — Method
function 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.

Examples

julia> using RCall
 julia> using PhyloNetworks
 julia> net = readnewick("(((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
@@ -43,4 +43,4 @@
  $ tip.label          : chr [1:4] "A" "B" "C" "D"
  - attr(*, "class")= chr [1:2] "evonet" "phylo"
 
-R> plot(net)
source
+R> plot(net)source diff --git a/dev/man/adding_data/index.html b/dev/man/adding_data/index.html index a4c0eb8..f7f63c5 100644 --- a/dev/man/adding_data/index.html +++ b/dev/man/adding_data/index.html @@ -109,4 +109,4 @@ 16 │ 1 16 #undef false false 4.5 8.5 17 │ 1 17 #undef false false 1.5 6.89062 18 │ 1 18 #undef false false 4.5 10.0 - 3 rows omitted + 3 rows omitted diff --git a/dev/man/better_edges/index.html b/dev/man/better_edges/index.html index 297e63b..17c1479 100644 --- a/dev/man/better_edges/index.html +++ b/dev/man/better_edges/index.html @@ -11,4 +11,4 @@ 9 => 5.0 8 => 3.0 3 => 3.0 - 1 => 5.0
julia> plot(net1, edgewidth=log_populationsize);

example5

+ 1 => 5.0
julia> plot(net1, edgewidth=log_populationsize);

example5

diff --git a/dev/man/getting_started/index.html b/dev/man/getting_started/index.html index bf3ae02..373c8fa 100644 --- a/dev/man/getting_started/index.html +++ b/dev/man/getting_started/index.html @@ -3,4 +3,4 @@ 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);

example1

For the function's full documentation, see here: plot.

version history

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).

+(A,((B,#H1),(C,(D)#H1)));

and call plot, as shown below.

plot(net);

example1

For the function's full documentation, see here: plot.

version history

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).

diff --git a/dev/man/installation/index.html b/dev/man/installation/index.html index 155fb97..71f33ff 100644 --- a/dev/man/installation/index.html +++ b/dev/man/installation/index.html @@ -1,3 +1,3 @@ installation · PhyloPlots.jl
GitHub

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 PhyloPlots

Or in julian mode:

using Pkg
-Pkg.add("PhyloPlots")
+Pkg.add("PhyloPlots") diff --git a/dev/man/untangling_edges/index.html b/dev/man/untangling_edges/index.html index 5a4355c..8cfdd25 100644 --- a/dev/man/untangling_edges/index.html +++ b/dev/man/untangling_edges/index.html @@ -1,3 +1,3 @@ untangling edges · PhyloPlots.jl
GitHub

Untangling the network

This plot may not be the easiest to read, as the hybrid edge crosses over C's edge:

example1

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);

example2

As we can see, rotating edges around node -5 will make for a prettier network.

rotate!(net, -5)
-plot(net)

example3

This may seem unnecessary for a small network as shown, but it is a useful tool for plotting large networks.

+plot(net)

example3

This may seem unnecessary for a small network as shown, but it is a useful tool for plotting large networks.