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

NAME

       Bio::Tools::SeqPattern - represent a sequence pattern or motif

SYNOPSIS

        use Bio::Tools::SeqPattern;

        my $pat1     = 'T[GA]AA...TAAT';
        my $pattern1 = Bio::Tools::SeqPattern->new(-SEQ =>$pat1, -TYPE =>'Dna');

        my $pat2     = '[VILM]R(GXX){3,2}...[^PG]';
        my $pattern2 = Bio::Tools::SeqPattern->new(-SEQ =>$pat2, -TYPE =>'Amino');

DESCRIPTION

       Bio::Tools::SeqPattern module encapsulates generic data and methods for manipulating
       regular expressions describing nucleic or amino acid sequence patterns (a.k.a, "motifs"),
       such as the ones produced by Bio::Tools::IUPAC.

       Bio::Tools::SeqPattern is a concrete class that inherits from Bio::Seq.

       This class grew out of a need to have a standard module for doing routine tasks with
       sequence patterns such as:

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

       Other features to look for in the future:

         -- Full pattern syntax checking
         -- Conversion between expanded and condensed forms of the pattern

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.

       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:

          1) You need only one copy of the sequence.
          2) Only one regexp is executed.
          3) Regexp patterns are typically much smaller than sequences.

       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.

       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.

OTHER FEATURES

   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.

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

   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, GCG, etc.  Currently, this module only
       supports patterns using a grep-like syntax.

USAGE

       A simple demo script called seq_pattern.pl is included in the examples/ directory of the
       central Bioperl distribution.

SEE ALSO

       Bio::Seq - Lightweight sequence object.

       Bio::Tools::IUPAC - The IUPAC code for degenerate residues and their conversion to a
       regular expression.

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

       Steve Chervitz, sac-at-bioperl.org

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.

new

        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.

       See Also   : Bio::Root::Root::new,
                    Bio::Seq::_initialize

alphabet_ok

        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's 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.

expand

        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)

       See Also   : "Extended Alphabet Support", _expand_pep(), _expand_nuc()

_expand_pep

        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

       See Also   : expand(), _expand_nuc()

_expand_nuc

        Title     : _expand_nuc
        Purpose   : Expands nucleotide patterns
        Returns   : String (the expanded pattern)
        Argument  : String (the unexpanded pattern)
        Throws    : n/a

       See Also   : expand(), _expand_pep()

revcom

        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't 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.

       See Also   : Bio::Seq::revcom, "_fixpat_1", "_fixpat_2", "_fixpat_3", "_fixpat_4",
       "_fixpat_5"

backtranslate

        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.

_fixpat_1

        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

       See Also   : revcom()

_fixpat_2

        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

       See Also   : revcom()

_fixpat_3

        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

       See Also   : revcom()

_fixpat_4

        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

       See Also   : revcom()

_fixpat_5

        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

       See Also   : revcom()

_fixpat_6

        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

       See Also   : revcom()

   str
        Title   : str
        Usage   : $obj->str($newval)
        Function:
        Returns : value of str
        Args    : newvalue (optional)

   type
        Title   : type
        Usage   : $obj->type($newval)
        Function:
        Returns : value of type
        Args    : newvalue (optional)

FOR DEVELOPERS ONLY

   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:

       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!).

       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.

       An instance of Bio::Tools::RestrictionEnzyme.pm is a blessed reference to a hash
       containing all or some of the following fields:

        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) 'Dna' or 'Amino'