Provided by: libbio-perl-perl_1.7.8-1_all bug

NAME

       Bio::SeqUtils - Additional methods for PrimarySeq objects

SYNOPSIS

           use Bio::SeqUtils;
           # get a Bio::PrimarySeqI compliant object, $seq, somehow
           $util = Bio::SeqUtils->new();
           $polypeptide_3char = $util->seq3($seq);
           # or
           $polypeptide_3char = Bio::SeqUtils->seq3($seq);

           # set the sequence string (stored in one char code in the object)
           Bio::SeqUtils->seq3($seq, $polypeptide_3char);

           # translate a sequence in all six frames
           @seqs = Bio::SeqUtils->translate_6frames($seq);

           # inplace editing of the sequence
           Bio::SeqUtils->mutate($seq,
                                 Bio::LiveSeq::Mutation->new(-seq => 'c',
                                                             -pos => 3
                                                            ));
           # mutate a sequence to desired similarity%
           $newseq = Bio::SeqUtils-> evolve
               ($seq, $similarity, $transition_transversion_rate);

           # concatenate two or more sequences with annotations and features,
           # the first sequence will be modified
           Bio::SeqUtils->cat(@seqs);
           my $catseq=$seqs[0];

           # truncate a sequence, retaining features and adjusting their
           # coordinates if necessary
           my $truncseq = Bio::SeqUtils->trunc_with_features($seq, 100, 200);

           # reverse complement a sequence and its features
           my $revcomseq = Bio::SeqUtils->revcom_with_features($seq);

           # simulate cloning of a fragment into a vector. Cut the vector at
           # positions 1000 and 1100 (deleting positions 1001 to 1099) and
           # "ligate" a fragment into the sites. The fragment is
           # reverse-complemented in this example (option "flip").
           # All features of the vector and fragment are preserved and
           # features that are affected by the deletion/insertion are
           # modified accordingly.
           # $vector and $fragment must be Bio::SeqI compliant objects
           my $new_molecule = Bio::Sequtils->ligate(
             -vector => $vector,
             -fragment => $fragment,
             -left => 1000,
             -right => 1100,
             -flip => 1
           );

           # delete a segment of a sequence (from pos 1000 to 1100, inclusive),
           # again preserving features and annotations
           my $new_molecule = Bio::SeqUtils->cut( $seq, 1000, 1100 );

           # insert a fragment into a recipient between positions 1000 and
           # 1001. $recipient is a Bio::SeqI compliant object
           my $new_molecule =  Bio::SeqUtils::PbrTools->insert(
             $recipient_seq,
             $fragment_seq,
             1000
           );

DESCRIPTION

       This class is a holder of methods that work on Bio::PrimarySeqI- compliant sequence
       objects, e.g. Bio::PrimarySeq and Bio::Seq. These methods are not part of the
       Bio::PrimarySeqI interface and should in general not be essential to the primary function
       of sequence objects. If you are thinking of adding essential functions, it might be better
       to create your own sequence class.  See Bio::PrimarySeqI, Bio::PrimarySeq, and Bio::Seq
       for more.

       The methods take as their first argument a sequence object. It is possible to use methods
       without first creating a SeqUtils object, i.e. use it as an anonymous hash.

       The first two methods, seq3() and seq3in(), give out or read in protein sequences coded in
       three letter IUPAC amino acid codes.

       The next two methods, translate_3frames() and translate_6frames(), wrap around the
       standard translate method to give back an array of three forward or all six frame
       translations.

       The mutate() method mutates the sequence string with a mutation description object.

       The cat() method concatenates two or more sequences. The first sequence is modified by
       addition of the remaining sequences. All annotations and sequence features will be
       transferred.

       The revcom_with_features() and trunc_with_features() methods are similar to the revcom()
       and trunc() methods from Bio::Seq, but also adjust any features associated with the
       sequence as appropriate.

       There are also methods that simulate molecular cloning with rich sequence objects.  The
       delete() method cuts a segment out of a sequence and re-joins the left and right fragments
       (like splicing or digesting and re-ligating a molecule).  Positions (and types) of
       sequence features are adjusted accordingly: Features that span the deleted segment are
       converted to split featuress to indicate the disruption. (Sub)Features that extend into
       the deleted segment are truncated.  A new molecule is created and returned.

       The insert() method inserts a fragment (which can be a rich Bio::Seq object) into another
       sequence object adding all annotations and features to the final product.  Features that
       span the insertion site are converted to split features to indicate the disruption.  A new
       feature is added to indicate the inserted fragment itself.  A new molecule is created and
       returned.

       The ligate() method simulates digesting a recipient (vector) and ligating a fragment into
       it, which can also be flipped if needed. It is simply a combination of a deletion and an
       insertion step and returns a new molecule. The rules for modifying feature locations
       outlined above are also used here, e.g. features that span the cut sites are converted to
       split features with truncated sub-locations.

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 - Heikki Lehvaslaiho

       Email:  heikki-at-bioperl-dot-org

CONTRIBUTORS

       Roy R. Chaudhuri - roy.chaudhuri at gmail.com Frank Schwach - frank.schwach@sanger.ac.uk

APPENDIX

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

   seq3
        Title   : seq3
        Usage   : $string = Bio::SeqUtils->seq3($seq)
        Function: Read only method that returns the amino acid sequence as a
                  string of three letter codes. alphabet has to be
                  'protein'. Output follows the IUPAC standard plus 'Ter' for
                  terminator. Any unknown character, including the default
                  unknown character 'X', is changed into 'Xaa'. A noncoded
                  aminoacid selenocystein is recognized (Sec, U).

        Returns : A scalar
        Args    : character used for stop in the protein sequence optional,
                  defaults to '*' string used to separate the output amino
                  acid codes, optional, defaults to ''

   seq3in
        Title   : seq3in
        Usage   : $seq = Bio::SeqUtils->seq3in($seq, 'MetGlyTer')
        Function: Method for changing of the sequence of a
                  Bio::PrimarySeqI sequence object. The three letter amino
                  acid input string is converted into one letter code.  Any
                  unknown character triplet, including the default 'Xaa', is
                  converted into 'X'.

        Returns : Bio::PrimarySeq object
        Args    : sequence string
                  optional character to be used for stop in the protein sequence,
                     defaults to '*'
                  optional character to be used for unknown in the protein sequence,
                     defaults to 'X'

   translate_3frames
        Title   : translate_3frames
        Usage   : @prots = Bio::SeqUtils->translate_3frames($seq)
        Function: Translate a nucleotide sequence in three forward frames.
                  The IDs of the sequences are appended with '-0F', '-1F', '-2F'.
        Returns : An array of seq objects
        Args    : sequence object
                  same arguments as to Bio::PrimarySeqI::translate

   translate_6frames
        Title   : translate_6frames
        Usage   : @prots = Bio::SeqUtils->translate_6frames($seq)
        Function: translate a nucleotide sequence in all six frames
                  The IDs of the sequences are appended with '-0F', '-1F', '-2F',
                  '-0R', '-1R', '-2R'.
        Returns : An array of seq objects
        Args    : sequence object
                  same arguments as to Bio::PrimarySeqI::translate

   valid_aa
        Title   : valid_aa
        Usage   : my @aa = $table->valid_aa
        Function: Retrieves a list of the valid amino acid codes.
                  The list is ordered so that first 21 codes are for unique
                  amino acids. The rest are ['B', 'Z', 'X', '*'].
        Returns : array of all the valid amino acid codes
        Args    : [optional] $code => [0 -> return list of 1 letter aa codes,
                                       1 -> return list of 3 letter aa codes,
                                       2 -> return associative array of both ]

   mutate
        Title   : mutate
        Usage   : Bio::SeqUtils->mutate($seq,$mutation1, $mutation2);
        Function: Inplace editing of the sequence.

                  The second argument can be a Bio::LiveSeq::Mutation object
                  or an array of them. The mutations are applied sequentially
                  checking only that their position is within the current
                  sequence.  Insertions are inserted before the given
                  position.

        Returns : boolean
        Args    : sequence object
                  mutation, a Bio::LiveSeq::Mutation object, or an array of them

       See Bio::LiveSeq::Mutation.

   cat
         Title   : cat
         Usage   : Bio::SeqUtils->cat(@seqs);
                   my $catseq=$seqs[0];
         Function: Concatenates a list of Bio::Seq objects, adding them all on to the
                   end of the first sequence. Annotations and sequence features are
                   copied over from any additional objects, and the coordinates of any
                   copied features are adjusted appropriately.
         Returns : a boolean
         Args    : array of sequence objects

       Note that annotations have no sequence locations. If you concatenate sequences with the
       same annotations they will all be added.

   trunc_with_features
        Title   : trunc_with_features
        Usage   : $trunc=Bio::SeqUtils->trunc_with_features($seq, $start, $end);
        Function: Like Bio::Seq::trunc, but keeps features (adjusting coordinates
                  where necessary. Features that partially overlap the region have
                  their location changed to a Bio::Location::Fuzzy.
        Returns : A new sequence object
        Args    : A sequence object, start coordinate, end coordinate (inclusive)

   delete
        Title   : delete
        Function: cuts a segment out of a sequence and re-joins the left and right fragments
                  (like splicing or digesting and re-ligating a molecule).
                  Positions (and types) of sequence features are adjusted accordingly:
                  Features that span the cut site are converted to split featuress to
                  indicate the disruption.
                  Features that extend into the cut-out fragment are truncated.
                  A new molecule is created and returned.
        Usage   : my $cutseq =  Bio::SeqUtils::PbrTools->cut( $seq, 1000, 1100 );
        Args    : a Bio::PrimarySeqI compliant object to cut,
                  first nt of the segment to be deleted
                  last nt of the segment to be deleted
                  optional:
                  hash-ref of options:
                   clone_obj: if true, clone the input sequence object rather
                              than calling "new" on the object's class

        Returns : a new Bio::Seq object

   insert
        Title   : insert
        Function: inserts a fragment (a Bio::Seq object) into a nother sequence object
                  adding all annotations and features to the final product.
                  Features that span the insertion site are converted to split
                  features to indicate the disruption.
                  A new feature is added to indicate the inserted fragment itself.
                  A new molecule is created and returned.
        Usage   : # insert a fragment after pos 1000
                  my $insert_seq =  Bio::SeqUtils::PbrTools->insert(
                    $recipient_seq,
                    $fragment_seq,
                    1000
                  );
        Args    : recipient sequence (a Bio::PrimarySeqI compliant object),
                  a fragmetn to insert (Bio::PrimarySeqI compliant object),
                  insertion position (fragment is inserted to the right of this pos)
                   pos=0 will prepend the fragment to the recipient
                  optional:
                  hash-ref of options:
                   clone_obj: if true, clone the input sequence object rather
                              than calling "new" on the object's class
        Returns : a new Bio::Seq object

   ligate
        title   : ligate
        function: pastes a fragment (which can also have features) into a recipient
                  sequence between two "cut" sites, preserving features and adjusting
                  their locations.
                  This is a shortcut for deleting a segment from a sequence object followed
                  by an insertion of a fragmnet and is supposed to be used to simulate
                  in-vitro cloning where a recipient (a vector) is digested and a fragment
                  is then ligated into the recipient molecule. The fragment can be flipped
                  (reverse-complemented with all its features).
                  A new sequence object is returned to represent the product of the reaction.
                  Features and annotations are transferred from the insert to the product
                  and features on the recipient are adjusted according to the methods
                  L</"delete"> amd L</"insert">:
                  Features spanning the insertion site will be split up into two sub-locations.
                  (Sub-)features in the deleted region are themselves deleted.
                  (Sub-)features that extend into the deleted region are truncated.
                  The class of the product object depends on the class of the recipient (vector)
                  sequence object. if it is not possible to instantiate a new
                  object of that class, a Bio::Primaryseq object is created instead.
        usage   : # insert the flipped fragment between positions 1000 and 1100 of the
                  # vector, i.e. everything between these two positions is deleted and
                  # replaced by the fragment
                  my $new_molecule = Bio::Sequtils::Pbrtools->ligate(
                    -recipient => $vector,
                    -fragment => $fragment,
                    -left => 1000,
                    -right => 1100,
                    -flip      => 1,
                    -clone_obj => 1
                  );
        args    : recipient: the recipient/vector molecule
                  fragment: molecule that is to be ligated into the vector
                  left: left cut site (fragment will be inserted to the right of
                        this position)
                  optional:
                   right: right cut site (fragment will be inseterted to the
                          left of this position). defaults to left+1
                   flip: boolean, if true, the fragment is reverse-complemented
                         (including features) before inserting
                   clone_obj: if true, clone the recipient object to create the product
                              instead of calling "new" on its class
        returns : a new Bio::Seq object of the ligated fragments

   _coord_adjust_deletion
        title   : _coord_adjust_deletion
        function: recursively adjusts coordinates of seqfeatures on a molecule
                  where a segment has been deleted.
                  (sub)features that span the deletion site become split features.
                  (sub)features that extend into the deletion site are truncated.
                  A note is added to the feature to inform about the size and
                  position of the deletion.
        usage   : my $adjusted_feature = Bio::Sequtils::_coord_adjust_deletion(
                    $feature,
                    $start,
                    $end
                  );
        args    : a Bio::SeqFeatureI compliant object,
                  start (inclusive) position of the deletion site,
                  end (inclusive) position of the deletion site
        returns : a Bio::SeqFeatureI compliant object

   _coord_adjust_insertion
        title   : _coord_adjust_insertion
        function: recursively adjusts coordinates of seqfeatures on a molecule
                  where another sequence has been inserted.
                  (sub)features that span the insertion site become split features
                  and a note is added about the size and positin of the insertion.
                  Features with an IN-BETWEEN location at the insertion site
                  are lost (such features can only exist between adjacent bases)
        usage   : my $adjusted_feature = Bio::Sequtils::_coord_adjust_insertion(
                    $feature,
                    $insert_pos,
                    $insert_length
                  );
        args    : a Bio::SeqFeatureI compliant object,
                  insertion position (insert to the right of this position)
                  length of inserted fragment
        returns : a Bio::SeqFeatureI compliant object

   _single_loc_object_from_collection
        Title   : _single_loc_object_from_collection
        Function: takes an array of location objects. Returns either a split
                  location object if there are more than one locations in the
                  array or returns the single location if there is only one
        Usage   : my $loc = _single_loc_object_from_collection( @sublocs );
        Args    : array of Bio::Location objects
        Returns : a single Bio:;Location object containing all locations

   _location_objects_from_coordinate_list
        Title   : _location_objects_from_coordinate_list
        Function: takes an array-ref of start/end coordinates, a strand and a
                  type and returns a list of Bio::Location objects (Fuzzy by
                  default, Simple in case of in-between coordinates).
                  If location type is not "IN-BETWEEN", individual types may be
                  passed in for start and end location as per Bio::Location::Fuzzy
                  documentation.
        Usage   : my @loc_objs = $self->_location_objects_from_coordinate_list(
                    \@coords,
                    $strand,
                    $type
                  );
        Args    : array-ref of array-refs each containing:
                  start, end [, start-type, end-type]
                    where types are optional. If given, must be
                    a one of ('BEFORE', 'AFTER', 'EXACT','WITHIN', 'BETWEEN')
                  strand (all locations must be on same strand)
                  location-type (EXACT, IN-BETWEEN etc)
        Returns : list of Bio::Location objects

   _new_seq_via_clone
        Title   : _new_seq_via_clone
        Function: clone a sequence object using Bio::Root::Root::clone and set the new sequence string
                  sequence features are removed.
        Usage   : my $new_seq = $self->_new_seq_via_clone( $seq_obj, $seq_str );
        Args    : original seq object [, new sequence string]
        Returns : a clone of the original sequence object, optionally with new sequence string

   _new_seq_from_old
        Title   : _new_seq_from_old
        Function: creates a new sequence obejct, if possible of the same class as the old and adds
                  attributes to it. Also copies annotation across to the new object.
        Usage   : my $new_seq = $self->_new_seq_from_old( $seq_obj, { seq => $seq_str, display_id => 'some_ID'});
        Args    : old sequence object
                  hashref of attributes for the new sequence (sequence string etc.)
        Returns : a new Bio::Seq object

   _coord_adjust
         Title   : _coord_adjust
         Usage   : my $newfeat=Bio::SeqUtils->_coord_adjust($feature, 100, $seq->length);
         Function: Recursive subroutine to adjust the coordinates of a feature
                   and all its subfeatures. If a sequence length is specified, then
                   any adjusted features that have locations beyond the boundaries
                   of the sequence are converted to Bio::Location::Fuzzy objects.

         Returns : A Bio::SeqFeatureI compliant object.
         Args    : A Bio::SeqFeatureI compliant object,
                   the number of bases to add to the coordinates
                   (optional) the length of the parent sequence

   revcom_with_features
        Title   : revcom_with_features
        Usage   : $revcom=Bio::SeqUtils->revcom_with_features($seq);
        Function: Like Bio::Seq::revcom, but keeps features (adjusting coordinates
                  as appropriate.
        Returns : A new sequence object
        Args    : A sequence object

   _feature_revcom
         Title   : _feature_revcom
         Usage   : my $newfeat=Bio::SeqUtils->_feature_revcom($feature, $seq->length);
         Function: Recursive subroutine to reverse complement a feature and
                   all its subfeatures. The length of the parent sequence must be
                   specified.

         Returns : A Bio::SeqFeatureI compliant object.
         Args    : A Bio::SeqFeatureI compliant object,
                   the length of the parent sequence

   evolve
         Title   : evolve
         Usage   : my $newseq = Bio::SeqUtils->
                       evolve($seq, $similarity, $transition_transversion_rate);
         Function: Mutates the sequence by point mutations until the similarity of
                   the new sequence has decreased to the required level.
                   Transition/transversion rate is adjustable.
         Returns : A new Bio::PrimarySeq object
         Args    : sequence object
                   percentage similarity (e.g. 80)
                   tr/tv rate, optional, defaults to 1 (= 1:1)

       Set the verbosity of the Bio::SeqUtils object to positive integer to see the mutations as
       they happen.

       This method works only on nucleotide sequences. It prints a warning if you set the target
       similarity to be less than 25%.

       Transition/transversion ratio is an observed attribute of an sequence comparison. We are
       dealing here with the transition/transversion rate that we set for our model of sequence
       evolution.