Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::PhyloNetwork(3)  User Contributed Perl Documentation Bio::PhyloNetwork(3)

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

   Tree-child phylogenetic networks
       Tree-child (TC) phylogenetic networks are a special class of
       phylogenetic networks for which a distance, called mu-distance, is
       defined [CRV2] based on certain data (mu-data) associated to every
       node.  Moreover,	this distance extends the Robinson-Foulds on
       phylogenetic trees. This	package	allows testing for a phylogenetic
       network if it is	TC and computes	mu-distances between networks over the
       same set	of leaves.

       Moreover, the mu-data 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.

   Time-consistency
       Another useful property of Phylogenetic Networks	that appears in	the
       literature is that of time-consistency or real-time 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 time-consistency
       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 [q-bio.PE]

       [CRV2]
	   G. Cardona, F. Rossello, G. Valiente. A Distance Measure for	Tree-
	   Child Phylogenetic Networks.	Preprint.

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

       [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):46-56, 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 mu-data stored in
	  \%mudata and with set	of leaves in \@leaves.

       new(-mudata => \%mudata,	-numleaves => $numleaves)
	  creates the network by reconstructing	it from	its mu-data 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 Tree-Child	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 mu-data
	Returns	: hash
	Args	: none

       $net->mudata() returns a	hash with keys the nodes of $net and each
       value is	a muVector object holding its mu-vector.

   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 mu-distance 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 mu-distance 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) time-consistent
	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 time-consistent
	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 mu-vectors.
	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 mu-vectors.
	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

perl v5.24.1			  2017-07-08		  Bio::PhyloNetwork(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO | APPENDIX

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::PhyloNetwork&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help