Bio::SeqUtils(3pm)

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

💖 Bio::SeqUtils 💖

okay bestie, welcome to Bio::SeqUtils(3pm) — it's part of the User Contributed Perl Documentation family and it is so useful, like genuinely. it's a little toolbox of extra methods for PrimarySeq objects. let's get into it 🧚

✨ NAME ✨

Bio::SeqUtils — extra methods for PrimarySeq objects, because the base ones weren't giving enough 💅

🌸 SYNOPSIS 🌸

use Bio::SeqUtils;
# get a Bio::PrimarySeqI compliant object, $seq, somehow
$util = Bio::SeqUtils->new();
$polypeptide_3char = $util->seq3($seq);
# or
$polypeptide_3char = Bio::SeqUtils->seq3($seq);

# set the sequence string (stored in one char code in the object)
Bio::SeqUtils->seq3($seq, $polypeptide_3char);

# translate a sequence in all six frames
@seqs = Bio::SeqUtils->translate_6frames($seq);

# inplace editing of the sequence
Bio::SeqUtils->mutate($seq,
                      Bio::LiveSeq::Mutation->new(-seq => 'c',
                                                  -pos => 3
                                                 ));
# mutate a sequence to desired similarity%
$newseq = Bio::SeqUtils-> evolve
    ($seq, $similarity, $transition_transversion_rate);

# concatenate two or more sequences with annotations and features,
# the first sequence will be modified
Bio::SeqUtils->cat(@seqs);
my $catseq=$seqs[0];

# truncate a sequence, retaining features and adjusting their
# coordinates if necessary
my $truncseq = Bio::SeqUtils->trunc_with_features($seq, 100, 200);

# reverse complement a sequence and its features
my $revcomseq = Bio::SeqUtils->revcom_with_features($seq);

# simulate cloning of a fragment into a vector. Cut the vector at
# positions 1000 and 1100 (deleting positions 1001 to 1099) and
# "ligate" a fragment into the sites. The fragment is
# reverse-complemented in this example (option "flip").
# All features of the vector and fragment are preserved and
# features that are affected by the deletion/insertion are
# modified accordingly.
# $vector and $fragment must be Bio::SeqI compliant objects
my $new_molecule = Bio::Sequtils->ligate(
  -vector => $vector,
  -fragment => $fragment,
  -left => 1000,
  -right => 1100,
  -flip => 1
);

# delete a segment of a sequence (from pos 1000 to 1100, inclusive),
# again preserving features and annotations
my $new_molecule = Bio::SeqUtils->cut( $seq, 1000, 1100 );

# insert a fragment into a recipient between positions 1000 and
# 1001. $recipient is a Bio::SeqI compliant object
my $new_molecule =  Bio::SeqUtils::PbrTools->insert(
  $recipient_seq,
  $fragment_seq,
  1000
);

like, look at all those slashes. it's giving utility belt 🦋

🌈 DESCRIPTION 🌈

so this class is literally just a holder of methods that work on Bio::PrimarySeqI-compliant sequence objects, e.g. Bio::PrimarySeq and Bio::Seq. that's the whole vibe. these methods are not part of the Bio::PrimarySeqI interface, and they should in general not be essential to the primary function of sequence objects. like, they're the fun extras, not the core curriculum. if you're thinking of adding essential functions, it might be better to create your own sequence class 👑 See Bio::PrimarySeqI, Bio::PrimarySeq, and Bio::Seq for more.

the methods take as their first argument a sequence object. and here's the cute part: it is possible to use methods without first creating a SeqUtils object, i.e. use it as an anonymous hash. no new() required, we're low maintenance 💅

the first two methods, seq3() and seq3in(), give out or read in protein sequences coded in three letter IUPAC amino acid codes. iconic.

the next two methods, translate_3frames() and translate_6frames(), wrap around the standard translate method to give back an array of three forward or all six frame translations. six frames?? main character energy fr fr.

the mutate() method mutates the sequence string with a mutation description object.

the cat() method concatenates two or more sequences. the first sequence is modified by addition of the remaining sequences. all annotations and sequence features will be transferred. 🫶

the revcom_with_features() and trunc_with_features() methods are similar to the revcom() and trunc() methods from Bio::Seq, but also adjust any features associated with the sequence as appropriate. the way that they also fix your features?? obsessed.

there are also methods that simulate molecular cloning with rich sequence objects. the delete() method cuts a segment out of a sequence and re-joins the left and right fragments (like splicing or digesting and re-ligating a molecule). positions (and types) of sequence features are adjusted accordingly: features that span the deleted segment are converted to split featuress to indicate the disruption. (sub)features that extend into the deleted segment are truncated. a new molecule is created and returned. ✨

the insert() method inserts a fragment (which can be a rich Bio::Seq object) into another sequence object adding all annotations and features to the final product. features that span the insertion site are converted to split features to indicate the disruption. a new feature is added to indicate the inserted fragment itself. a new molecule is created and returned.

the ligate() method simulates digesting a recipient (vector) and ligating a fragment into it, which can also be flipped if needed. it is simply a combination of a deletion and an insertion step and returns a new molecule. the rules for modifying feature locations outlined above are also used here, e.g. features that span the cut sites are converted to split features with truncated sub-locations.

💌 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. (we love a supportive community 🥹)

  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. like, give them the receipts bestie 🧾

🐛 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 🫶

  • Roy R. Chaudhuri - roy.chaudhuri at gmail.com
  • Frank Schwach - frank.schwach@sanger.ac.uk

📖 APPENDIX 📖

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _

🎀 seq3

  • Title: seq3
  • Usage: $string = Bio::SeqUtils->seq3($seq)
  • Function: read only method that returns the amino acid sequence as a string of three letter codes. alphabet has to be 'protein'. output follows the IUPAC standard plus 'Ter' for terminator. any unknown character, including the default unknown character 'X', is changed into 'Xaa'. a noncoded aminoacid selenocystein is recognized (Sec, U).
  • Returns: a scalar
  • Args: character used for stop in the protein sequence — optional, defaults to '*'; string used to separate the output amino acid codes — optional, defaults to ''

🧬 seq3in

  • Title: seq3in
  • Usage: $seq = Bio::SeqUtils->seq3in($seq, 'MetGlyTer')
  • Function: method for changing of the sequence of a Bio::PrimarySeqI sequence object. the three letter amino acid input string is converted into one letter code. any unknown character triplet, including the default 'Xaa', is converted into 'X'.
  • Returns: Bio::PrimarySeq object
  • Args:
    • sequence string
    • optional character to be used for stop in the protein sequence, defaults to '*'
    • optional character to be used for unknown in the protein sequence, defaults to 'X'

✨ translate_3frames

  • Title: translate_3frames
  • Usage: @prots = Bio::SeqUtils->translate_3frames($seq)
  • Function: translate a nucleotide sequence in three forward frames. the IDs of the sequences are appended with '-0F', '-1F', '-2F'.
  • Returns: an array of seq objects
  • Args:
    • sequence object
    • same arguments as to Bio::PrimarySeqI::translate

🔥 translate_6frames

  • Title: translate_6frames
  • Usage: @prots = Bio::SeqUtils->translate_6frames($seq)
  • Function: translate a nucleotide sequence in all six frames. the IDs of the sequences are appended with '-0F', '-1F', '-2F', '-0R', '-1R', '-2R'.
  • Returns: an array of seq objects
  • Args:
    • sequence object
    • same arguments as to Bio::PrimarySeqI::translate

🧪 valid_aa

  • Title: valid_aa
  • Usage: my @aa = $table->valid_aa
  • Function: retrieves a list of the valid amino acid codes. the list is ordered so that first 21 codes are for unique amino acids. the rest are ['B', 'Z', 'X', '*'].
  • Returns: array of all the valid amino acid codes
  • Args: [optional] $code =>
    • 0 -> return list of 1 letter aa codes
    • 1 -> return list of 3 letter aa codes
    • 2 -> return associative array of both

💥 mutate

  • Title: mutate
  • Usage: Bio::SeqUtils->mutate($seq,$mutation1, $mutation2);
  • Function: inplace editing of the sequence.

the second argument can be a Bio::LiveSeq::Mutation object or an array of them. the mutations are applied sequentially checking only that their position is within the current sequence. insertions are inserted before the given position.

  • Returns: boolean
  • Args:
    • sequence object
    • mutation, a Bio::LiveSeq::Mutation object, or an array of them

see Bio::LiveSeq::Mutation.

🐾 cat

  • Title: cat
  • Usage:
Bio::SeqUtils->cat(@seqs);
my $catseq=$seqs[0];
  • Function: concatenates a list of Bio::Seq objects, adding them all on to the end of the first sequence. annotations and sequence features are copied over from any additional objects, and the coordinates of any copied features are adjusted appropriately.
  • Returns: a boolean
  • Args: array of sequence objects
note that annotations have no sequence locations. if you concatenate sequences with the same annotations they will all be added.

🎀 trunc_with_features 🎀

  • Title: trunc_with_features
  • Usage:
$trunc=Bio::SeqUtils->trunc_with_features($seq, $start, $end);
  • Function: it's giving Bio::Seq::trunc, but it keeps your features and adjusts their coordinates wherever that's necessary. Any feature that only partially overlaps the region gets its location changed into a Bio::Location::Fuzzy. That's it, that's the whole vibe. 💅
  • Returns: a brand new sequence object ✨
  • Args: a sequence object, start coordinate, end coordinate (inclusive)

🧚 delete 🧚

  • Title: delete
  • Function: cuts a segment out of a sequence and re-joins the left and right fragments — splicing energy, or digesting a molecule and re-ligating it, whatever your lab-flavoured metaphor is. The positions (and types) of the sequence features get adjusted accordingly, and the receipts are very specific:
    • Features that span the cut site get converted to split features to indicate the disruption.
    • Features that extend into the cut-out fragment get truncated. A whole new molecule is created and returned. 🫶
  • Usage:
my $cutseq =  Bio::SeqUtils::PbrTools->cut( $seq, 1000, 1100 );
  • Args:
    • a Bio::PrimarySeqI compliant object to cut
    • first nt of the segment to be deleted
    • last nt of the segment to be deleted
    • optional — a hash-ref of options:
      • clone_obj: if true, clone the input sequence object rather than calling "new" on the object's class
  • Returns: a new Bio::Seq object

🦋 insert 🦋

  • Title: insert
  • Function: inserts a fragment (a Bio::Seq object) into another sequence object, adding all annotations and features to the final product. Features that span the insertion site get converted to split features so the disruption is visible. A new feature is added to indicate the inserted fragment itself. A new molecule is created and returned. 😌
  • Usage:
# insert a fragment after pos 1000
my $insert_seq =  Bio::SeqUtils::PbrTools->insert(
  $recipient_seq,
  $fragment_seq,
  1000
);
  • Args:
    • recipient sequence (a Bio::PrimarySeqI compliant object)
    • a fragment to insert (Bio::PrimarySeqI compliant object)
    • insertion position (fragment is inserted to the right of this pos) — and heads up, pos=0 will prepend the fragment to the recipient
    • optional — a hash-ref of options:
      • clone_obj: if true, clone the input sequence object rather than calling "new" on the object's class
  • Returns: a new Bio::Seq object

🌸 ligate 🌸

  • Title: ligate
  • Function: pastes a fragment (which can also have features, yes bestie) into a recipient sequence between two "cut" sites, preserving features and adjusting their locations. It's a shortcut for deleting a segment from a sequence object and then inserting a fragment — made for simulating in-vitro cloning, where a recipient (a vector) gets digested and a fragment gets ligated into the recipient molecule. The fragment can even be flipped (reverse-complemented, features and all). A new sequence object is returned to represent the product of the reaction. 🧪

Features and annotations are transferred from the insert to the product, and features on the recipient are adjusted according to the methods delete and insert:

  • Features spanning the insertion site will be split up into two sub-locations.
  • (Sub-)features in the deleted region are themselves deleted.
  • (Sub-)features that extend into the deleted region are truncated.

The class of the product object depends on the class of the recipient (vector) sequence object. If it is not possible to instantiate a new object of that class, a Bio::PrimarySeq object is created instead. Slay by fallback. 💀

  • Usage:
# insert the flipped fragment between positions 1000 and 1100 of the
# vector, i.e. everything between these two positions is deleted and
# replaced by the fragment
my $new_molecule = Bio::Sequtils::Pbrtools->ligate(
  -recipient => $vector,
  -fragment => $fragment,
  -left => 1000,
  -right => 1100,
  -flip      => 1,
  -clone_obj => 1
);
  • Args:
    • recipient: the recipient/vector molecule
    • fragment: molecule that is to be ligated into the vector
    • left: left cut site (fragment will be inserted to the right of this position)
    • optional:
      • right: right cut site (fragment will be inserted to the left of this position). defaults to left+1
      • flip: boolean, if true, the fragment is reverse-complemented (including features) before inserting
      • clone_obj: if true, clone the recipient object to create the product instead of calling "new" on its class
  • Returns: a new Bio::Seq object of the ligated fragments 👑

🔧 _coord_adjust_deletion 🔧

  • Title: _coord_adjust_deletion
  • Function: recursively adjusts coordinates of seqfeatures on a molecule where a segment has been deleted.
    • (sub)features that span the deletion site become split features.
    • (sub)features that extend into the deletion site are truncated. A note is added to the feature to inform about the size and position of the deletion. 📝
  • Usage:
my $adjusted_feature = Bio::Sequtils::_coord_adjust_deletion(
  $feature,
  $start,
  $end
);
  • Args:
    • a Bio::SeqFeatureI compliant object
    • start (inclusive) position of the deletion site
    • end (inclusive) position of the deletion site
  • Returns: a Bio::SeqFeatureI compliant object

🔧 _coord_adjust_insertion 🔧

  • Title: _coord_adjust_insertion
  • Function: recursively adjusts coordinates of seqfeatures on a molecule where another sequence has been inserted. (sub)features that span the insertion site become split features, and a note is added about the size and position of the insertion. Features with an IN-BETWEEN location at the insertion site are lost — and honestly they can only exist between adjacent bases anyway, so there's nowhere for them to go. 😭
  • Usage:
my $adjusted_feature = Bio::Sequtils::_coord_adjust_insertion(
  $feature,
  $insert_pos,
  $insert_length
);
  • Args:
    • a Bio::SeqFeatureI compliant object
    • insertion position (insert to the right of this position)
    • length of inserted fragment
  • Returns: a Bio::SeqFeatureI compliant object

🍓 _single_loc_object_from_collection 🍓

  • Title: _single_loc_object_from_collection
  • Function: takes an array of location objects. Returns either a split location object if there's more than one location in the array, or just returns the single location if there's only one. Either way you get one thing back. 🫶
  • Usage:
my $loc = _single_loc_object_from_collection( @sublocs );
  • Args: array of Bio::Location objects
  • Returns: a single Bio::Location object containing all locations

🍓 _location_objects_from_coordinate_list 🍓

  • Title: _location_objects_from_coordinate_list
  • Function: takes an array-ref of start/end coordinates, a strand and a type, and returns a list of Bio::Location objects (Fuzzy by default, Simple in case of in-between coordinates). If the location type is not "IN-BETWEEN", individual types may be passed in for start and end location as per the Bio::Location::Fuzzy documentation. ✨
  • Usage:
my @loc_objs = $self->_location_objects_from_coordinate_list(
  \@coords,
  $strand,
  $type
);
  • Args:
    • array-ref of array-refs, each containing: start, end [, start-type, end-type] — where types are optional. If given, must be one of ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
    • strand (all locations must be on same strand)
    • location-type (EXACT, IN-BETWEEN etc)
  • Returns: list of Bio::Location objects

🧬 _new_seq_via_clone 🧬

  • Title: _new_seq_via_clone
  • Function: clones a sequence object using Bio::Root::Root::clone and sets the new sequence string. The sequence features are removed — yeah, gone, don't @ me. 💅
  • Usage:
my $new_seq = $self->_new_seq_via_clone( $seq_obj, $seq_str );
  • Args: original seq object [, new sequence string]
  • Returns: a clone of the original sequence object, optionally with a new sequence string

🧬 _new_seq_from_old 🧬

  • Title: _new_seq_from_old
  • Function: creates a new sequence object — of the same class as the old one if possible — and adds attributes to it. It also copies the annotation across to the new object. 🫶
  • Usage:
my $new_seq = $self->_new_seq_from_old( $seq_obj, { seq => $seq_str, display_id => 'some_ID'});
  • Args:
    • old sequence object
    • hashref of attributes for the new sequence (sequence string etc.)
  • Returns: a new Bio::Seq object

🪄 _coord_adjust 🪄

  • Title: _coord_adjust
  • Usage:
my $newfeat=Bio::SeqUtils->_coord_adjust($feature, 100, $seq->length);
  • Function: recursive subroutine to adjust the coordinates of a feature and all its subfeatures. If a sequence length is specified, then any adjusted features that have locations beyond the boundaries of the sequence get converted to Bio::Location::Fuzzy objects. 🌈
  • Returns: a Bio::SeqFeatureI compliant object
  • Args:
    • a Bio::SeqFeatureI compliant object
    • the number of bases to add to the coordinates
    • (optional) the length of the parent sequence

🦋 revcom_with_features 🦋

  • Title: revcom_with_features
  • Usage:
$revcom=Bio::SeqUtils->revcom_with_features($seq);
  • Function: like Bio::Seq::revcom, but it keeps the features (adjusting coordinates as appropriate). Reverse-complementing without losing your annotations? Iconic behaviour, honestly. 💅
  • Returns: a new sequence object
  • Args: a sequence object

🪄 _feature_revcom 🪄

  • Title: _feature_revcom
  • Usage:
my $newfeat=Bio::SeqUtils->_feature_revcom($feature, $seq->length);
  • Function: recursive subroutine to reverse complement a feature and all its subfeatures. The length of the parent sequence must be specified — no length, no service. 😤
  • Returns: a Bio::SeqFeatureI compliant object
  • Args:
    • a Bio::SeqFeatureI compliant object
    • the length of the parent sequence

✨ evolve ✨

  • Title 🧬 — evolve
  • Usage 💅 —
my $newseq = Bio::SeqUtils->
              evolve($seq, $similarity, $transition_transversion_rate);
  • Function 🔥 — mutates the sequence by point mutations until the similarity of the new sequence has decreased to the required level. Transition/transversion rate is adjustable, bestie, so you're not stuck with the default vibe.
  • Returns 🎀 — a brand new Bio::PrimarySeq object
  • Args 🦋 — a sequence object, a percentage similarity (like 80), and a tr/tv rate — that last one is optional and defaults to 1 (= 1:1)

Set the verbosity of the Bio::SeqUtils object to a positive integer if you want to literally watch the mutations happen as they happen. It's giving live commentary. 👑

Heads up: this method works only on nucleotide sequences. Also, it prints a warning if you set the target similarity to be less than 25%. So like, don't be shocked when it yells at you. 😭

One lil thing that trips people up, so let's be clear: transition/transversion ratio is an observed attribute of a sequence comparison. What we're dealing with here is the transition/transversion rate — the one we set for our model of sequence evolution. Different things, no cap. 💖

That's the whole page, bestie — you made it to the end, iconic behavior fr fr. 🌈⭐🌸

This was perl v5.32.1, dated 2021-08-15, and it's Bio::SeqUtils(3pm) — go forth and mutate responsibly. 🫶💜

📦 where this page comes from