Provided by: libbio-perl-perl_1.7.2-2_all bug

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