Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  BIO::PHYLO::LISTABLEROLE (3)

.ds Aq ’


Bio::Phylo::ListableRole - Extra functionality for things that are lists



 No direct usage, parent class. Methods documented here
 are available for all objects that inherit from it.


A listable object is an object that contains multiple smaller objects of the same type. For example: a tree contains nodes, so it’s a listable object.

This class contains methods that are useful for all listable objects: Matrices (i.e. sets of matrix objects), individual Matrix objects, Datum objects (i.e. character state sequences), Taxa, Forest, Tree and Node objects.



prune_entities() Prunes the container’s contents specified by an array reference of indices.

 Type    : Mutator
 Title   : prune_entities
 Usage   : $list->prune_entities([9,7,7,6]);
 Function: Prunes a subset of contents
 Returns : A Bio::Phylo::Listable object.
 Args    : An array reference of indices

get_index_of() Returns the index of the argument in the list, or undef if the list doesn’t contain the argument

 Type    : Accessor
 Title   : get_index_of
 Usage   : my $i = $listable->get_index_of($obj)
 Function: Returns the index of the argument in the list,
           or undef if the list doesnt contain the argument
 Returns : An index or undef
 Args    : A contained object

get_by_index() Gets element at index from container.

 Type    : Accessor
 Title   : get_by_index
 Usage   : my $contained_obj = $obj->get_by_index($i);
 Function: Retrieves the ith entity
           from a listable object.
 Returns : An entity stored by a listable
           object (or array ref for slices).
 Args    : An index or range. This works
           the way you dereference any perl
           array including through slices,
           i.e. $obj->get_by_index(0 .. 10)>
           $obj->get_by_index(0, -1)
           and so on.
 Comments: Throws if out-of-bounds

get_by_regular_expression() Gets elements that match regular expression from container.

 Type    : Accessor
 Title   : get_by_regular_expression
 Usage   : my @objects = @{
                    -value => $method,
                    -match => $re
            ) };
 Function: Retrieves the data in the
           current Bio::Phylo::Listable
           object whose $method output
           matches $re
 Returns : A list of Bio::Phylo::* objects.
 Args    : -value => any of the string
                     datum props (e.g. get_type)
           -match => a compiled regular
                     expression (e.g. qr/^[D|R]NA$/)

get_by_value() Gets elements that meet numerical rule from container.

 Type    : Accessor
 Title   : get_by_value
 Usage   : my @objects = @{ $obj->get_by_value(
              -value => $method,
              -ge    => $number
           ) };
 Function: Iterates through all objects
           contained by $obj and returns
           those for which the output of
           $method (e.g. get_tree_length)
           is less than (-lt), less than
           or equal to (-le), equal to
           (-eq), greater than or equal to
           (-ge), or greater than (-gt) $number.
 Returns : A reference to an array of objects
 Args    : -value => any of the numerical
                     obj data (e.g. tree length)
           -lt    => less than
           -le    => less than or equals
           -eq    => equals
           -ge    => greater than or equals
           -gt    => greater than

get_by_name() Gets first element that has argument name

 Type    : Accessor
 Title   : get_by_name
 Usage   : my $found = $obj->get_by_name(foo);
 Function: Retrieves the first contained object
           in the current Bio::Phylo::Listable
           object whose name is foo
 Returns : A Bio::Phylo::* object.
 Args    : A name (string)


visit() Iterates over objects contained by container, executes argument code reference on each.

 Type    : Visitor predicate
 Title   : visit
 Usage   : $obj->visit(
               sub{ print $_[0]->get_name, "\n" }
 Function: Implements visitor pattern
           using code reference.
 Returns : The container, possibly modified.
 Args    : a CODE reference.


contains() Tests whether the container object contains the argument object.

 Type    : Test
 Title   : contains
 Usage   : if ( $obj->contains( $other_obj ) ) {
               # do something
 Function: Tests whether the container object
           contains the argument object
 Returns : BOOLEAN
 Args    : A Bio::Phylo::* object

can_contain() Tests if argument can be inserted in container.

 Type    : Test
 Title   : can_contain
 Usage   : &do_something if $listable->can_contain( $obj );
 Function: Tests if $obj can be inserted in $listable
 Returns : BOOL
 Args    : An $obj to test


cross_reference() The cross_reference method links node and datum objects to the taxa they apply to. After crossreferencing a matrix with a taxa object, every datum object has a reference to a taxon object stored in its $datum->get_taxon field, and every taxon object has a list of references to datum objects stored in its $taxon->get_data field.

 Type    : Generic method
 Title   : cross_reference
 Usage   : $obj->cross_reference($taxa);
 Function: Crossreferences the entities
           in the container with names
           in $taxa
 Returns : string
 Args    : A Bio::Phylo::Taxa object

alphabetize() Sorts the contents alphabetically by their name.

 Type    : Generic method
 Title   : alphabetize
 Usage   : $obj->alphabetize;
 Function: Sorts the contents alphabetically by their name.
 Returns : $self
 Args    : None


Many Bio::Phylo objects are segmented, i.e. they contain one or more subparts of the same type. For example, a matrix contains multiple rows; each row contains multiple cells; a tree contains nodes, and so on. (Segmented objects all inherit from Bio::Phylo::Listable, i.e. the class whose documentation you’re reading here.) In many cases it is useful to be able to define subsets of the contents of segmented objects, for example sets of taxon objects inside a taxa block. The Bio::Phylo::Listable object allows this through a number of methods (add_set, remove_set, add_to_set, remove_from_set etc.). Those methods delegate the actual management of the set contents to the Bio::Phylo::Set object. Consult the documentation for Bio::Phylo::Set for a code sample.
sets_to_xml() Returns string representation of sets

 Type    : Accessor
 Title   : sets_to_xml
 Usage   : my $str = $obj->sets_to_xml;
 Function: Gets xml string
 Returns : Scalar
 Args    : None


There is a mailing list at <!forum/bio-phylo> for any user or developer questions and discussions.

Also see the manual: Bio::Phylo::Manual and <>.

    Objects inheriting from Bio::Phylo::Listable

Bio::Phylo::Forest Iterate over a set of trees.
Bio::Phylo::Forest::Tree Iterate over nodes in a tree.
Bio::Phylo::Forest::Node Iterate of children of a node.
Bio::Phylo::Matrices Iterate over a set of matrices.
Bio::Phylo::Matrices::Matrix Iterate over the datum objects in a matrix.
Bio::Phylo::Matrices::Datum Iterate over the characters in a datum.
Bio::Phylo::Taxa Iterate over a set of taxa.


Bio::Phylo::NeXML::Writable This object inherits from Bio::Phylo::NeXML::Writable, so methods defined there are also applicable here.


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

<B>Rutger A VosB>, <B>Jason CaravasB>, <B>Klaas HartmannB>, <B>Mark A JensenB> and <B>Chase MillerB>, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics <B>12B>:63. <>

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 BIO::PHYLO::LISTABLEROLE (3) 2014-02-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.