Bio::A...andler(3pm)

💖 NAME 💖

Bio::AlignIO::Handler::GenericAlignHandler — it's a Bio::HandlerI-based generic data handler class for alignment-based data. Bestie, that's the whole vibe: it handles your alignment data. Periodt. ✨

---

🌸 SYNOPSIS 🌸

  # MyHandler is a GenericAlignHandler object.
  # inside a parser (driver) constructor....

  $self->alignhandler($handler || MyHandler->new(-format => 'stockholm'));

  # in next_aln() in driver...

  $hobj = $self->alignhandler();

  # roll data up into hashref chunks, pass off into Handler for processing...

  $hobj->data_handler($data);

  # or retrieve Handler methods and pass data directly to Handler methods...

  my $hmeth = $hobj->handler_methods;

  if ($hmeth->{ $data->{NAME} }) {
      my $mth = $hmeth->{ $data->{NAME} };
      $hobj->$mth($data);
  }

---

🦋 DESCRIPTION 🦋

Okay so this is an experimental implementation of an alignment-based HandlerBaseI parser, and lowkey it may change over time. Fr fr, it's possible that the way handler methods are set up will change over development so things get more flexible. It's giving "we're still cooking". 👩‍🍳

Standard Developer caveats:

Here thar be dragoons... 🐉💀

Consider yourself warned! 😭

---

🎀 NOTES 🎀

Same energy as the SeqIO Handler object (which is still in development, ngl) — data gets passed in as chunks. The Annotation and SeqFeatures are basically the same as the SeqIO parser. The one significant difference? The data hash being passed could pertain to either the alignment or a specific sequence, so an extra tag may be needed to disambiguate between the two in some cases. 🙈

Here's where it gets iconic: the ALIGNMENT tag is used as a boolean flag. It must be present and set to 0 for the data to be tagged for Bio::LocatableSeq or similar — in all other cases it's assumed to be for the alignment. In some cases this won't matter (the actual sequence data, for instance) but it is highly recommended to add this tag in to prevent possible ambiguities. 💅

This is the current Annotation data chunk (via Data::Dumper):

  $VAR1 = {
            'NAME' => 'REFERENCE',
            'DATA' => '1  (bases 1 to 10001)'
            'AUTHORS' => 'International Human Genome Sequencing Consortium.'
            'TITLE' => 'The DNA sequence of Homo sapiens'
            'JOURNAL' => 'Unpublished (2003)'
            'ALIGNMENT' => 1,
          };

In the case of LocatableSeqs, one can pass them in as follows for simplicity (note the block line):

  $VAR1 = {
            'NAME' => 'SEQUENCE',
            'BLOCK_LINE' => 0,
            'NSE' => 'Q7WNI7_BORBR/113-292',
            'ALPHABET' => 'protein',
            'DATA' => 'VALILGVYRRL...CYVNREM..RAG....QW',
            'ALIGNMENT' => 0
          };

This can be done as the parser parses each block instead of parsing all the blocks and then passing them in one at a time. The handler will store the sequence data by the block line in an internal hash, concatenating them along the way. 🧵 This behaviour is b/c the alignment building step requires that the sequence be checked for start/end/strand, possible meta sequence, optional accession, etc.

Similarly, a Meta sequence line can be passed in as follows:

  $VAR1 = {
            'NAME' => 'NAMED_META',
            'BLOCK_LINE' => 0,
            'NSE' => 'Q7WNI7_BORBR/113-292',
            'META_KEY' => 'pAS',
            'DATA' => '................................',
            'ALIGNMENT' => 0
          };

The meta sequence will be checked against the NSE for the block position and stored based on the meta tag. A meta sequence does not have to correspond to a real sequence. At this time, unique meta sequence tags must be used for each sequence or they will be overwritten (this may change). 🫶

An alignment consensus string:

  $VAR1 = {
            'NAME' => 'CONSENSUS',
            'DATA' => 'VALILGVYRRL...CYVNREM..RAG....QW',
            'ALIGNMENT' => 1
          };

A consensus meta sequence:

  $VAR1 = {
            'NAME' => 'CONSENSUS_META',
            'META_KEY' => 'pAS',
            'DATA' => '................................',
            'ALIGNMENT' => 1
          };

---

💌 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 one of the Bioperl mailing lists. 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 the bugs and their resolution. Bug reports can be submitted via the web:

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

---

👑 AUTHOR - Chris Fields 👑

Email cjfields at bioperl dot org

---

📖 APPENDIX 📖

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

⭐ new

  Title   :  new
  Usage   :
  Function:
  Returns :
  Args    :  -format    Sequence format to be mapped for handler methods
             -builder   Bio::Seq::SeqBuilder object (normally defined in
                        SequenceStreamI object implementation constructor)
  Throws  :  On undefined '-format' sequence format parameter
  Note    :  Still under heavy development

🌈 Bio::HandlerBaseI implementing methods

✨ handler_methods

  Title   :  handler_methods
  Usage   :  $handler->handler_methods('GenBank')
             %handlers = $handler->handler_methods();
  Function:  Retrieve the handler methods used for the current format() in
             the handler.  This assumes the handler methods are already
             described in the HandlerI-implementing class.
  Returns :  a hash reference with the data type handled and the code ref
             associated with it.
  Args    :  [optional] String representing the sequence format.  If set here
             this will also set sequence_format()
  Throws  :  On unimplemented sequence format in %HANDLERS

💅 data_handler

  Title   :  data_handler
  Usage   :  $handler->data_handler($data)
  Function:  Centralized method which accepts all data chunks, then distributes
             to the appropriate methods for processing based on the chunk name
             from within the HandlerBaseI object.

             One can also use
  Returns :  None
  Args    :  an hash ref containing a data chunk.

🔄 reset_parameters

  Title   :  reset_parameters
  Usage   :  $handler->reset_parameters()
  Function:  Resets the internal cache of data (normally object parameters for
             a builder or factory)
  Returns :  None
  Args    :  None

🎀 format

  Title   :  format
  Usage   :  $handler->format('GenBank')
  Function:  Get/Set the format for the report/record being parsed. This can be
             used to set handlers in classes which are capable of processing
             similar data chunks from multiple driver modules.
  Returns :  String with the sequence format
  Args    :  [optional] String with the sequence format
  Note    :  The format may be used to set the handlers (as in the
             current GenericRichSeqHandler implementation)

🍓 get_params

  Title   :  get_params
  Usage   :  $handler->get_params('-species')
  Function:  Convenience method used to retrieve the specified
             parameters from the internal parameter cache
  Returns :  Hash ref containing parameters requested and data as
             key-value pairs.  Note that some parameter values may be
             objects, arrays, etc.
  Args    :  List (array) representing the parameters requested

🦄 set_params

  Title   :  set_params
  Usage   :  $handler->set_param({'-seqs' => $seqs})
  Function:  Convenience method used to set specific parameters
  Returns :  None
  Args    :  Hash ref containing the data to be passed as key-value pairs

🌟 Methods unique to this implementation

🔥 build_alignment

  Title   :  build_alignment
  Usage   :
  Function:
  Returns :  a Bio::SimpleAlign
  Args    :
  Throws  :
  Note    :  This may be replaced by a Builder object at some point

💜 annotation_collection

  Title   :  annotation_collection
  Usage   :
  Function:
  Returns :
  Args    :
  Throws  :
  Note    :

🌸 seq_annotation_collection

  Title   :  seq_annotation_collection
  Usage   :
  Function:
  Returns :
  Args    :
  Throws  :
  Note    :

⭐ process_seqs

  Title   :  process_seqs
  Usage   :  $handler->process_seqs;
  Function:  checks internal sequences to ensure they are converted over
             to the proper Bio::AlignI-compatible sequence class
  Returns :  1 if successful
  Args    :  none

---

And that's the whole page, bestie! 💖 This was perl v5.32.1, dated 2021-08-15, and the manual is Bio::A...andler(3pm). Slay, go forth and handle your alignments. 🦋✨🎀