 NAME
 SYNOPSIS
 DESCRIPTION
 AUTHOR
 SEE ALSO
 APPENDIX
 new
 is_leaf
 is_root
 is_tree_node
 is_hybrid_node
 is_tree_child
 nodes
 leaves
 roots
 internal_nodes
 tree_nodes
 hybrid_nodes
 graph
 edges
 tree_edges
 hybrid_edges
 explode
 mudata
 heights
 mu_distance
 mu_distance_generalized
 tripartitions
 is_time_consistent
 temporal_representation
 contract_elementary
 optimal_alignment
 optimal_alignment_generalized
 topological_restriction
 eNewick
 eNewick_full
 display
NAME
Bio::PhyloNetwork  Module to compute with Phylogenetic Networks
SYNOPSIS
use Bio::PhyloNetwork;
# Create a PhyloNetwork object from a eNewick string
my $net1=Bio::PhyloNetwork>new(
eNewick=>'t0:((H1,(H2,l2)),H2); H1:((H3,l1)); H2:((H3,(l3,H1))); H3:(l4);'
);
# Print all available data
print $net1;
# Rebuild $net1 from its mu_data
my %mudata=$net1>mudata();
my $net2=Bio::PhyloNetwork>new(mudata=>\%mudata,numleaves=>4);
print $net2;
print "d=".$net1>mu_distance($net2)."\n";
# Get another one and compute distance
my $net3=Bio::PhyloNetwork>new(
eNewick=>'(l2,((l1,(H1,l4)),H1))r; (l3)H1;'
);
print "d=".$net1>mu_distance($net3)."\n";
# ...and find an optimal alignment w.r.t. the Manhattan distance (default)
my ($weight,%alignment)=$net1>optimal_alignment($net3);
print "weight:$weight\n";
foreach my $node1 (keys %alignment) {
print "$node1 => ".$alignment{$node1}."\n";
}
# ...or the Hamming distance
my ($weightH,%alignmentH)=$net1>optimal_alignment($net3,metric=>'Hamming');
print "weight:$weightH\n";
foreach my $node1 (keys %alignmentH) {
print "$node1 => ".$alignmentH{$node1}."\n";
}
# Test for time consistency of $net1
if ($net1>is_time_consistent) {
print "net1 is time consistent\n"
}
else {
print "net1 is not time consistent\n"
}
# create a network from the list of edges
my $net4=Bio::PhyloNetwork>new(edges=>
[qw(r s r t s u s c t c t v u b u l3 u b v b v l4 b l2 c l1)]);
# Test for time consistency of $net3
if ($net4>is_time_consistent) {
print "net4 is time consistent\n"
}
else {
print "net4 is not time consistent\n"
}
# And print all information on net4
print $net4;
# Compute some tripartitions
my %triparts=$net1>tripartitions();
# Now these are stored
print $net1;
# And can compute the tripartition error
print "dtr=".$net1>tripartition_error($net3)."\n";
DESCRIPTION
Phylogenetic Networks
This is a module to work with phylogenetic networks. Phylogenetic networks have been studied over the last years as a richer model of the evolutionary history of sets of organisms than phylogenetic trees, because they take not only mutation events but also recombination and horizontal gene transfer events into account.
The natural model for describing the evolutionary history of a set of sequences under recombination events is a DAG, hence this package relies on the package Graph::Directed to represent the underlying graph of a phylogenetic network. We refer the reader to [CRV1,CRV2] for formal definitions related to phylogenetic networks.
eNewick description
With this package, phylogenetic networks can be given by its eNewick string. This description appeared in other packages related to phylogenetic networks (see [PhyloNet] and [NetGen]); in fact, these two packages use different descriptions. The Bio::PhyloNetwork package allows both of them, but uses the second one in its output.
The first approach [PhyloNet] goes as follows: For each hybrid node H, say with parents u_1,u_2,...,u_k and children v_1,v_2,...v_l: split H in k+1 different nodes; let each of the first k copies be a child of one of the u_1,...,u_k (one for each) and have no children (hence we will have k extra leaves); as for the last copy, let it have no parents and have v_1,...,v_l be its children. This way we get a forest; each of the trees will be rooted at either one root of the phylogenetic network or a hybrid node of it; the set of leaves (of the whole forest) will be the set of leaves of the original network together with the set of hybrid nodes (each of them repeated as many times as its indegree). Then, the eNewick representation of the phylogenetic network will be the Newick representation of all the trees in the obtained forest, each of them with its root labeled.
The second approach [NetGen] goes as follows: For each hybrid node H, say with parents u_1,u_2,...,u_k and children v_1,v_2,...v_l: split H in k different nodes; let the first copy be a child of u_1 and have all v_1,v_2,...v_l as its children; let the other copies be child of u_2,...,u_k (one for each) and have no children. This way, we get a tree whose set of leaves is the set of leaves of the original network together with the set of hybrid nodes (possibly repeated). Then the Newick string of the obtained tree (note that some internal nodes will be labeled and some leaves will be repeated) is the eNewick string of the phylogenetic network.
For example, consider the network depicted below:
r
/ \
/ \
U V
/ \ / \
1 \ / 3
H

2
If the first approach is taken, we get the forest:
r
/ \
/ \
U V
/ \ / \
1 H H 3

H

2
Hence, the eNewick string is '((1,H),(H,3))r; (2)H;'.
As for the second one, one gets the tree:
r
/ \
/ \
U V
/ \ / \
1 H  3
H

2
Hence, the eNewick string is '((1,H),((2)H,3))r;'.
Note: when rooting a tree, this package allows the notations '(subtree,subtree,...)root' as well as 'root:(subtree,subtree,...)', but the first one is used when writing eNewick strings.
Treechild phylogenetic networks
Treechild (TC) phylogenetic networks are a special class of phylogenetic networks for which a distance, called mudistance, is defined [CRV2] based on certain data (mudata) associated to every node. Moreover, this distance extends the RobinsonFoulds on phylogenetic trees. This package allows testing for a phylogenetic network if it is TC and computes mudistances between networks over the same set of leaves.
Moreover, the mudata allows one to define the optimal (in some precise sense) alignment between networks over the same set of leaves. This package also computes this optimal alignment.
Tripartitions
Although tripartitions (see [CRV1] and the references therein) do not allow to define distances, this package outputs tripartitions and computes a weak form of the tripartition error.
Timeconsistency
Another useful property of Phylogenetic Networks that appears in the literature is that of timeconsistency or realtime hybrids [BSS]. Roughly speaking, a network admits a temporal representation if it can be drawn in such a way that tree arcs (those whose end is a tree node) are inclined downwards, while hybridization arcs (those whose end is a hybrid node) are horizontal. This package checks for timeconsistency and, if so, a temporal representation is provided.
AUTHOR
Gabriel Cardona, gabriel(dot)cardona(at)uib(dot)es
Gabriel Valiente, valiente(at)lsi(dot)upc(dot)edu
SEE ALSO
 [CRV1]

G. Cardona, F. Rossello, G. Valiente. Tripartitions do not always discriminate phylogenetic networks. arXiv:0707.2376v1 [qbio.PE]
 [CRV2]

G. Cardona, F. Rossello, G. Valiente. A Distance Measure for TreeChild Phylogenetic Networks. Preprint.
 [NetGen]

M.M. Morin, and B.M.E. Moret. NetGen: generating phylogenetic networks with diploid hybrids. Bioinformatics 22 (2006), 19211923
 [PhyloNet]

PhyloNet: "Phylogenetic Networks Toolkit". http://bioinfo.cs.rice.edu/phylonet
 [BSS]

M. Baroni, C. Semple, and M. Steel. Hybrids in Real Time. Syst. Biol. 55(1):4656, 2006
APPENDIX
The rest of the documentation details each of the object methods.
new
Title : new
Usage : my $obj = new Bio::PhyloNetwork();
Function: Creates a new Bio::PhyloNetwork object
Returns : Bio::PhyloNetwork
Args : none
OR
eNewick => string
OR
graph => Graph::Directed object
OR
edges => reference to an array
OR
tree => Bio::Tree::Tree object
OR
mudata => reference to a hash,
leaves => reference to an array
OR
mudata => reference to a hash,
numleaves => integer
Returns a Bio::PhyloNetwork object, created according to the data given:
 new()

creates an empty network.
 new(eNewick => $str)

creates the network whose Extended Newick representation (see description above) is the string $str.
 new(graph => $graph)

creates the network with underlying graph given by the Graph::Directed object $graph
 new(tree => $tree)

creates a network as a copy of the Bio::Tree::Tree object in $tree
 new(mudata => \%mudata, leaves => \@leaves)

creates the network by reconstructing it from its mudata stored in \%mudata and with set of leaves in \@leaves.
 new(mudata => \%mudata, numleaves => $numleaves)

creates the network by reconstructing it from its mudata stored in \%mudata and with set of leaves in ("l1".."l$numleaves").
is_leaf
Title : is_leaf
Usage : my $b=$net>is_leaf($u)
Function: tests if $u is a leaf in $net
Returns : boolean
Args : scalar
is_root
Title : is_root
Usage : my $b=$net>is_root($u)
Function: tests if $u is the root of $net
Returns : boolean
Args : scalar
is_tree_node
Title : is_tree_node
Usage : my $b=$net>is_tree_node($u)
Function: tests if $u is a tree node in $net
Returns : boolean
Args : scalar
is_hybrid_node
Title : is_hybrid_node
Usage : my $b=$net>is_hybrid_node($u)
Function: tests if $u is a hybrid node in $net
Returns : boolean
Args : scalar
is_tree_child
Title : is_tree_child
Usage : my $b=$net>is_tree_child()
Function: tests if $net is a TreeChild phylogenetic network
Returns : boolean
Args : Bio::PhyloNetwork
nodes
Title : nodes
Usage : my @nodes=$net>nodes()
Function: returns the set of nodes of $net
Returns : array
Args : none
leaves
Title : leaves
Usage : my @leaves=$net>leaves()
Function: returns the set of leaves of $net
Returns : array
Args : none
roots
Title : roots
Usage : my @roots=$net>roots()
Function: returns the set of roots of $net
Returns : array
Args : none
internal_nodes
Title : internal_nodes
Usage : my @internal_nodes=$net>internal_nodes()
Function: returns the set of internal nodes of $net
Returns : array
Args : none
tree_nodes
Title : tree_nodes
Usage : my @tree_nodes=$net>tree_nodes()
Function: returns the set of tree nodes of $net
Returns : array
Args : none
hybrid_nodes
Title : hybrid_nodes
Usage : my @hybrid_nodes=$net>hybrid_nodes()
Function: returns the set of hybrid nodes of $net
Returns : array
Args : none
graph
Title : graph
Usage : my $graph=$net>graph()
Function: returns the underlying graph of $net
Returns : Graph::Directed
Args : none
edges
Title : edges
Usage : my @edges=$net>edges()
Function: returns the set of edges of $net
Returns : array
Args : none
Each element in the array is an anonimous array whose first element is the head of the edge and the second one is the tail.
tree_edges
Title : tree_edges
Usage : my @tree_edges=$net>tree_edges()
Function: returns the set of tree edges of $net
(those whose tail is a tree node)
Returns : array
Args : none
hybrid_edges
Title : hybrid_edges
Usage : my @hybrid_edges=$net>hybrid_edges()
Function: returns the set of hybrid edges of $net
(those whose tail is a hybrid node)
Returns : array
Args : none
explode
Title : explode
Usage : my @trees=$net>explode()
Function: returns the representation of $net by a set of
Bio::Tree:Tree objects
Returns : array
Args : none
mudata
Title : mudata
Usage : my %mudata=$net>mudata()
Function: returns the representation of $net by its mudata
Returns : hash
Args : none
$net>mudata() returns a hash with keys the nodes of $net and each value is a muVector object holding its muvector.
heights
Title : heights
Usage : my %heights=$net>heights()
Function: returns the heights of the nodes of $net
Returns : hash
Args : none
$net>heights() returns a hash with keys the nodes of $net and each value is its height.
mu_distance
Title : mu_distance
Usage : my $dist=$net1>mu_distance($net2)
Function: Computes the mudistance between the networks $net1 and $net2 on
the same set of leaves
Returns : scalar
Args : Bio::PhyloNetwork
mu_distance_generalized
Title : mu_distance_generalized
Usage : my $dist=$net1>mu_distance($net2)
Function: Computes the mudistance between the topological restrictions of
networks $net1 and $net2 on its common set of leaves
Returns : scalar
Args : Bio::PhyloNetwork
tripartitions
Title : tripartitions
Usage : my %tripartitions=$net>tripartitions()
Function: returns the set of tripartitions of $net
Returns : hash
Args : none
$net>tripartitions() returns a hash with keys the nodes of $net and each value is a string representing the tripartition of the leaves induced by the node. A string "BCA..." associated with a node u (e.g.) means, the first leaf is in the set B(u), the second one in C(u), the third one in A(u), and so on.
is_time_consistent
Title : is_time_consistent
Usage : my $b=$net>is_time_consistent()
Function: tests if $net is (strong) timeconsistent
Returns : boolean
Args : none
temporal_representation
Title : temporal_representation
Usage : my %time=$net>temporal_representation()
Function: returns a hash containing a temporal representation of $net, or 0
if $net is not timeconsistent
Returns : hash
Args : none
contract_elementary
Title : contract_elementary
Usage : my ($contracted,$blocks)=$net>contract_elementary();
Function: Returns the network $contracted, obtained by contracting elementary
paths of $net into edges. The reference $blocks points to a hash
where, for each node of $contracted, gives the corresponding nodes
of $net that have been deleted.
Returns : Bio::PhyloNetwork,reference to hash
Args : none
optimal_alignment
Title : optimal_alignment
Usage : my ($weight,$alignment,$wgts)=$net>optimal_alignment($net2)
Function: returns the total weight of an optimal alignment,
the alignment itself, and partial weights
between the networks $net1 and $net2 on the same set of leaves.
An optional argument allows one to use the Manhattan (default) or the
Hamming distance between muvectors.
Returns : scalar,reference to hash,reference to hash
Args : Bio::PhyloNetwork,
metric => string (optional)
Supported strings for the metric parameter are 'Manhattan' or 'Hamming'.
optimal_alignment_generalized
Title : optimal_alignment_generalized
Usage : my ($weight,%alignment)=$net>optimal_alignment_generalized($net2)
Function: returns the wieght of an optimal alignment, and the alignment itself,
between the topological restriction of the networks $net1 and $net2
on the set of common leaves.
An optional argument allows one to use the Manhattan (default) or the
Hamming distance between muvectors.
Returns : scalar,hash
Args : Bio::PhyloNetwork,
metric => string (optional)
Supported strings for the metric parameter are 'Manhattan' or 'Hamming'.
topological_restriction
Title : topological_restriction
Usage : my ($netr1,$netr2)=$net1>topological_restriction($net2)
Function: returns the topological restriction of $net1 and $net2 on its
common set of leaves
Returns : Bio::PhyloNetwork, Bio::PhyloNetwork
Args : Bio::PhyloNetwork
eNewick
Title : eNewick
Usage : my $str=$net>eNewick()
Function: returns the eNewick representation of $net without labeling
internal tree nodes
Returns : string
Args : none
eNewick_full
Title : eNewick_full
Usage : my $str=$net>eNewick_full()
Function: returns the eNewick representation of $net labeling
internal tree nodes
Returns : string
Args : none
display
Title : display
Usage : my $str=$net>display()
Function: returns a string containing all the available information on $net
Returns : string
Args : none