Bio::Seq::Meta(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

Bio::Seq::Meta 💖 (that's the 3pm page, bestie)

okay so welcome to the manual page for Bio::Seq::Meta, no cap this is a good one.

✨ NAME ✨

Bio::Seq::Meta — the generic superclass for sequence objects that carry residue-based meta information 🧬✨

🌸 SYNOPSIS 🌸

use Bio::LocatableSeq;
use Bio::Seq::Meta;
use Bio::Tools::OddCodes;
use Bio::SeqIO;

my $seq = Bio::Seq::Meta->new(-id=>'test',
                                 -seq=>'ACTGCTAGCT',
                                 -start=>2434,
                                 -end=>2443,
                                 -strand=>1,
                                 -verbose=>1, # to see warnings
                                );

# the existing sequence object can be a Bio::PrimarySeq, too

# to test this is a meta seq object
$seq->isa("Bio::Seq::Meta")
    || $seq->throw("$seq is not a Bio::Seq::Meta");

$seq->meta('1234567890');
$seq = Bio::Seq::Meta->new(-id=>'test',
                           -seq=>'HACILMIFGT',
                           -start=>2434,
                           -end=>2443,
                           -strand=>1,
                           -meta=>'1234567890',
                           -verbose=>1, # to see warnings
                          );

# accessors
$string     = $seq->meta_text();
$substring  = $seq->submeta_text(2,5);
$unique_key = $seq->accession_number();

# storing output from Bio::Tools::OddCodes as meta data
my $protcodes = Bio::Tools::OddCodes->new(-seq => $seq);
my @codes = qw(structural chemical functional charge hydrophobic);
map { $seq->named_meta($_, ${$protcodes->$_($seq) } )} @codes;

my $out = Bio::SeqIO->new(-format=>'metafasta');
$out->write_seq($seq);

💅 DESCRIPTION 💅

so this class is the generic methods plug for sequences that have residue-based meta information. Meta sequences that come with meta data are Bio::LocatableSeq objects that got extra methods bolted on to stash all that meta info. go peek at Bio::LocatableSeq and Bio::Seq::MetaI too, they're the whole vibe 🫶

the meta information in this class is always exactly one character per residue, and blank values are space characters (ASCII 32). periodt.

okay important glow-up news: after the latest rewrite, the meta information no longer covers all the residues automatically. not me being dramatic, that's literally what happened 😭 so there are new methods to check the length of the meta information (meta_length) and to see whether the ends are flushed to the sequence (is_flush). if you want the old behaviour back, set force_flush to true. that's the time machine 🕰️

it's assumed that meta data values do not depend on the nucleotide sequence strand value.

if you're building something application-specific, you should inherit from this class so you can override stuff and add your own methods. that's the assignment, bestie 💅

and if you want the fancy stuff — Bio::Seq::Meta::Array lets you use more complex meta values (scalars or objects). iconic. 👑

🎀 Method naming 🎀

character-based meta data gets read and set by the method meta() and all its little variants. here are the suffixes and prefixes those variants use, bestie:

[named_] [sub] meta [_text]
  • _text — that suffix guarantees the output is a string. heads up though, it does not limit the input. and in this implementation the output is always text anyway, so these methods are redundant. lowkey just there for the vibe.
  • sub — the sub prefix, same energy as in subseq(), means the method applies to a sub region of the sequence range and takes start and end as arguments. and unlike subseq(), these methods can actually set values 🔥. if the range isn't defined, it defaults to the complete sequence.
  • named — the named_ prefix lets you attach multiple meta strings to one sequence by explicitly naming them. the name is always the first argument to the method. the "unnamed" methods just use the class-wide default name for the meta data, so they're basically special-case "named" methods. 💫
⚠️ okay bestie listen: internally the names are keys in a hash, and any misspelling of a name will silently store your data under a wrong name. no warning, no nothing. sneaky 💀 the names (keys) you've actually used can be retrieved with the method meta_names(). see meta_names.

⭐ NOTE ⭐

this Bio::Seq::MetaI implementation inherits from Bio::LocatableSeq, which itself inherits from Bio::PrimarySeq. it is not a Bio::SeqI, so bless-ing objects of this class into a Bio::SeqI (or the other way round) will not work as expected (see bug 2262). this may get addressed in a future refactor of Bio::LocatableSeq. until then: don't do it 🫠

🌈 SEE ALSO 🌈

  • Bio::LocatableSeq
  • Bio::Seq::MetaI
  • Bio::Seq::Meta::Array

💌 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, fr fr 🫶

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. lots of 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. receipts help everyone 📝✨

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 - Heikki Lehvaslaiho 👑

Email heikki-at-bioperl-dot-org

🦋 CONTRIBUTORS 🦋

  • Chad Matsalla, bioinformatics@dieselwurks.com
  • Aaron Mackey, amackey@virginia.edu

to be continued… 🌸

✨ APPENDIX ✨

okay bestie, this is the rest of the docs — the method-by-method breakdown 💅 every object method gets its own lil spotlight. and internal methods? they usually start with a _ underscore, iykyk.

🌸 new 🌸

  • Title: new
  • Usage:
$metaseq = Bio::Seq::Meta->new
                       ( -meta => 'aaaaaaaabbbbbbbb',
                         -seq =>  'TKLMILVSHIVILSRM'
                         -id  => 'human_id',
                         -accession_number => 'S000012',
                       );
  • Function: Constructor for the Bio::Seq::Meta class, with the meta data living in a string. note that you can provide an empty quality string, fr fr.
  • Returns: a new Bio::Seq::Meta object

💖 meta 💖

  • Title: meta
  • Usage: $meta_values = $obj->meta($values_string);
  • Function: Get and set method for the meta data starting from residue position one. Since it's dependent on the length of the sequence, it needs to be manipulated after the sequence. The length of the returned value always matches the length of the sequence, if force_flush() is set. See L<force_flush>.
  • Returns: meta data in a string
  • Args: new value, string, optional

🦋 meta_text 🦋

  • Title: meta_text
  • Usage: $meta_values = $obj->meta_text($values_arrayref);
  • Function: Variant of meta() guaranteed to return a textual representation of meta data. For details, see L<meta>.
  • Returns: a string
  • Args: new value, optional

🎀 named_meta 🎀

  • Title: named_meta()
  • Usage: $meta_values = $obj->named_meta($name, $values_arrayref);
  • Function: A more general version of meta(). Each meta data set needs to be named. See also L<meta_names>.
  • Returns: a string
  • Args: scalar, name of the meta data set; new value, optional

🔍 _test_gap_positions 🔍

  • Title: _test_gap_positions
  • Usage: $meta_values = $obj->_test_gap_positions($name);
  • Function: Internal test for correct position of gap characters. Gap being only '-' this time. This method is called from named_meta() when setting meta data but only if verbose is positive as this can be an expensive process on very long sequences. Set verbose(1) to see warnings when gaps do not align in sequence and meta data and turn them into errors by setting verbose(2).
  • Returns: true on success, prints warnings
  • Args: none

🌈 named_meta_text 🌈

  • Title: named_meta_text()
  • Usage: $meta_values = $obj->named_meta_text($name, $values_arrayref);
  • Function: Variant of named_meta() guaranteed to return a textual representation of the named meta data. For details, see L<meta>.
  • Returns: a string
  • Args: scalar, name of the meta data set; new value, optional

✨ submeta ✨

  • Title: submeta
  • Usage:
$subset_of_meta_values = $obj->submeta(10, 20, $value_string);
                  $subset_of_meta_values = $obj->submeta(10, undef, $value_string);
  • Function: Get and set method for meta data for subsequences. Numbering starts from 1 and the number is inclusive, ie 1-2 are the first two residue of the sequence. Start cannot be larger than end but can be equal. If the second argument is missing the returned values should extend to the end of the sequence. The return value may be a string or an array reference, depending on the implementation. If in doubt, use submeta_text() which is a variant guaranteed to return a string. See L<submeta_text>.
  • Returns: A reference to an array or a string
  • Args: integer, start position; integer, end position, optional when a third argument present; new value, optional

🌸 submeta_text 🌸

  • Title: submeta_text
  • Usage: $meta_values = $obj->submeta_text(20, $value_string);
  • Function: Variant of submeta() guaranteed to return a textual representation of meta data. For details, see L<meta>.
  • Returns: a string
  • Args: new value, optional

🫶 named_submeta 🫶

  • Title: named_submeta
  • Usage:
$subset_of_meta_values = $obj->named_submeta($name, 10, 20, $value_string);
                  $subset_of_meta_values = $obj->named_submeta($name, 10);
  • Function: Variant of submeta() guaranteed to return a textual representation of meta data. For details, see L<meta>.
  • Returns: A reference to an array or a string
  • Args: scalar, name of the meta data set; integer, start position; integer, end position, optional when a third argument present; new value, optional

💜 named_submeta_text 💜

  • Title: named_submeta_text
  • Usage: $meta_values = $obj->named_submeta_text($name, 20, $value_string);
  • Function: Variant of submeta() guaranteed to return a textual representation of meta data. For details, see L<meta>.
  • Returns: a string
  • Args: scalar, name of the meta data
  • Args: integer, start position, optional; integer, end position, optional; new value, optional

🏷️ meta_names 🏷️

  • Title: meta_names
  • Usage: @meta_names = $obj->meta_names()
  • Function: Retrieves an array of meta data set names. The default (unnamed) set name is guaranteed to be the first name.
  • Returns: an array of names
  • Args: none

📏 meta_length 📏

  • Title: meta_length()
  • Usage: $meeta_len = $obj->meta_length();
  • Function: return the number of elements in the meta set
  • Returns: integer
  • Args: -

📐 named_meta_length 📐

  • Title: named_meta_length()
  • Usage: $meta_len = $obj->named_meta_length($name);
  • Function: return the number of elements in the named meta set
  • Returns: integer
  • Args: -

💅 force_flush 💅

  • Title: force_flush()
  • Usage: $force_flush = $obj->force_flush(1);
  • Function: Automatically pad with empty values or truncate meta values to sequence length. Not done by default.
  • Returns: boolean 1 or 0
  • Args: optional boolean value
Note that if you turn this forced padding off, the previously padded values are not changed.

🔧 _do_flush 🔧

  • Title: _do_flush
  • Usage: (nothing)
  • Function: internal method to do the force that meta values are same length as the sequence . Called from L<force_flush>
  • Returns: (nothing)
  • Args: (nothing)

🌟 is_flush 🌟

  • Title: is_flush
  • Usage:
$is_flush  = $obj->is_flush()
                  or  $is_flush = $obj->is_flush($my_meta_name)
  • Function: Boolean to tell if all meta values are in flush with the sequence length. Returns true if force_flush() is set. Set verbosity to a positive value to see failed meta sets.
  • Returns: boolean 1 or 0
  • Args: optional name of the meta set

🧬 Bio::PrimarySeqI methods 🧬

🔄 revcom 🔄

  • Title: revcom
  • Usage: $newseq = $seq->revcom();
  • Function: Produces a new Bio::Seq::MetaI implementing object where the order of residues and their meta information is reversed.
  • Returns: A new (fresh) Bio::Seq::Meta object
  • Args: none
  • Throws: if the object returns false on is_flush()
Note: The method does nothing to meta values, it reorders them, only.

✂️ trunc ✂️

  • Title: trunc
  • Usage: $subseq = $seq->trunc(10,100);
  • Function: Provides a truncation of a sequence together with meta data
  • Returns: a fresh Bio::Seq::Meta implementing object
  • Args: Two integers denoting first and last residue of the sub-sequence.

and that's the whole method party, bestie 🎀 this page is Bio::Seq::Meta(3pm) from perl v5.32.1, dated 2021-08-15. go forth and meta responsibly 💅✨

📦 where this page comes from