Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Bio::Seq::SeqBuilder(3User Contributed Perl DocumentatiBio::Seq::SeqBuilder(3)

NAME
       Bio::Seq::SeqBuilder - Configurable object builder for sequence stream
       parsers

SYNOPSIS
	  use Bio::SeqIO;

	  # usually you	won't instantiate this yourself	- a SeqIO object -
	  # you	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
	  }

DESCRIPTION
       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 sequence, 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. This	configuration could also conserve memory if
       you're running out of available RAM.

       See the methods of the class-specific implementation section for
       further documentation of	what can be configured.

FEEDBACK
   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/wiki/Mailing_lists	- About	the mailing lists

   Support
       Please direct usage questions or	support	issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and
       reponsive experts will be able look at the problem and quickly address
       it. Please include a thorough description of the	problem	with code and
       data examples if	at all possible.

   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 the
       web:

	 https://github.com/bioperl/bioperl-live/issues

AUTHOR - Hilmar	Lapp
       Email hlapp at gmx.net

APPENDIX
       The rest	of the documentation details each of the object	methods.
       Internal	methods	are usually preceded with a _

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

Methods	for implementing Bio::Factory::ObjectBuilderI
   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

Implementation specific	methods
       These methods allow one 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
		  parameters. 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 parameters 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

Methods	to control what	type of	object is built
   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)

perl v5.32.0			  2019-12-07	       Bio::Seq::SeqBuilder(3)

NAME | SYNOPSIS | DESCRIPTION | FEEDBACK | AUTHOR - Hilmar Lapp | APPENDIX | Methods for implementing Bio::Factory::ObjectBuilderI | Implementation specific methods | Methods to control what type of object is built

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Seq::SeqBuilder&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help