Bio::LocatableSeq.3pm

Langue: en

Version: 2010-05-19 (ubuntu - 24/10/10)

Section: 3 (Bibliothèques de fonctions)

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

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:
   http://bugzilla.open-bio.org/
 
 

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,
 
  Example :
  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(! $seq->validate_seq($seq_str) ) {
                 print "sequence $seq_str is not valid for an object of
                 alphabet ",$seq->alphabet, "\n";
             }
  Function: Validates a given sequence string. A validating sequence string
            must be accepted by seq(). A string that does not validate will
            lead to an exception if passed to seq().
 
            The implementation provided here does not take alphabet() into
            account. Allowed are all letters (A-Z), numbers [0-9] 
            and common symbols used for gaps, stop codons, unknown residues,
            and frameshifts, including '-','.','*','?','=',and '~'.
 
  Example :
  Returns : 1 if the supplied sequence string is valid for the object, and
            0 otherwise.
  Args    : The sequence string to be validated.
 
 

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())