.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Tools::SeqPattern 3pm"
.TH Bio::Tools::SeqPattern 3pm "2020-10-28" "perl v5.30.3" "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::Tools::SeqPattern \- represent a sequence pattern or motif
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Bio::Tools::SeqPattern;
\&
\& my $pat1     = \*(AqT[GA]AA...TAAT\*(Aq;
\& my $pattern1 = Bio::Tools::SeqPattern\->new(\-SEQ =>$pat1, \-TYPE =>\*(AqDna\*(Aq);
\&
\& my $pat2     = \*(Aq[VILM]R(GXX){3,2}...[^PG]\*(Aq;
\& my $pattern2 = Bio::Tools::SeqPattern\->new(\-SEQ =>$pat2, \-TYPE =>\*(AqAmino\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::Tools::SeqPattern module encapsulates generic data and
methods for manipulating regular expressions describing nucleic or
amino acid sequence patterns (a.k.a, \*(L"motifs\*(R"), such as the ones produced by
Bio::Tools::IUPAC.
.PP
Bio::Tools::SeqPattern is a concrete class that inherits from Bio::Seq.
.PP
This class grew out of a need to have a standard module for doing routine
tasks with sequence patterns such as:
.PP
.Vb 4
\&  \-\- Forming a reverse\-complement version of a nucleotide sequence pattern
\&  \-\- Expanding patterns containing ambiguity codes
\&  \-\- Checking for invalid regexp characters
\&  \-\- Untainting yet preserving special characters in the pattern
.Ve
.PP
Other features to look for in the future:
.PP
.Vb 2
\&  \-\- Full pattern syntax checking
\&  \-\- Conversion between expanded and condensed forms of the pattern
.Ve
.SH "MOTIVATIONS"
.IX Header "MOTIVATIONS"
A key motivation for Bio::Tools::SeqPattern is to have a way to
generate a reverse complement of a nucleotide sequence pattern.
This makes possible simultaneous pattern matching on both sense and
anti-sense strands of a query sequence.
.PP
In principle, one could do such a search more inefficiently by testing
against both sense and anti-sense versions of a sequence.
It is entirely equivalent to test a regexp containing both sense and
anti-sense versions of the *pattern* against one copy of the sequence.
The latter approach is much more efficient since:
.PP
.Vb 3
\&   1) You need only one copy of the sequence.
\&   2) Only one regexp is executed.
\&   3) Regexp patterns are typically much smaller than sequences.
.Ve
.PP
Patterns can be quite complex and it is often difficult to
generate the reverse complement pattern. The Bioperl SeqPattern.pm
addresses this problem, providing a convenient set of tools
for working with biological sequence regular expressions.
.PP
Not all patterns have been tested. If you discover a pattern that
is not handled properly by Bio::Tools::SeqPattern.pm, please
send me some email (sac@bioperl.org). Thanks.
.SH "OTHER FEATURES"
.IX Header "OTHER FEATURES"
.SS "Extended Alphabet Support"
.IX Subsection "Extended Alphabet Support"
This module supports the same set of ambiguity codes for nucleotide
sequences as supported by Bio::Seq. These ambiguity codes
define the behavior or the expand method.
.PP
.Vb 10
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& Symbol       Meaning      Nucleic Acid
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  A            A           (A)denine
\&  C            C           (C)ytosine
\&  G            G           (G)uanine
\&  T            T           (T)hymine
\&  U            U           (U)racil
\&  M          A or C        a(M)ino group
\&  R          A or G        pu(R)ine
\&  W          A or T        (W)eak bond
\&  S          C or G        (S)trong bond
\&  Y          C or T        p(Y)rimidine
\&  K          G or T        (K)eto group
\&  V        A or C or G
\&  H        A or C or T
\&  D        A or G or T
\&  B        C or G or T
\&  X      G or A or T or C
\&  N      G or A or T or C
\&  .      G or A or T or C
\&
\&
\&
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& Symbol           Meaning
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& A        Alanine
\& C        Cysteine
\& D        Aspartic Acid
\& E        Glutamic Acid
\& F        Phenylalanine
\& G        Glycine
\& H        Histidine
\& I        Isoleucine
\& K        Lysine
\& L        Leucine
\& M        Methionine
\& N        Asparagine
\& P        Proline
\& Q        Glutamine
\& R        Arginine
\& S        Serine
\& T        Threonine
\& V        Valine
\& W        Tryptophan
\& Y        Tyrosine
\&
\& B        Aspartic Acid, Asparagine
\& Z        Glutamic Acid, Glutamine
\& X        Any amino acid
\& .        Any amino acid
.Ve
.SS "Multiple Format Support"
.IX Subsection "Multiple Format Support"
Ultimately, this module should be able to build SeqPattern.pm objects
using a variety of pattern formats such as ProSite, Blocks, Prints, \s-1GCG,\s0 etc.
Currently, this module only supports patterns using a grep-like syntax.
.SH "USAGE"
.IX Header "USAGE"
A simple demo script called seq_pattern.pl is included in the examples/
directory of the central Bioperl distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Bio::Seq \- Lightweight sequence object.
.PP
Bio::Tools::IUPAC \- The \s-1IUPAC\s0 code for degenerate residues and their
conversion to a regular expression.
.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://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Steve Chervitz, sac\-at\-bioperl.org
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997\-8 Steve Chervitz. All Rights Reserved.
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "new"
.IX Header "new"
.Vb 9
\& Title     : new
\& Usage     : my $seqpat = Bio::Tools::SeqPattern\->new();
\& Purpose   : Verifies that the type is correct for superclass (Bio::Seq.pm)
\&           : and calls superclass constructor last.
\& Returns   : n/a
\& Argument  : Parameters passed to new()
\& Throws    : Exception if the pattern string (seq) is empty.
\& Comments  : The process of creating a new SeqPattern.pm object
\&           : ensures that the pattern string is untained.
.Ve
.PP
See Also   : Bio::Root::Root::new,
             Bio::Seq::_initialize
.SH "alphabet_ok"
.IX Header "alphabet_ok"
.Vb 10
\& Title     : alphabet_ok
\& Usage     : $mypat\->alphabet_ok;
\& Purpose   : Checks for invalid regexp characters.
\&           : Overrides Bio::Seq::alphabet_ok() to allow
\&           : additional regexp characters ,.*()[]<>{}^$
\&           : in addition to the standard genetic alphabet.
\&           : Also untaints the pattern and sets the sequence
\&           : object\*(Aqs sequence to the untained string.
\& Returns   : Boolean (1 | 0)
\& Argument  : n/a
\& Throws    : Exception if the pattern contains invalid characters.
\& Comments  : Does not call the superclass method.
\&           : Actually permits any alphanumeric, not just the
\&           : standard genetic alphabet.
.Ve
.SH "expand"
.IX Header "expand"
.Vb 8
\& Title     : expand
\& Usage     : $seqpat_object\->expand();
\& Purpose   : Expands the sequence pattern using special ambiguity codes.
\& Example   : $pat = $seq_pat\->expand();
\& Returns   : String containing fully expanded sequence pattern
\& Argument  : n/a
\& Throws    : Exception if sequence type is not recognized
\&           : (i.e., is not one of [DR]NA, Amino)
.Ve
.PP
See Also   : \*(L"Extended Alphabet Support\*(R", _expand_pep(), _expand_nuc()
.SH "_expand_pep"
.IX Header "_expand_pep"
.Vb 6
\& Title     : _expand_pep
\& Usage     : n/a; automatically called by expand()
\& Purpose   : Expands peptide patterns
\& Returns   : String (the expanded pattern)
\& Argument  : String (the unexpanded pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : expand(), _expand_nuc()
.SH "_expand_nuc"
.IX Header "_expand_nuc"
.Vb 5
\& Title     : _expand_nuc
\& Purpose   : Expands nucleotide patterns
\& Returns   : String (the expanded pattern)
\& Argument  : String (the unexpanded pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : expand(), _expand_pep()
.SH "revcom"
.IX Header "revcom"
.Vb 10
\& Title     : revcom
\& Usage     : revcom([1]);
\& Purpose   : Forms a pattern capable of recognizing the reverse complement
\&           : version of a nucleotide sequence pattern.
\& Example   : $pattern_object\->revcom();
\&           : $pattern_object\->revcom(1); ## returns expanded rev complement pattern.
\& Returns   : Object reference for a new Bio::Tools::SeqPattern containing
\&           : the revcom of the current pattern as its sequence.
\& Argument  : (1) boolean (optional) (default= false)
\&           :     true : expand the pattern before rev\-complementing.
\&           :     false: don\*(Aqt expand pattern before or after rev\-complementing.
\& Throws    : Exception if called for amino acid sequence pattern.
\& Comments  : This method permits the simultaneous searching of both
\&           : sense and anti\-sense versions of a nucleotide pattern
\&           : by means of a grep\-type of functionality in which any
\&           : number of patterns may be or\-ed into the recognition
\&           : pattern.
\&           : Overrides Bio::Seq::revcom() and calls it first thing.
\&           : The order of _fixpat() calls is critical.
.Ve
.PP
See Also   : Bio::Seq::revcom, \*(L"_fixpat_1\*(R", \*(L"_fixpat_2\*(R", \*(L"_fixpat_3\*(R", \*(L"_fixpat_4\*(R", \*(L"_fixpat_5\*(R"
.SH "backtranslate"
.IX Header "backtranslate"
.Vb 8
\& Title     : backtranslate
\& Usage     : backtranslate();
\& Purpose   : Produce a degenerate oligonucleotide whose translation would produce
\&           : the original protein motif.
\& Example   : $pattern_object\->backtranslate();
\& Returns   : Object reference for a new Bio::Tools::SeqPattern containing
\&           : the reverse translation of the current pattern as its sequence.
\& Throws    : Exception if called for nucleotide sequence pattern.
.Ve
.SH "_fixpat_1"
.IX Header "_fixpat_1"
.Vb 9
\& Title     : _fixpat_1
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all {7,5} \-\-> {5,7}     (Part I)
\&           :           and [T^] \-\-> [^T]      (Part II)
\&           :           and *N   \-\-> N*        (Part III)
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SH "_fixpat_2"
.IX Header "_fixpat_2"
.Vb 8
\& Title     : _fixpat_2
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all {5,7}Y \-\-\-> Y{5,7}
\&           :          and {10,}. \-\-\-> .{10,}
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded, partially reversed pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SH "_fixpat_3"
.IX Header "_fixpat_3"
.Vb 7
\& Title     : _fixpat_3
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all {5,7}(XXX) \-\-\-> (XXX){5,7}
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded, partially reversed pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SH "_fixpat_4"
.IX Header "_fixpat_4"
.Vb 7
\& Title     : _fixpat_4
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all {5,7}[XXX] \-\-\-> [XXX]{5,7}
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded, partially reversed  pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SH "_fixpat_5"
.IX Header "_fixpat_5"
.Vb 8
\& Title     : _fixpat_5
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all *[XXX]  \-\-\-> [XXX]*
\&           :          and *(XXX)  \-\-\-> (XXX)*
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded, partially reversed pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SH "_fixpat_6"
.IX Header "_fixpat_6"
.Vb 9
\& Title     : _fixpat_6
\& Usage     : n/a; called automatically by revcom()
\& Purpose   : Utility method for revcom()
\&           : Converts all ?Y{5,7}  \-\-\-> Y{5,7}?
\&           :          and ?(XXX){5,7}  \-\-\-> (XXX){5,7}?
\&           :          and ?[XYZ]{5,7}  \-\-\-> [XYZ]{5,7}?
\& Returns   : String (the new, partially reversed pattern)
\& Argument  : String (the expanded, partially reversed pattern)
\& Throws    : n/a
.Ve
.PP
See Also   : revcom()
.SS "str"
.IX Subsection "str"
.Vb 5
\& Title   : str
\& Usage   : $obj\->str($newval)
\& Function:
\& Returns : value of str
\& Args    : newvalue (optional)
.Ve
.SS "type"
.IX Subsection "type"
.Vb 5
\& Title   : type
\& Usage   : $obj\->type($newval)
\& Function:
\& Returns : value of type
\& Args    : newvalue (optional)
.Ve
.SH "FOR DEVELOPERS ONLY"
.IX Header "FOR DEVELOPERS ONLY"
.SS "Data Members"
.IX Subsection "Data Members"
Information about the various data members of this module is provided
for those wishing to modify or understand the code. Two things to bear
in mind:
.IP "1 Do \s-1NOT\s0 rely on these in any code outside of this module." 2
.IX Item "1 Do NOT rely on these in any code outside of this module."
All data members are prefixed with an underscore to signify that they
are private.  Always use accessor methods. If the accessor doesn't
exist or is inadequate, create or modify an accessor (and let me know,
too!).
.IP "2 This documentation may be incomplete and out of date." 2
.IX Item "2 This documentation may be incomplete and out of date."
It is easy for this documentation to become obsolete as this module is
still evolving.  Always double check this info and search for members
not described here.
.PP
An instance of Bio::Tools::RestrictionEnzyme.pm is a blessed reference
to a hash containing all or some of the following fields:
.PP
.Vb 3
\& FIELD          VALUE
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& _rev     : The corrected reverse complement of the fully expanded pattern.
\&
\& INHERITED DATA MEMBERS:
\&
\& _seq     : (From Bio::Seq.pm) The original, unexpanded input sequence after untainting.
\& _type    : (From Bio::Seq.pm) \*(AqDna\*(Aq or \*(AqAmino\*(Aq
.Ve