NAME

       Bio::Tools::SeqWords - Object holding n-mer statistics for a sequence

SYNOPSIS

         # Create the SeqWords object, e.g.:

         my $inputstream = Bio::SeqIO->new(-file => "seqfile",
                                                -format => 'Fasta');
         my $seqobj = $inputstream->next_seq();
         my $seq_word = Bio::Tools::SeqWords->new(-seq => $seqobj);

         # Or:
         my $seqobj = Bio::PrimarySeq->new(-seq => "agggtttccc",
                                           -alphabet => 'dna',
                                           -id => 'test');
         my $seq_word  =  Bio::Tools::SeqWords->new(-seq => $seqobj);

         # obtain a hash of word counts, eg:
         my $hash_ref = $seq_stats->count_words($word_length);

         # display hash table, eg:
         my %hash = %$hash_ref;
         foreach my $key(sort keys %hash)
         {
           print "\n$key\t$hash{$key}";
         }

         # Or:

         my $hash_ref =
            Bio::Tools::SeqWords->count_words($seqobj,$word_length);

DESCRIPTION

       Bio::Tools::SeqWords is a featherweight object for the calculation of n-mer word
       occurrences in a single sequence.  It is envisaged that the object will be useful for
       construction of scripts which use n-mer word tables as the raw material for statistical
       calculations; for instance, hexamer frequency for the calculation of coding protential, or
       the calculation of periodicity in repetitive DNA.  Triplet frequency is already handled by
       Bio::Tools::SeqStats (author: Peter Schattner).

       There are a few possible applications for protein, e.g. hypothesised amino acid 7-mers in
       heat shock proteins, or proteins with multiple simple motifs.  Sometimes these protein
       periodicities are best seen when the amino acid alphabet is truncated, e.g. Shulman
       alphabet.  Since there are quite a few of these shortened alphabets, this module does not
       specify any particular alphabet.

       See Synopsis above for object creation code.

   Rationale
       Take a sequence object and create an object for the purposes of holding n-mer word
       statistics about that sequence. The sequence can be nucleic acid or protein.

       In count_words() the words are counted in a non-overlapping manner, ie. in the style of a
       codon table, but with any word length.

       In count_overlap_words() the words are counted in an overlapping manner.

       For counts on opposite strand (DNA/RNA), a reverse complement method should be performed,
       and then the count repeated.

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://redmine.open-bio.org/projects/bioperl/

AUTHOR

       Derek Gatherer, in the loosest sense of the word 'author'.  The general shape of the
       module is lifted directly from the SeqStat module of Peter Schattner. The central
       subroutine to count the words is adapted from original code provided by Dave Shivak, in
       response to a query on the bioperl mailing list.  At least 2 other people provided
       alternative means (equally good but not used in the end) of performing the same
       calculation.  Thanks to all for your assistance.

CONTRIBUTORS

       Jason Stajich, jason-at-bioperl.org

APPENDIX

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

   count_words
        Title   : count_words
        Usage   : $word_count = $seq_stats->count_words($word_length)
                       or
                  $word_count = $seq_stats->Bio::Tools::SeqWords->($seqobj,$word_length);
        Function: Counts non-overlapping words within a string, any alphabet is
                  used
        Example : a sequence ACCGTCCGT, counted at word length 4, will give the hash
                  {ACCG => 1, TCCG => 1}
        Returns : Reference to a hash in which keys are words (any length) of the
                  alphabet used and values are number of occurrences of the word
                  in the sequence.
        Args    : Word length as scalar and, reference to sequence object if
                  required

                  Throws an exception word length is not a positive integer
                  or if word length is longer than the sequence.

   count_overlap_words
        Title   : count_overlap_words
        Usage   : $word_count = $word_obj->count_overlap_words($word_length);
        Function: Counts overlapping words within a string, any alphabet is used
        Example : A sequence ACCAACCA, counted at word length 4, will give the hash
                       {ACCA=>2, CCAA=>1, CAAC=>1, AACC=>1}
        Returns : Reference to a hash in which keys are words (any length) of the
                  alphabet used and values are number of occurrences of the word in
                  the sequence.
        Args    : Word length as scalar

                  Throws an exception if word length is not a positive integer
                  or if word length is longer than the sequence.