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

NAME

       Bio::LiveSeq::SeqI - Abstract sequence interface class for LiveSeq

SYNOPSIS

         # documentation needed

DESCRIPTION

       This class implements BioPerl PrimarySeqI interface for Live Seq objects.

       One of the main difference in LiveSequence compared to traditional "string" sequences is
       that coordinate systems are flexible. Typically gene nucleotide numbering starts from 1 at
       the first character of the initiator codon (A in ATG). This means that negative positions
       are possible and common!

       Secondly, the sequence manipulation methods do not return a new sequence object but change
       the current object. The current status can be written out to BioPerl sequence objects.

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

AUTHOR - Joseph A.L. Insana

       Email:  Insana@ebi.ac.uk, jinsana@gmx.net

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

       Some note on the terminology/notation of method names:
        label: a unique pointer to a single nucleotide
        position: the position of a nucleotide according to a particular coordinate
                  system (e.g. counting downstream from a particular label taken as
                  number 1)
        base: the one letter code for a nucleotide (i.e.: "a" "t" "c" "g")

              a base is the "value" that an "element" of a "chain" can assume
                (see documentation on the Chain datastructure if interested)

   seq
        Title   : seq
        Usage   : $string    = $obj->seq()
        Function: Returns the complete sequence of an object as a string of letters.
                  Suggested cases are upper case for proteins and lower case for
                  DNA sequence (IUPAC standard),
        Returns : a string

   all_labels
        Title   : all_labels
        Usage   : @labels = $obj->all_labels()
        Function: all the labels of every nucleotide an object is composed of
        Returns : an array of labels
        Args    : none

   labelsubseq
         Title   : labelsubseq
         Usage   : $dna->labelsubseq();
                 : $dna->labelsubseq($startlabel);
                 : $dna->labelsubseq($startlabel,$length);
                 : $dna->labelsubseq($startlabel,undef,$endlabel);
         e.g.    : $dna->labelsubseq(4,undef,8);
         Function: prints the sequence as string. The difference between labelsubseq
                   and normal subseq is that it uses /labels/ as arguments, instead
                   than positions. This allows for faster and more efficient lookup,
                   skipping the (usually) lengthy conversion of positions into labels.
                   This is especially useful for manipulating with high power
                   LiveSeq objects, knowing the labels and exploiting their
                   usefulness.
         Returns : a string
         Errorcode -1
         Args    : without arguments it returns the entire sequence
                   with a startlabel it returns the sequence downstream that label
                   if a length is specified, it returns only that number of bases
                   if an endlabel is specified, it overrides the length argument
                    and prints instead up to that label (included)
         Defaults: $startlabel defaults to the beginning of the entire sequence
                   $endlabel defaults to the end of the entire sequence

   subseq
        Title   : subseq
        Usage   : $substring = $obj->subseq(10,40);
                : $substring = $obj->subseq(10,undef,4);
        Function: returns the subseq from start to end, where the first base
                  is 1 and the number is inclusive, ie 1-2 are the first two
                  bases of the sequence

                  Start cannot be larger than end but can be equal.

                  Allows for negative numbers $obj->subseq(-10,-1). By
                  definition, there is no 0!
                              -5  -1 1   5
                       gctagcgcccaac atggctcgctg

                  This allows one to retrieve sequences upstream from given position.

                  The precedence is from left to right: if END is given LENGTH is
                  ignored.

        Examples: $obj->subseq(-10,undef,10) returns 10 elements before position 1
                  $obj->subseq(4,8) returns elements from the 4th to the 8th, inclusive

        Returns : a string
        Errorcode: -1
        Args    : start,  integer, defaults to start of the sequence
                  end,    integer, '' or undef, defaults to end of the sequence
                  length, integer, '' or undef
                  an optional strand (1 or -1) 4th argument
                   if strand argument is not given, it will default to the object
                   argument. This argument is useful when a call is issued from a child
                   of a parent object containing the subseq method

   length
         Title   : length
         Usage   : $seq->length();
         Function: returns the number of nucleotides (or the number of aminoacids)
                   in the entire sequence
         Returns : an integer
         Errorcode -1
         Args    : none

   display_id
        Title   : display_id
        Usage   : $id_string = $obj->display_id();
        Function: returns the display id, alias the common name of the object

                  The semantics of this is that it is the most likely string
                  to be used as an identifier of the sequence, and likely to
                  have "human" readability.  The id is equivalent to the ID
                  field of the GenBank/EMBL databanks and the id field of the
                  Swissprot/sptrembl database. In fasta format, the >(\S+) is
                  presumed to be the id, though some people overload the id
                  to embed other information.

        See also: accession_number
        Returns : a string
        Args    : none

   accession_number
        Title   : accession_number
        Usage   : $unique_biological_key = $obj->accession_number;
        Function: Returns the unique biological id for a sequence, commonly
                  called the accession_number.
                  Notice that primary_id() provides the unique id for the
                  implementation, allowing multiple objects to have the same accession
                  number in a particular implementation.

                  For objects with no accession_number this method returns "unknown".
        Returns : a string
        Args    : none

   primary_id
        Title   : primary_id
        Usage   : $unique_implementation_key = $obj->primary_id;
        Function: Returns the unique id for this object in this
                  implementation. This allows implementations to manage their own
                  object ids in a way the implementation can control. Clients can
                  expect one id to map to one object.

                  For sequences with no primary_id, this method returns
                  a stringified memory location.

        Returns : A string
        Args    : None

   change
        Title   : change
        Usage   : $substring = $obj->change('AA', 10);
        Function: changes, modifies, mutates the LiveSequence
        Examples:
               $obj->change('',   10);      delete nucleotide #10
               $obj->change('',   10, 2);   delete two nucleotides starting from #10
               $obj->change('G',  10);      change nuc #10 to 'G'
               $obj->change('GA', 10, 4);   replace #10 and 3 following with 'GA'
               $obj->change('GA', 10, 2));  is same as $obj->change('GA',  10);
               $obj->change('GA', 10, 0 );  insert 'GA' before nucleotide at #10
               $obj->change('GA', 10, 1);   GA inserted before #10, #10 deleted
               $obj->change('GATC', 10, 2); GATC inserted before #10, #10&#11 deleted
               $obj->change('GATC', 10, 6); GATC inserted before #10, #10-#15 deleted

        Returns : a string of deleted bases (if any) or 1 (everything OK)
        Errorcode: -1
        Args    : seq,    string, or '' ('' = undef = 0 = deletion)
                  start,  integer
                  length, integer (optional)

   positionchange
        Title   : positionchange
        Function: Exactly like change. I.e. change() defaults to positionchange()

   labelchange
        Title   : labelchange
        Function: Exactly like change but uses a /label/ instead than a position
                  as second argument. This allows for multiple changes in a LiveSeq
                  without the burden of recomputing positions. I.e. for a multiple
                  change in two different points of the LiveSeq, the approach would
                  be the following: fetch the correct labels out of the two different
                  positions (method: label($position)) and then use the labelchange()
                  method to modify the sequence using those labels instead than
                  relying on the positions (that would have modified after the
                  first change).

   valid
         Title   : valid
         Usage   : $boolean = $obj->valid($label)
         Function: tests if a label exists inside the object
         Returns : boolean
         Args    : label

   start
         Title   : start
         Usage   : $startlabel=$obj->start()
         Function: returns the label of the first nucleotide of the object (exon, CDS)
         Returns : label
         Args    : none

   end
         Title   : end
         Usage   : $endlabel=$obj->end()
         Function: returns the label of the last nucleotide of the object (exon, CDS)
         Returns : label
         Args    : none

   strand
         Title   : strand
         Usage   : $strand=$obj->strand()
                   $obj->strand($strand)
         Function: gets or sets strand information, being 1 or -1 (forward or reverse)
         Returns : -1 or 1
         Args    : none OR -1 or 1

   alphabet
        Title   : alphabet
        Usage   : if( $obj->alphabet eq 'dna' ) { /Do Something/ }
        Function: Returns the type of sequence being one of
                  'dna', 'rna' or 'protein'. This is case sensitive.

        Returns : a string either 'dna','rna','protein'.
        Args    : none

   coordinate_start
         Title   : coordinate_start
         Usage   : $coordstartlabel=$obj->coordinate_start()
                 : $coordstartlabel=$obj->coordinate_start($label)
         Function: returns and optionally sets the first label of the coordinate
                   system used
                   For some objects only labels inside the object or in frame (for
                   Translation objects) will be allowed to get set as coordinate start

         Returns : label. It returns 0 if label not found.
         Errorcode -1
         Args    : an optional reference $label that is position 1

   label
         Title   : label
         Usage   : $seq->label($position)
                 : $seq->label($position,$firstlabel)
         Examples: $nextlabel=$seq->label(2,$label) -> retrieves the following label
                 : $prevlabel=$seq->label(-1,$label) -> retrieves the preceding label

         Function: returns the label of the nucleotide at $position from current
                   coordinate start
         Returns : a label. It returns 0 if label not found.
         Errorcode -1
         Args    : a position,
                   an optional reference $firstlabel that is to be used as position 1
                   an optional strand (1 or -1) argument
                    if strand argument is not given, it will default to the object
                    argument. This argument is useful when a call is issued from a child
                    of a parent object containing the subseq method

   position
         Title   : position
         Usage   : $seq->position($label)
                 : $seq->position($label,$firstlabel)
         Function: returns the position of nucleotide at $label
         Returns : the position of the label from current coordinate start
         Errorcode 0
         Args    : a label pointing to a certain nucleotide (e.g. start of exon)
                   an optional "firstlabel" as reference to count from
                   an optional strand (1 or -1) argument
                    if strand argument is not given, it will default to the object
                    argument. This argument is useful when a call is issued from a child
                    of a parent object containing the subseq method

   follows
         Title   : follows
         Usage   : $seq->follows($firstlabel,$secondlabel)
                 : $seq->follows($firstlabel,$secondlabel,$strand)
         Function: checks if SECONDlabel follows FIRSTlabel, undependent of the strand
                   i.e. it checks downstream for forward strand and
                   upstream for reverse strand
         Returns : 1 or 0
         Errorcode -1
         Args    : two labels
                   an optional strand (1 or -1) argument
                    if strand argument is not given, it will default to the object
                    argument. This argument is useful when a call is issued from a child
                    of a parent object containing the subseq method

   gene
        Title   : gene
        Usage   : my $gene=$obj->gene;
        Function: Gets or sets the reference to the LiveSeq::Gene object.
                  Objects that are features of a LiveSeq Gene will have this
                  attribute set automatically.

        Returns : reference to an object of class Gene
        Note    : if Gene object is not set, this method will return 0;
        Args    : none or reference to object of class Bio::LiveSeq::Gene

   obj_valid
        Title   : obj_valid
        Usage   : if ($obj->obj_valid) {do something;}
        Function: Checks if start and end labels are still valid for the ojbect,
                  i.e. tests if the LiveSeq object is still valid
        Returns : boolean
        Args    : none

   name
        Title   : name
        Usage   : $name = $obj->name;
                : $name = $obj->name("ABCD");
        Function: Returns or sets the name of the object.
                  If there is no name, it will return "unknown";
        Returns : A string
        Args    : None

   desc
        Title   : desc
        Usage   : $desc = $obj->desc;
                : $desc = $obj->desc("ABCD");
        Function: Returns or sets the description of the object.
                  If there is no description, it will return "unknown";
        Returns : A string
        Args    : None

   source
        Title   : source
        Usage   : $name = $obj->source;
                : $name = $obj->source("Homo sapiens");
        Function: Returns or sets the organism that is source of the object.
                  If there is no source, it will return "unknown";
        Returns : A string
        Args    : None