Bio::Phylo::ListableRole(3)

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

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

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

METHODS

  ARRAY METHODS

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 doesn't 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 i'th 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 = @{
                   $obj->get_by_regular_expression(
                        -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)

  VISITOR METHODS

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.

  TESTS

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

  UTILITY METHODS

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

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

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

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

  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.

  Superclasses

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

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>