Rechercher une page de manuel

Bio::PhyloNetwork.3pm

Langue: en

Version: 2009-03-10 (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
SEE ALSO
APPENDIX

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

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 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 to use the Manhattan (default) or the
            Hamming distance between mu-vectors.
  Returns : scalar,hash
  Args    : Bio::PhyloNetwork,
            -metric => string (optional)