.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::SeqUtils 3pm"
.TH Bio::SeqUtils 3pm "2012-03-02" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::SeqUtils \- Additional methods for PrimarySeq objects
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    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 => \*(Aqc\*(Aq,
\&                                                      \-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);
\&
\&    # 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);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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.
.PP
The first two methods, \fIseq3()\fR and \fIseq3in()\fR, give out or read in protein
sequences coded in three letter \s-1IUPAC\s0 amino acid codes.
.PP
The next two methods, \fItranslate_3frames()\fR and \fItranslate_6frames()\fR, wrap
around the standard translate method to give back an array of three
forward or all six frame translations.
.PP
The \fImutate()\fR method mutates the sequence string with a mutation
description object.
.PP
The \fIcat()\fR 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.
.PP
The \fIrevcom_with_features()\fR and \fItrunc_with_features()\fR methods are similar
to the \fIrevcom()\fR and \fItrunc()\fR methods from Bio::Seq, but also adjust any
features associated with the sequence as appropriate.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://redmine.open\-bio.org/projects/bioperl/
.Ve
.SH "AUTHOR \- Heikki Lehvaslaiho"
.IX Header "AUTHOR - Heikki Lehvaslaiho"
Email:  heikki-at-bioperl-dot-org
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Roy R. Chaudhuri \- roy.chaudhuri at gmail.com
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.SS "seq3"
.IX Subsection "seq3"
.Vb 8
\& 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
\&           \*(Aqprotein\*(Aq. Output follows the IUPAC standard plus \*(AqTer\*(Aq for
\&           terminator. Any unknown character, including the default
\&           unknown character \*(AqX\*(Aq, is changed into \*(AqXaa\*(Aq. A noncoded
\&           aminoacid selenocystein is recognized (Sec, U).
\&
\& Returns : A scalar
\& Args    : character used for stop in the protein sequence optional,
\&           defaults to \*(Aq*\*(Aq string used to separate the output amino
\&           acid codes, optional, defaults to \*(Aq\*(Aq
.Ve
.SS "seq3in"
.IX Subsection "seq3in"
.Vb 7
\& Title   : seq3in
\& Usage   : $seq = Bio::SeqUtils\->seq3in($seq, \*(AqMetGlyTer\*(Aq)
\& 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 \*(AqXaa\*(Aq, is
\&           converted into \*(AqX\*(Aq.
\&
\& Returns : Bio::PrimarySeq object
\& Args    : sequence string
\&           optional character to be used for stop in the protein sequence,
\&              defaults to \*(Aq*\*(Aq
\&           optional character to be used for unknown in the protein sequence,
\&              defaults to \*(AqX\*(Aq
.Ve
.SS "translate_3frames"
.IX Subsection "translate_3frames"
.Vb 7
\& 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 \*(Aq\-0F\*(Aq, \*(Aq\-1F\*(Aq, \*(Aq\-2F\*(Aq.
\& Returns : An array of seq objects
\& Args    : sequence object
\&           same arguments as to Bio::PrimarySeqI::translate
.Ve
.SS "translate_6frames"
.IX Subsection "translate_6frames"
.Vb 8
\& 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 \*(Aq\-0F\*(Aq, \*(Aq\-1F\*(Aq, \*(Aq\-2F\*(Aq,
\&           \*(Aq\-0R\*(Aq, \*(Aq\-1R\*(Aq, \*(Aq\-2R\*(Aq.
\& Returns : An array of seq objects
\& Args    : sequence object
\&           same arguments as to Bio::PrimarySeqI::translate
.Ve
.SS "valid_aa"
.IX Subsection "valid_aa"
.Vb 9
\& 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 [\*(AqB\*(Aq, \*(AqZ\*(Aq, \*(AqX\*(Aq, \*(Aq*\*(Aq].
\& 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 ]
.Ve
.SS "mutate"
.IX Subsection "mutate"
.Vb 3
\& 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
.Ve
.PP
See Bio::LiveSeq::Mutation.
.SS "cat"
.IX Subsection "cat"
.Vb 8
\&  Title   : cat
\&  Usage   : my $catseq = Bio::SeqUtils\->cat(@seqs)
\&  Function: Concatenates an array of Bio::Seq objects, using the first sequence
\&            as a target. Annotations and sequence features are copied over 
\&            from any additional objects. Adjusts the coordinates of copied 
\&            features.
\&  Returns : a boolean
\&  Args    : array of sequence objects
.Ve
.PP
Note that annotations have no sequence locations. If you concatenate
sequences with the same annotations they will all be added.
.SS "trunc_with_features"
.IX Subsection "trunc_with_features"
.Vb 7
\& 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)
.Ve
.SS "_coord_adjust"
.IX Subsection "_coord_adjust"
.Vb 6
\&  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
.Ve
.SS "revcom_with_features"
.IX Subsection "revcom_with_features"
.Vb 6
\& 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
.Ve
.SS "_feature_revcom"
.IX Subsection "_feature_revcom"
.Vb 5
\&  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
.Ve
.SS "evolve"
.IX Subsection "evolve"
.Vb 10
\&  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)
.Ve
.PP
Set the verbosity of the Bio::SeqUtils object to positive integer to
see the mutations as they happen.
.PP
This method works only on nucleotide sequences. It prints a warning if
you set the target similarity to be less than 25%.
.PP
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.