Provided by: libbio-perl-perl_1.7.2-3_all bug

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.

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

       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.

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.

         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 _

   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   :
        Function: read-only name of form id/start-end
        Example :
        Returns :
        Args    :

   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
                  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.

   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

   no_gap
        Title     : no_gaps
        Usage     : $self->no_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    : Deprecated (in favor of num_gaps())

   no_sequences
        Title     : no_sequences
        Usage     : $gaps = $seq->no_sequences
        Function  : number of sequence in the sequence alignment
        Returns   : integer
        Argument  :
        Status    : Deprecated (in favor of num_sequences())