Bio::Seq::SeqBuilder - Configurable object builder for sequence stream parsers use Bio::SeqIO; # usually you won't instantiate this yourself -- a SeqIO object # will have one already my $seqin = Bio::SeqIO->new(-fh => \*STDIN, -format => "genbank"); my $builder = $seqin->sequence_builder(); # if you need only sequence, id, and description (e.g. for # conversion to FASTA format): $builder->want_none(); $builder->add_wanted_slot('display_id','desc','seq'); # if you want everything except the sequence and features $builder->want_all(1); # this is the default if it's untouched $builder->add_unwanted_slot('seq','features'); # if you want only human sequences shorter than 5kb and skip all # others $builder->add_object_condition(sub { my $h = shift; return 0 if $h->{'-length'} > 5000; return 0 if exists($h->{'-species'}) && ($h->{'-species'}->binomial() ne "Homo sapiens"); return 1; }); # when you are finished with configuring the builder, just use # the SeqIO API as you would normally while(my $seq = $seqin->next_seq()) { # do something } This is an implementation of Bio::Factory::ObjectBuilderI used by parsers of rich sequence streams. It provides for a relatively easy-to-use configurator of the parsing flow. Configuring the parsing process may be for you if you need much less information, or much less sequences, than the stream actually contains. Configuration can in both cases speed up the parsing time considerably, because unwanted sections or the rest of unwanted sequences are skipped over by the parser. See the methods of the class-specific implementation section for further documentation of what can be configured.

Mailing Lists
User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated. bioperl-l@bioperl.org - General discussion http://bioperl.org/MailList.shtml - About the mailing lists

Reporting Bugs
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via email or the web: bioperl-bugs@bioperl.org http://bugzilla.bioperl.org/ Email hlapp at gmx.net Additional contributors names and emails here The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new
Title : new Usage : my $obj = new Bio::Seq::SeqBuilder(); Function: Builds a new Bio::Seq::SeqBuilder object Returns : an instance of Bio::Seq::SeqBuilder Args :

want_slot
Title : want_slot Usage : Function: Whether or not the object builder wants to populate the specified slot of the object to be built. The slot can be specified either as the name of the respective method, or the initialization parameter that would be otherwise passed to new() of the object to be built. Note that usually only the parser will call this method. Use add_wanted_slots and add_unwanted_slots for configuration. Example : Returns : TRUE if the object builder wants to populate the slot, and FALSE otherwise. Args : the name of the slot (a string)

add_slot_value
Title : add_slot_value Usage : Function: Adds one or more values to the specified slot of the object to be built. Naming the slot is the same as for want_slot(). The object builder may further filter the content to be set, or even completely ignore the request. If this method reports failure, the caller should not add more values to the same slot. In addition, the caller may find it appropriate to abandon the object being built altogether. This implementation will allow the caller to overwrite the return value from want_slot(), because the slot is not checked against want_slot(). Note that usually only the parser will call this method, but you may call it from anywhere if you know what you are doing. A derived class may be used to further manipulate the value to be added. Example : Returns : TRUE on success, and FALSE otherwise Args : the name of the slot (a string) parameters determining the value to be set OR alternatively, a list of slotname/value pairs in the style of named parameters as they would be passed to new(), where each element at an even index is the parameter (slot) name starting with a dash, and each element at an odd index is the value of the preceding name.

want_object
Title : want_object Usage : Function: Whether or not the object builder is still interested in continuing with the object being built. If this method returns FALSE, the caller should not add any more values to slots, or otherwise risks that the builder throws an exception. In addition, make_object() is likely to return undef after this method returned FALSE. Note that usually only the parser will call this method. Use add_object_condition for configuration. Example : Returns : TRUE if the object builder wants to continue building the present object, and FALSE otherwise. Args : none

make_object
Title : make_object Usage : Function: Get the built object. This method is allowed to return undef if no value has ever been added since the last call to make_object(), or if want_object() returned FALSE (or would have returned FALSE) before calling this method. For an implementation that allows consecutive building of objects, a caller must call this method once, and only once, between subsequent objects to be built. I.e., a call to make_object implies 'end_object.' Example : Returns : the object that was built Args : none These methods allow to conveniently configure this sequence object builder as to which slots are desired, and under which circumstances a sequence object should be abandoned altogether. The default mode is want_all(1), which means the builder will report all slots as wanted that the object created by the sequence factory supports. You can add specific slots you want through add_wanted_slots(). In most cases, you will want to call want_none() before in order to relax zero acceptance through a list of wanted slots. Alternatively, you can add specific unwanted slots through add_unwanted_slots(). In this case, you will usually want to call want_all(1) before (which is the default if you never touched the builder) to restrict unrestricted acceptance. I.e., want_all(1) means want all slots except for the unwanted, and want_none() means only those explicitly wanted. If a slot is in both the unwanted and the wanted list, the following rules hold. In want-all mode, the unwanted list overrules. In want-none mode, the wanted list overrides the unwanted list. If this is confusing to you, just try to avoid having slots at the same time in the wanted and the unwanted lists.

get_wanted_slots
Title : get_wanted_slots Usage : $obj->get_wanted_slots($newval) Function: Get the list of wanted slots Example : Returns : a list of strings Args :

add_wanted_slot
Title : add_wanted_slot Usage : Function: Adds the specified slots to the list of wanted slots. Example : Returns : TRUE Args : an array of slot names (strings)

remove_wanted_slots
Title : remove_wanted_slots Usage : Function: Removes all wanted slots added previously through add_wanted_slots(). Example : Returns : the previous list of wanted slot names Args : none

get_unwanted_slots
Title : get_unwanted_slots Usage : $obj->get_unwanted_slots($newval) Function: Get the list of unwanted slots. Example : Returns : a list of strings Args : none

add_unwanted_slot
Title : add_unwanted_slot Usage : Function: Adds the specified slots to the list of unwanted slots. Example : Returns : TRUE Args : an array of slot names (strings)

remove_unwanted_slots
Title : remove_unwanted_slots Usage : Function: Removes the list of unwanted slots added previously through add_unwanted_slots(). Example : Returns : the previous list of unwanted slot names Args : none

want_none
Title : want_none Usage : Function: Disables all slots. After calling this method, want_slot() will return FALSE regardless of slot name. This is different from removed_wanted_slots() in that it also sets want_all() to FALSE. Note that it also resets the list of unwanted slots in order to avoid slots being in both lists. Example : Returns : TRUE Args : none

want_all
Title : want_all Usage : $obj->want_all($newval) Function: Whether or not this sequence object builder wants to populate all slots that the object has. Whether an object supports a slot is generally determined by what can() returns. You can add additional 'virtual' slots by calling add_wanted_slot. This will be ON by default. Call $obj->want_none() to disable all slots. Example : Returns : TRUE if this builder wants to populate all slots, and FALSE otherwise. Args : on set, new value (a scalar or undef, optional)

get_object_conditions
Title : get_object_conditions Usage : Function: Get the list of conditions an object must meet in order to be 'wanted.' See want_object() for where this is used. Conditions in this implementation are closures (anonymous functions) which are passed one parameter, a hash reference the keys of which are equal to initialization paramaters. The closure must return TRUE to make the object 'wanted.' Conditions will be implicitly ANDed. Example : Returns : a list of closures Args : none

add_object_condition
Title : add_object_condition Usage : Function: Adds a condition an object must meet in order to be 'wanted.' See want_object() for where this is used. Conditions in this implementation must be closures (anonymous functions). These will be passed one parameter, which is a hash reference with the sequence object initialization paramters being the keys. Conditions are implicitly ANDed. If you want other operators, perform those tests inside of one closure instead of multiple. This will also be more efficient. Example : Returns : TRUE Args : the list of conditions

remove_object_conditions
Title : remove_object_conditions Usage : Function: Removes the conditions an object must meet in order to be 'wanted.' Example : Returns : The list of previously set conditions (an array of closures) Args : none

sequence_factory
Title : sequence_factory Usage : $obj->sequence_factory($newval) Function: Get/set the sequence factory to be used by this object builder. Example : Returns : the Bio::Factory::SequenceFactoryI implementing object to use Args : on set, new value (a Bio::Factory::SequenceFactoryI implementing object or undef, optional)