NAME

Bio::Phylo - Phylogenetic analysis using perl

SYNOPSIS

# Actually, you would almost never use this module directly. This is 
# the base class for other modules.
use Bio::Phylo;

# sets global verbosity to 'error'
Bio::Phylo->VERBOSE( -level => Bio::Phylo::Util::Logger::ERROR );

# sets verbosity for forest ojects to 'debug'
Bio::Phylo->VERBOSE( 
	-level => Bio::Phylo::Util::Logger::DEBUG, 
	-class => 'Bio::Phylo::Forest' 
);

# prints version, including SVN revision number
print Bio::Phylo->VERSION;

# prints suggested citation
print Bio::Phylo->CITATION;

DESCRIPTION

This is the base class for the Bio::Phylo package for phylogenetic analysis using object-oriented perl5. In this file, methods are defined that are performed by other objects in the Bio::Phylo release that inherit from this base class (which you normally wouldn't use directly).

For general information on how to use Bio::Phylo, consult the manual (Bio::Phylo::Manual).

If you come here because you are trying to debug a problem you run into in using Bio::Phylo, you may be interested in the "exceptions" system as discussed in Bio::Phylo::Util::Exceptions. In addition, you may find the logging system in Bio::Phylo::Util::Logger of use to localize problems.

METHODS

CONSTRUCTOR

new()

The Bio::Phylo root constructor is rarely used directly. Rather, many other objects in Bio::Phylo internally go up the inheritance tree to this constructor. The arguments shown here can therefore also be passed to any of the child classes' constructors, which will pass them on up the inheritance tree. Generally, constructors in Bio::Phylo subclasses can process as arguments all methods that have set_* in their names. The arguments are named for the methods, but "set_" has been replaced with a dash "-", e.g. the method "set_name" becomes the argument "-name" in the constructor.

Type    : Constructor
Title   : new
Usage   : my $phylo = Bio::Phylo->new;
Function: Instantiates Bio::Phylo object
Returns : a Bio::Phylo object 
Args    : Optional, any number of setters. For example,
		   Bio::Phylo->new( -name => $name )
		   will call set_name( $name ) internally

MUTATORS

set_guid()

Sets invocant GUID.

 Type    : Mutator
 Title   : set_guid
 Usage   : $obj->set_guid($guid);
 Function: Assigns an object's GUID.
 Returns : Modified object.
 Args    : A scalar
 Notes   : This field can be used for storing an identifier that is
           unambiguous within a given content. For example, an LSID,
	   a genbank accession number, etc.

set_desc()

Sets invocant description.

Type    : Mutator
Title   : set_desc
Usage   : $obj->set_desc($desc);
Function: Assigns an object's description.
Returns : Modified object.
Args    : Argument must be a string.

set_score()

Sets invocant score.

Type    : Mutator
Title   : set_score
Usage   : $obj->set_score($score);
Function: Assigns an object's numerical score.
Returns : Modified object.
Args    : Argument must be any of
          perl's number formats, or undefined
          to reset score.

set_generic()

Sets generic key/value pair(s).

Type    : Mutator
Title   : set_generic
Usage   : $obj->set_generic( %generic );
Function: Assigns generic key/value pairs to the invocant.
Returns : Modified object.
Args    : Valid arguments constitute:

          * key/value pairs, for example:
            $obj->set_generic( '-lnl' => 0.87565 );

          * or a hash ref, for example:
            $obj->set_generic( { '-lnl' => 0.87565 } );

          * or nothing, to reset the stored hash, e.g.
               $obj->set_generic( );

ACCESSORS

get_nexus_name()

Gets invocant's name, modified to be safely used in nexus files. This means that:

*

names with spaces in them that aren't 'single quoted' have their spaces replaced with underscores

*

names with any of the following characters in them are single quoted: -^*(){}[]+=;:"\<>/,

*

names with single quotes inside them (i.e. not around them) are "double quoted"

Type    : Accessor
Title   : get_nexus_name
Usage   : my $name = $obj->get_nexus_name;
Function: Returns the object's name.
Returns : A string
Args    : None

get_internal_name()

Gets invocant's 'fallback' name (possibly autogenerated).

Type    : Accessor
Title   : get_internal_name
Usage   : my $name = $obj->get_internal_name;
Function: Returns the object's name (if none was set, the name
          is a combination of the $obj's class and its UID).
Returns : A string
Args    : None

get_guid()

Gets invocant GUID.

 Type    : Accessor
 Title   : get_guid
 Usage   : my $guid = $obj->get_guid;
 Function: Assigns an object's GUID.
 Returns : Scalar.
 Args    : None
 Notes   : This field can be used for storing an identifier that is
           unambiguous within a given content. For example, an LSID,
	   a genbank accession number, etc.

get_desc()

Gets invocant description.

Type    : Accessor
Title   : get_desc
Usage   : my $desc = $obj->get_desc;
Function: Returns the object's description (if any).
Returns : A string
Args    : None

get_score()

Gets invocant's score.

Type    : Accessor
Title   : get_score
Usage   : my $score = $obj->get_score;
Function: Returns the object's numerical score (if any).
Returns : A number
Args    : None

get_generic()

Gets generic hashref or hash value(s).

Type    : Accessor
Title   : get_generic
Usage   : my $value = $obj->get_generic($key);
          or
          my %hash = %{ $obj->get_generic() };
Function: Returns the object's generic data. If an
          argument is used, it is considered a key
          for which the associated value is returned.
          Without arguments, a reference to the whole
          hash is returned.
Returns : A value or an array reference of values
Args    : A key (string) or an array reference of keys

get_logger()

Gets a logger object.

Type    : Accessor
Title   : get_logger
Usage   : my $logger = $obj->get_logger;
Function: Returns a Bio::Phylo::Util::Logger object
Returns : Bio::Phylo::Util::Logger
Args    : None

PACKAGE METHODS

get()

Attempts to execute argument string as method on invocant.

Type    : Accessor
Title   : get
Usage   : my $treename = $tree->get('get_name');
Function: Alternative syntax for safely accessing
          any of the object data; useful for
          interpolating runtime $vars.
Returns : (context dependent)
Args    : a SCALAR variable, e.g. $var = 'get_name';

get_obj_by_id()

Attempts to fetch an in-memory object by its UID

Type    : Accessor
Title   : get_obj_by_id
Usage   : my $obj = Bio::Phylo->get_obj_by_id($uid);
Function: Fetches an object from the IDPool cache
Returns : A Bio::Phylo object 
Args    : A unique id

to_string()

Serializes object to general purpose string

Type    : Serializer
Title   : to_string()
Usage   : print $obj->to_string();
Function: Serializes object to general purpose string
Returns : String 
Args    : None
Comments: This is YAML

clone()

Clones invocant.

Type    : Utility method
Title   : clone
Usage   : my $clone = $object->clone;
Function: Creates a copy of the invocant object.
Returns : A copy of the invocant.
Args    : None.
Comments: Cloning is currently experimental, use with caution.

VERBOSE()

Getter and setter for the verbosity level. Refer to Bio::Phylo::Util::Logger for more info on available verbosity levels.

Type    : Accessor
Title   : VERBOSE()
Usage   : Bio::Phylo->VERBOSE( -level => $level )
Function: Sets/gets verbose level
Returns : Verbose level
Args    : -level => $level
Comments:

CITATION()

Returns suggested citation.

Type    : Accessor
Title   : CITATION
Usage   : $phylo->CITATION;
Function: Returns suggested citation.
Returns : Returns suggested citation.
Args    : None
Comments:

VERSION()

Gets version number (including revision number).

Type    : Accessor
Title   : VERSION
Usage   : $phylo->VERSION;
Function: Returns version number
          (including SVN revision number).
Alias   :
Returns : SCALAR
Args    : NONE
Comments:

SEE ALSO

There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.

Also see the manual: Bio::Phylo::Manual and http://rutgervos.blogspot.com

CITATION

If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/1471-2105-12-63