Provided by: libbio-perl-run-perl_1.6.9-2_all bug

NAME

       Bio::Tools::Run::Phylo::Phylip::Neighbor - Wrapper for the phylip program neighbor by
       Joseph Felsenstein for creating a phylogenetic tree(either through Neighbor or UPGMA)
       based on protein distances based on amino substitution rate.

       14 Nov 2002 Shawn Works with Phylip version 3.6

SYNOPSIS

         #Create a SimpleAlign object
         @params = ('ktuple' => 2, 'matrix' => 'BLOSUM');
         $factory = Bio::Tools::Run::Alignment::Clustalw->new(@params);
         $inputfilename = 't/data/cysprot.fa';
         $aln = $factory->run($inputfilename); # $aln is a SimpleAlign object.

         # Create the Distance Matrix
         # using a default PAM matrix and id name lengths limit of 30 note to
         # use id name length greater than the standard 10 in neighbor, you
         # will need to modify the neighbor source code

         $protdist_factory = Bio::Tools::Run::Phylo::Phylip::ProtDist->new(@params);
         my $matrix  = $protdist_factory->run($aln);

         #Create the tree passing in the distance matrix
         @params = ('type'=>'NJ','outgroup'=>2,'lowtri'=>1,
                    'upptri'=>1,'subrep'=>1);

         my $neighbor_factory =
            Bio::Tools::Run::Phylo::Phylip::Neighbor->new(@params);

         #you can set your outgroup using either a number specifying
         #the rank in the matrix or you can just use the name of the
         #species

         $neighbor_factory->outgroup('ENSP00001');
         #or
         $neighbor_factory->outgroup(1);

         my ($tree) = $neighbor_factory->run($matrix);

         # Alternatively, one can create the tree by passing in a file name
         # containing a phylip formatted distance matrix(using protdist)
         my $neighbor_factory =
           Bio::Tools::Run::Phylo::Phylip::Neighbor->new(@params);
         my ($tree) = $neighbor_factory->run('/home/shawnh/prot.dist');

         # To prevent PHYLIP from truncating sequence names:
         # Step 1. Shelf the original names:
           my ($aln_safe, $ref_name)=                    #   $aln_safe has serial names
                      $aln->set_displayname_safe();      #   $ref_name holds original names
         # Step 2. Run ProtDist and Neighbor:
           $matrix  = $protdist_factory->
                       creat_distance_matrix($aln_safe); #  Use $aln_safe instead of $aln
           $tree = $neighbor_factory->run($matrix);
         # Step 3. Retrieve orgininal OTU names:
           use Bio::Tree::Tree;
           my @nodes=$tree->get_nodes();
           foreach my $nd (@nodes){
              $nd->id($ref_name->{$nd->id_output}) if $nd->is_Leaf;
           }

PARAMTERS FOR NEIGHBOR COMPUTATION

   TYPE
         Title         : TYPE
         Description   : (optional)
                         This sets the type of tree to construct, using
                         neighbor joining or UPGMA.

                         NJ    Neighbor Joining
                         UPGMA UPGMA

         Usage         : @params = ('type'=>'X');#where X is one of the values above
                         Defaults to NJ

                         For more information on the usage of the different
                         models, please refer to the documentation found in
                         the phylip package.

   OUTGROUP (*ONLY AVAILABLE FOR NEIGHBOR JOINING)
         Title         : OUTGROUP
         Description   : (optional)
                         This option selects the species to be used as the outgroup
         Acceptable Values: integer
         Usage         : @params = ('outgroup'=>'X');
                         where X is an positive integer not more than the
                         number of sequences
                         Defaults to 1

   LOWTRI
         Title         : LOWTRI
         Description   : (optional)
                         This indicates that the distance matrix is
                         input  in  Lower-triangular form  (the  lower-left
                         half of the distance matrix only, without the zero
                         diagonal elements)
         Usage         : @params = ('lowtri'=>'X'); where X is either 1 or 0
                         Defaults to 0

   UPPTRI
         Title         : UPPTRI
         Description   : (optional)
                         This indicates that the distance matrix is input  in
                         upper-triangular form  (the  upper-right half of the
                         distance matrix only, without the zero diagonal elements.)
       Usage           : @params = ('upptri'=>'X'); where X is either 1 or 0
                         Defaults to 0

   SUBREP
         Title         : SUBREP
         Description   : (optional)
                         This is the Subreplication option.

                         It informs the program that after each distance will
                         be provided an integer indicating that the distance
                         is a mean of that many replicates.

         Usage         : @params = ('subrep'=>'X'); where X is either 1 or 0
                         Defaults to 0

   JUMBLE
         Title        : JUMBLE
         Description  : (optional)

                        This enables you to tell the program to use a random
                        number generator to choose the input order of
                        species.  seed: an integer between 1 and 32767 and of
                        the form 4n+1 which means that it must give a
                        remainder of 1 when divided by 4.  Each different
                        seed leads to a different sequence of addition of
                        species.  By simply changing the random number seed
                        and re-running programs one can look for other, and
                        better trees.  iterations:

         Usage        : @params = ('jumble'=>'17); where 17 is the random seed
                        Defaults to no jumble

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web:

         http://redmine.open-bio.org/projects/bioperl/

AUTHOR - Shawn Hoon

       Email shawnh@fugu-sg.org

CONTRIBUTORS

       Email:jason-at-bioperl.org

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   program_name
        Title   : program_name
        Usage   : >program_name()
        Function: holds the program name
        Returns:  string
        Args    : None

   program_dir
        Title   : program_dir
        Usage   : ->program_dir()
        Function: returns the program directory, obtained from ENV variable.
        Returns:  string
        Args    :

   idlength
        Title   : idlength
        Usage   : $obj->idlength ($newval)
        Function:
        Returns : value of idlength
        Args    : newvalue (optional)

   run
        Title   : run
        Usage   :
               $inputfilename = 't/data/prot.dist';
               $tree = $neighborfactory->run($inputfilename);
        or
               $protdist_factory = Bio::Tools::Run::Phylo::Phylip::ProtDist->new(@params);
               $matrix  = $protdist_factory->create_distance_matrix($aln);
               $tree= $neighborfactory->run($matrix);

        Function: a Bio:Tree from a protein distance matrix created by protidst
        Example :
        Returns : Bio::Tree
        Args    : Name of a file containing a protein distance matrix in Phylip format
                  or a hash ref to a matrix

        Throws an exception if argument is not either a string (eg a
        filename) or a Hash. If argument is string, throws exception
        if file corresponding to string name can not be found.

   create_tree
        Title   : create_tree
        Usage   : my $file = $app->create_tree($treefile);
        Function: This method is deprecated. Please use run method.
        Returns : File containing the rendered tree
        Args    : either a Bio::Tree::TreeI
                   OR
                  filename of a tree in newick format

   _run
        Title   :  _run
        Usage   :  Internal function, not to be called directly
        Function:   makes actual system call to neighbor program
        Example :
        Returns : Bio::Tree object
        Args    : Name of a file containing protein distances in Phylip format
                  and a parameter string to be passed to neighbor

   _setinput()
        Title   : _setinput
        Usage   : Internal function, not to be called directly
        Function: Create input file for neighbor program
        Example :
        Returns : name of file containing the protein distance matrix in Phylip format
        Args    : name of file created by protdist or ref to hash created by
                  Bio::Tools:Run::Phylo::Phylip::ProtDist

   names()
        Title   :  names
        Usage   :  $tree->names(\%names)
        Function:  get/set for a hash ref for storing names in matrix
                   with rank as values.
        Example :
        Returns : hash reference
        Args    : hash reference

   _setparams()
        Title   :  _setparams
        Usage   :  Internal function, not to be called directly
        Function:   Create parameter inputs for neighbor program
        Example :
        Returns : parameter string to be passed to neighbor
        Args    : name of calling object

   outfile
        Title   : outfile
        Usage   : $obj->outfile($newval)
        Function: Get/Set default PHYLIP outfile name ('outfile' usually)
        Returns : value of outfile
        Args    : newvalue (optional)

   treefile
        Title   : treefile
        Usage   : $obj->treefile($newval)
        Function: Get/Set the default PHYLIP treefile name ('treefile' usually)
        Returns : value of treefile
        Args    : newvalue (optional)

perl v5.18.1                                2013-11-Bio::Tools::Run::Phylo::Phylip::Neighbor(3pm)