.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::LocatableSeq 3pm"
.TH Bio::LocatableSeq 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
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.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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.
.PP
It is, to be honest, not well integrated with the rest of bioperl. For example,
the \fBtrunc()\fR 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.
.PP
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 \s-1HSP\s0 data, however it can probably be integrated in better and most methods
do not implement it correctly yet. Also, several PrimarySeqI methods (\fBsubseq()\fR,
\&\fBtrunc()\fR, 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.
.PP
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.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "start"
.IX Subsection "start"
.Vb 6
\& Title   : start
\& Usage   : $obj\->start($newval)
\& Function: Get/set the 1\-based start position of this sequence in the original
\&           sequence. \*(Aq0\*(Aq means before the original sequence starts.
\& Returns : value of start
\& Args    : newvalue (optional)
.Ve
.SS "end"
.IX Subsection "end"
.Vb 11
\& Title   : end
\& Usage   : $obj\->end($newval)
\& Function: Get/set the 1\-based end position of this sequence in the original
\&           sequence. \*(Aq0\*(Aq 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.
.Ve
.SS "strand"
.IX Subsection "strand"
.Vb 5
\& 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)
.Ve
.SS "mapping"
.IX Subsection "mapping"
.Vb 8
\& 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).
.Ve
.SS "frameshifts"
.IX Subsection "frameshifts"
.Vb 6
\& 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
.Ve
.SS "get_nse"
.IX Subsection "get_nse"
.Vb 6
\& Title   : get_nse
\& Usage   :
\& Function: read\-only name of form id/start\-end
\& Example :
\& Returns :
\& Args    :
.Ve
.SS "force_nse"
.IX Subsection "force_nse"
.Vb 8
\& 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
.Ve
.SS "num_gaps"
.IX Subsection "num_gaps"
.Vb 4
\& Title   : num_gaps
\& Usage   :$self\->num_gaps(\*(Aq.\*(Aq)
\& Function:Gets number of gaps in the sequence. The count excludes
\&           leading or trailing gap characters.
\&
\&           Valid bioperl sequence characters are [A\-Za\-z\e\-\e.\e*]. Of
\&           these, \*(Aq.\*(Aq and \*(Aq\-\*(Aq 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
.Ve
.SS "column_from_residue_number"
.IX Subsection "column_from_residue_number"
.Vb 3
\& 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)
.Ve
.SS "location_from_column"
.IX Subsection "location_from_column"
.Vb 3
\& 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 \*(AqEXACT\*(Aq, if a position
\&           is between bases location_type() returns \*(AqIN\-BETWEEN\*(Aq.
\&           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
.Ve
.PP
See Bio::Location::Simple for more.
.SS "revcom"
.IX Subsection "revcom"
.Vb 6
\& 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
.Ve
.SS "trunc"
.IX Subsection "trunc"
.Vb 6
\& 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.
.Ve
.SS "validate_seq"
.IX Subsection "validate_seq"
.Vb 12
\& Title   : validate_seq
\& Usage   : if(! $seqobj\->validate_seq($seq_str) ) {
\&                print "sequence $seq_str is not valid for an object of
\&                alphabet ",$seqobj\->alphabet, "\en";
\&           }
\& Function: Test that the given sequence is valid, i.e. contains only valid
\&           characters. The allowed characters are all letters (A\-Z) and \*(Aq\-\*(Aq,\*(Aq.\*(Aq,
\&           \*(Aq*\*(Aq,\*(Aq?\*(Aq,\*(Aq=\*(Aq and \*(Aq~\*(Aq. 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
.Ve