Bio::L...ableSeq(3pm)

okay bestie, you found the page for Bio::LocatableSeq(3pm) — it's a User Contributed Perl Documentation page, and it's honestly iconic for what it does 💅

✨ NAME ✨

Bio::LocatableSeq — it's a Bio::PrimarySeq object that has start/end points on it, so it can be projected into an MSA, or just carry coordinates that are relative to another seq. slay 💖

---

🌸 SYNOPSIS 🌸

use Bio::LocatableSeq;
my $seq = Bio::LocatableSeq->new(-seq => "CAGT-GGT",
                -id  => "seq1",
                -start => 1,
                -end   => 7);

# a normal sequence object
$locseq->seq();
$locseq->id();

# has start,end points
$locseq->start();
$locseq->end();

# inherits off RangeI, so range operations possible

---

🦋 DESCRIPTION 🦋

so the LocatableSeq sequence object got built mainly because the SimpleAlign object literally requires this functionality, and when they rewrote the Sequence object they had to figure out what to do with this thing. that's the whole origin story, no cap.

and ngl, it is not well integrated with the rest of bioperl. for example, the trunc() function does not return a LocatableSeq object, even though some of y'all might have assumed it would. also, the sequence is not a Bio::SeqI, so the location is just inherited from Bio::RangeI and is not stored in a Bio::Location. the way that works is lowkey cursed but here we are.

there are all sorts of nasty gotcha's about interactions between coordinate systems when these sort of objects are used 😭 some mapping now occurs to deal with HSP data, however it can probably be integrated in better and most methods do not implement it correctly yet. also, several PrimarySeqI methods (subseq(), trunc(), etc.) do not behave as expected and must be used with care. due to this, LocatableSeq functionality is to be refactored in a future BioPerl release. however, for alignment functionality it works adequately for the time being 🫶

if you do not need alignment functionality, Bio::SeqfeatureI-implementing modules may be a suitable alternative to Bio::LocatableSeq. for example, Bio::SeqFeature::Generic and Bio::SeqFeature::Lite provide methods to attach a sequence to a specific region of a parent sequence and to set other useful attributes. cute alternatives, fr fr ✨

---

💌 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, bestie.

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

---

📖 APPENDIX 📖

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk, that underscore is the vibe check).

🎀 start

• Title: start
• Usage: $obj->start($newval)
• Function: get/set the 1-based start position of this sequence in the original sequence. '0' means before the original sequence starts.
• Returns: value of start
• Args: newvalue (optional)

🎀 end

• Title: end
• Usage: $obj->end($newval)
• Function: get/set the 1-based end position of this sequence in the original sequence. '0' means before the original sequence starts.
• Returns: value of end
• Args: newvalue (optional)
• Note: although this is a get/set, it checks passed values against the calculated end point ( derived from the sequence and based on $GAP_SYMBOLS and possible frameshifts() ). if there is no match, it will warn and set the proper value. probably best used for debugging proper sequence calculations 👀

🎀 strand

• Title: strand
• Usage: $obj->strand($newval)
• Function: return or set the strandedness
• Returns: the value of the strandedness (-1, 0 or 1)
• Args: the value of the strandedness (-1, 0 or 1)

🎀 mapping

• Title: mapping
• Usage: $obj->mapping($newval)
• Function: return or set the mapping indices (indicates # symbols/positions in the source string mapping to # of coordinate positions)
• Returns: two-element array (# symbols => # coordinate pos)
• Args: two elements (# symbols => # coordinate pos); this can also be passed in as an array reference of the two elements (as might be passed upon Bio::LocatableSeq instantiation, for instance).

🎀 frameshifts

• Title: frameshifts
• Usage: $obj->frameshifts($newval)
• Function: get/set the frameshift hash, which contains sequence positions as keys and the shift (-2, -1, 1, 2) as the value
• Returns: hash
• Args: hash or hash reference

🎀 get_nse

• Title: get_nse
• Usage: (nothing here, bestie, it's empty)
• Function: read-only name of form id/start-end
• Example: (empty)
• Returns: (empty)
• Args: (empty)

🎀 force_nse

• Title: force_nse
• Usage: $ls->force_nse()
• Function: Boolean which forces get_nse() to build an NSE, regardless of whether id(), start(), or end() is set
• Returns: Boolean value
• Args: (optional) Boolean (1 or 0)
• Note: this will convert any passed value evaluating as TRUE/FALSE to 1/0 respectively

🎀 num_gaps

• Title: num_gaps
• Usage: $self->num_gaps('.')
• Function: Gets number of gaps in the sequence. The count excludes leading or trailing gap characters.

Valid bioperl sequence characters are [A-Za-z\-\.\*]. Of these, . and - are counted as gap characters unless an optional argument specifies one of them.

• Returns: number of internal gaps in the sequence.
• Args: a gap character (optional)
• Status: Stable
• Note: replaces no_gaps

🎀 column_from_residue_number

• Title: column_from_residue_number
• Usage: $col = $seq->column_from_residue_number($resnumber)
• Function:

this function gives the position in the alignment (i.e. column number) of the given residue number in the sequence. for example, for the sequence

Seq1/91-97 AC..DEF.GH

column_from_residue_number(94) returns 6.

an exception is thrown if the residue number would lie outside the length of the aligment (e.g. column_from_residue_number( "Seq2", 22 ))

• Returns: a column number for the position of the given residue in the given sequence (1 = first column)
• Args: a residue number in the whole sequence (not just that segment of it in the alignment)

🎀 location_from_column

• Title: location_from_column
• Usage: $loc = $ali->location_from_column($column_number)
• Function:

this function gives the residue number for a given position in the alignment (i.e. column number) of the given. gaps complicate this process and force the output to be a Bio::Location::Simple where values can be undefined. for example, for the sequence:

Seq/91-96 .AC..DEF.G.

location_from_column( 3 ) position 92
location_from_column( 4 ) position 92^93
location_from_column( 9 ) position 95^96
location_from_column( 1 ) position undef

an exact position returns a Bio::Location::Simple object where where location_type() returns 'EXACT', if a position is between bases location_type() returns 'IN-BETWEEN'. column before the first residue returns undef. note that if the position is after the last residue in the alignment, that there is no guarantee that the original sequence has residues after that position.

an exception is thrown if the column number is not within the sequence.

• Returns: Bio::Location::Simple or undef
• Args: a column number
• Throws: if column is not within the sequence

see Bio::Location::Simple for more.

🎀 revcom

• Title: revcom
• Usage: $rev = $seq->revcom()
• Function: produces a new Bio::LocatableSeq object which has the reversed complement of the sequence. for protein sequences this throws an exception of "Sequence is a protein. Cannot revcom"
• Returns: a new Bio::LocatableSeq object
• Args: none

🎀 trunc

• Title: trunc
• Usage: $subseq = $myseq->trunc(10,100);
• Function: provides a truncation of a sequence,
• Returns: a fresh Bio::PrimarySeqI implementing object
• Args: two integers denoting first and last columns of the sequence to be included into sub-sequence.

🎀 validate_seq

• Title: validate_seq
• Usage:

if(! $seqobj->validate_seq($seq_str) ) {
    print "sequence $seq_str is not valid for an object of
    alphabet ",$seqobj->alphabet, "\n";
}

• Function: test that the given sequence is valid, i.e. contains only valid characters. the allowed characters are all letters (A-Z) and '-', '.', '*', '?', '=' and '~'. spaces are not valid. note that this implementation does not take alphabet() into account.
• Returns: 1 if the supplied sequence string is valid, 0 otherwise.
• Args:
  • sequence string to be validated
  • Boolean to throw an error if the sequence is invalid

---

and that's the whole page, bestie 💜 this was perl v5.32.1, dated 2021-08-15, straight from the Bio::L...ableSeq(3pm) page (yes the title is truncated like that, it's giving mysterious ✨). go forth and locate your seqs responsibly 🫶🎀