Bio::LocatableSeq - A Bio::PrimarySeq object with start/end points on it that
can be projected into a MSA or have coordinates relative to another seq.
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
The LocatableSeq sequence object was developed mainly because the SimpleAlign
object requires this functionality, and in the rewrite of the Sequence object
we had to decide what to do with this.
It is, to be honest, not well integrated with the rest of bioperl. For example,
the
trunc() function does not return a LocatableSeq object, as some
might have thought. Also, the sequence is not a Bio::SeqI, so the location is
simply inherited from Bio::RangeI and is not stored in a Bio::Location.
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.
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.
[email protected] - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Please direct usage questions or support issues to the mailing list:
[email protected]
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.
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
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
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)
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.
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)
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).
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
Title : get_nse
Usage :
Function: read-only name of form id/start-end
Example :
Returns :
Args :
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
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
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)
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
L<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.
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
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.
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