Bio::Root::Vector - Interface for managing linked lists of Perl5 objects.
At present, Vector objects cannot be instantiated. This package is currently designed to be inherited along with another class that provides a constructor (e.g., Bio::Root::Object.pm). The Vector provides a set of methods that can then be used for managing sets of objects.
See the USAGE section .
This module is included with the central Bioperl distribution:
http://bio.perl.org/Core/Latest ftp://bio.perl.org/pub/DIST
Follow the installation instructions included in the README file.
Bio::Root::Vector.pm provides an interface for creating and manipulating dynamic sets (linked lists) of Perl5 objects. This is an abstract class (ie., there is no constructor) and as such is expected to be inherited along with some other class (see note above).
Vectors are handy when, for example, an object may contain one or more other objects of a certain class. The container object knows only that is has at least one such object; the multiplex nature of the contained object is managed by the contained object via its Vector interface. The methods for adding, removing, counting, listing, and sorting all objects are bundled together in Vector.pm.
Thus, the current Bio::Root::Vector class is somewhat of a cross between an interator and a composite design pattern. At present, a number of classes utilize Bio::Root::Vector's composite-like behavior to implement a composite pattern (Bio::SeqManager.pm, for example). This is not necessarily ideal and is expected to change.
For a usage demo of Bio::Root::Vector.pm, see:
http://bio.perl.org/Core/Examples/Root_object/Vector
Bio::Root::Vector.pm does not directly inherit from Bio::Root::Object.pm but creates an manager object which does.
By default, all Vectors are doubly-linked lists. This relieves one from the burden of worrying about whether a given Vector is single- or doubly-linked. However, when generating lots of Vectors or extremely large vectors, memory becomes an issue. In particular, signaling the GC to free the memory for an object when you want to remove it. Until this memory issue is resolved, the use of Vector.pm is not recommended for large projects.
Although it is not required, all objects within a vector are expected to derive from the same class (package). Support for heterogeneous Vectors has not been explicitly added (but they should work fine, as long as you know what you're doing).
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/MailList.shtml - About the mailing lists
Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via email or the web:
bioperl-bugs@bio.perl.org http://bio.perl.org/bioperl-bugs/
Steve Chervitz <sac@bioperl.org>
See the FEEDBACK section for where to send bug reports and comments.
Bio::Root::Vector.pm, 0.04
(Maybe) create an container class version of this module
to permit Vectors to be instantiated. Thus, instead of inherited from both Object.pm and Vector.pm, you could create a Vector.pm object.
Improve documentation.
Bio::Root::Object.pm - Core object Bio::Root::Err.pm - Error/Exception object Bio::Root::Global.pm - Manages global variables/constants http://bio.perl.org/Projects/modules.html - Online module documentation http://bio.perl.org/ - Bioperl Project Homepage
This module was developed under the auspices of the Saccharomyces Genome Database: http://genome-www.stanford.edu/Saccharomyces
Copyright (c) 1996-98 Steve Chervitz. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Methods beginning with a leading underscore are considered private and are intended for internal use by this module. They are not considered part of the public interface and are described here for documentation purposes only.
Purpose : To set an object's rank to an arbitrary numeric : value to be used for sorting the objects of the Vector. Usage : $self->set_rank(-RANK =>numeric_ranking_data, : -RANK_BY =>ranking_criterion_string); : or without the named parameters as (rank, rank_by). Throws : warning (if rank is set without also setting RANK_BY) Comments : It is redundant for every object to store RANK_BY data. : For this reason, the RANK_BY data is stored with the master : object associated with the vector.
See Also : rank(), rank_by()
Purpose : Call this method to clone the whole vector. : NOT calling this method will extract the vector element. Usage : $self->clone_vector(); Throws : Exception if argument is not an object reference. Comments : This method is usually called from within a module's : _set_clone() method for modules that inherit from : Bio::Root::Vector.pm.
Purpose : Returns the previous object in the Vector or undef : if on first object. Usage : $self->prev
Purpose : Returns the next object in the Vector or undef : if on last object. Usage : $self->next
Purpose : Returns the first object in the Vector or $self : if Vector size = 1. Usage : $self->first
Purpose : Returns the last object in the Vector or : $self if Vector size = 1. Usage : $self->last
Purpose : Returns the rank of the current object or 1 : if rank is not defined. Usage : $self->rank
See Also : set_rank()
Purpose : Returns the ranking criterion or the string 'order of addition' : if rankBy has not been explicitly set. Usage : $self->rank_by
Purpose : Returns the number of objects currently in the Vector. Usage : $self->size
Purpose : Returns the master object associated with the Vector. : (should probably be a private method). Usage : $self->master
Purpose : Test whether the current object is the first in the Vector. Usage : $self->is_first
Purpose : Test whether the current object is the last in the Vector. Usage : $self->is_last
Purpose : Retrives an object from the Vector given its name. : Returns undef if the object cannot be found. Usage : $self->get(object_name) Examples : $self->get($obj->name)
See Also : list()
Purpose : Add an object to the end of a Vector. Usage : $self->add(object_reference)
See also : insert(), remove()
Purpose : Remove the current object from the Vector. Usage : $self->remove([-RET=>'first'|'last'|'next'|'prev'], [-UPDATE => 0|1]) Returns : The first, last, next, or previous object in the Vector : depending on the value of the -RET parameter. : Default = next. Argument : Named parameters: (TAGS CAN BE ALL UPPER OR ALL LOWER CASE) : -RET => string: 'first', 'last', 'prev' 'next' : THis indicates the object to be returned. : -UPDATE => boolean, if non-zero all objects in the vector : will be re-ranked. Comments : The -UPDATE parameter should be set to true to force a re-updating : of the rank data for each object. (default = 0, no update).
See Also : add(), insert(), shift(), chop()
Purpose : Remove all objects currently in the Vector. Usage : $self->remove_all
See Also : remove(), shift(), chop()
Purpose : Remove the first object from the Vector. : This is a wrapper for remove(). Usage : $self->shift([-RET=>'first'|'last'|'next'|'prev']) Returns : The object returned by remove().
See Also : remove(), chop()
Purpose : Remove the last object from the Vector. : This is a wrapper for remove(). Usage : $self->chop([-RET=>'first'|'last'|'next'|'prev']) Returns : The object returned by remove().
See Also : remove(), shift()
Purpose : Insert a new object into the vector relative to the current object. Usage : $self->insert(object_ref, ['before'|'after']) Examples : $self->insert($obj) # Default insert after $self : $self->insert($obj,'before') Returns : The new number of objects in the vector (int). Throws : exception if the first argument is not a reference.
See Also : add(), remove()
Purpose : Returns objects in the Vector as an array or array slice. Usage : $self->list([starting_object|'first'] [,ending_object|'last']) Examples : $self->list : $self->list('first',$self->prev)
See Also : get()
Purpose : Sort the objects in the Vector. Usage : $self->sort(['rank'|'name'], [reverse]) Returns : The last object of the sorted Vector. Argument : First argument can be 'name' or 'rank' to sort on : the object's name or rank data member, respectively. : If reverse is non-zero, sort will be in reverse order. Example : $self->sort() # Default sort by rank, not reverse. : $self->sort('name','reverse')
Purpose : Determine if at least one object in the Vector is valid. Usage : $self->valid_any Status : Deprecated. Comments : A non-valid object should throw an exception that must be : be caught an dealt with on the spot.
See Also : Bio::Root::Object::valid()
Purpose : Determine if all objects in the Vector are valid. Usage : $self->valid_all Comments : A non-valid object should throw an exception that must be : be caught an dealt with on the spot.
Information about the various data members of this module is provided for those wishing to modify or understand the code. Two things to bear in mind:
All data members are prefixed with an underscore to signify that they are private. Always use accessor methods. If the accessor doesn't exist or is inadequate, create or modify an accessor (and let me know, too!).
It is easy for this documentation to become obsolete as this module is still evolving. Always double check this info and search for members not described here.
Bio::Root::Vector.pm objects currently cannot be instantiated. Vector.pm must be inherited along with Bio::Root::Object.pm (or an object that provides a constructor). Vector.pm defines the following fields:
FIELD VALUE ------------------------------------------------------------------------ _prev Reference to the previous object in the Vector. _next Reference to the next object in the Vector. _rank Rank relative to other objects in the Vector. Default rank = chronological order of addition to the Vector. _master A reference to an Bio::Root::Object that acts as a manager for the given Vector. There is only one master per Vector. A master object is only needed when the Vector size is >1. The master object manages the following Vector data: _first - Reference to the first object in the Vector. _last - Reference to the last object in the Vector. _size - Total number of objects in the Vector. _rankBy - Criteria used to rank the object. Default: chronological order of addition. _index - Hash reference for quick access to any object based on its name. Bio::Root::Object{'_err'} - Holds any errors affecting the Vector as a whole.
To install Bio::Seq, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Seq
CPAN shell
perl -MCPAN -e shell install Bio::Seq
For more information on module installation, please visit the detailed CPAN module installation guide.