NAME

       Bio::LiveSeq::AARange - AARange abstract class for LiveSeq

SYNOPSIS

         #documentation needed

DESCRIPTION

       This is used as possible parent for aminoacid range object classes.  Or it can be used
       straight away to define aminoacid ranges.  The idea is that the ranges defined are
       attached to a Translation object and they refer to its coordinate-system when they are
       first created (via the new() method).  When they are created they are anyway linked to the
       underlying DNA LiveSeq by way of the LiveSeq labels. This allows to preserve the ranges
       even if the numbering changes in the Translation due to deletions or insertions.

       The protein sequence associated with the AARange can be accessed via the usual seq() or
       subseq() methods.

       The start and end of the AARange in protein coordinate system can be fetched with
       aa_start() and aa_end() methods. Note: the behaviour of these methods would be influenced
       by the coordinate_start set in the corresponding Translation object. This can be desirable
       but can also lead to confusion if the coordinate_start had been changed and the original
       position of the AARange was to be retrieved.

       start() and end() methods of the AARange will point to the labels identifying the first
       nucleotide of the first and last triplet coding for the start and end of the
       AminoAcidRange.

       The underlying nucleotide sequence of the AARange can be retrieved with the labelsubseq()
       method. This would retrieve the whole DNA sequence, including possible introns. This is
       called "DNA_sequence".

       To fetch the nucleotide sequence of the Transcript, without introns, the labelsubseq() of
       the attached Transcript (the Transcript the Translation comes from) has to be accessed.
       This is called "cDNA_sequence".

       Here are the operations to retrieve these latter two kinds of sequences:

          $startlabel=$AARange->start;
          $endtripletlabel=$AARange->end;
          $endlabel=$AARange->{'seq'}->label(3,$endtripletlabel,$AARange->strand);

          $dnaseq=$AARange->labelsubseq($startlabel,undef,$endlabel));

          $cdnaseq=$AARange->get_Transcript->labelsubseq($startlabel,undef,$endlabel);

       To simplify, these operations have been included in two additional methods: dna_seq() and
       cdna_seq().

       These would return the whole sequence, as in the examples above.  But the above general
       scheme can be used by specifying different labels, to retrieve hypothetical subsequences
       of interest.

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 _

   new
         Title   : new
         Usage   : $aarange = Bio::LiveSeq::AARange->new(-translation => $obj_ref,
                                                      -start => $beginaa,
                                                      -end => $endaa,
                                                      -name => "ABCD",
                                                      -description => "DCBA",
                                                      -translength => $length);

         Function: generates a new AminoAcidRange LiveSeq object
         Returns : reference to a new object of class AARange
         Errorcode -1
         Args    : two positions in AminoAcid coordinate numbering
                   an object reference specifying to which translation the aminoacid
                   ranges refer to
                   a name and a description (optional)
                   an optional "translength" argument: this can be given when
                   a lot of AARanges are to be created at the same time for the same
                   Translation object, calculating it with $translation->length
                   This would increase the speed, avoiding the new() function to
                   calculate everytime the same length again and again for every obj.

   get_Transcript
         Title   : valid
         Usage   : $transcript = $obj->get_Transcript()
         Function: retrieves the reference to the object of class Transcript (if any)
                   attached to a LiveSeq object
         Returns : object reference
         Args    : none

   get_Translation
         Title   : valid
         Usage   : $translation = $obj->get_Translation()
         Function: retrieves the reference to the object of class Translation (if any)
                   attached to a LiveSeq object
         Returns : object reference
         Args    : none

   aa_start
         Title   : aa_start
         Usage   : $end = $aarange->aa_start()
         Returns : integer (position, according to Translation coordinate system) of
                   the start of an AminoAcidRange object
         Args    : none

   aa_end
         Title   : aa_end
         Usage   : $end = $aarange->aa_end()
         Returns : integer (position, according to Translation coordinate system) of
                   the end of an AminoAcidRange object
         Args    : none

   dna_seq
         Title   : dna_seq
         Usage   : $end = $aarange->dna_seq()
         Returns : the sequence at DNA level of the entire AminoAcidRange
                   this would include introns (if present)
         Args    : none

   cdna_seq
         Title   : cdna_seq
         Usage   : $end = $aarange->cdna_seq()
         Returns : the sequence at cDNA level of the entire AminoAcidRange
                   i.e. this is the part of the Transcript that codes for the
                   AminoAcidRange. It would be composed just of exonic DNA.
         Args    : none