.\" 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::SeqWords 3pm"
.TH Bio::Tools::SeqWords 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::SeqWords \- Object holding n\-mer statistics for a sequence
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  # Create the SeqWords object, e.g.:
\&
\&  my $inputstream = Bio::SeqIO\->new(\-file => "seqfile", 
\&                                         \-format => \*(AqFasta\*(Aq);
\&  my $seqobj = $inputstream\->next_seq();
\&  my $seq_word = Bio::Tools::SeqWords\->new(\-seq => $seqobj);
\&
\&  # Or:
\&  my $seqobj = Bio::PrimarySeq\->new(\-seq => "agggtttccc",
\&                                    \-alphabet => \*(Aqdna\*(Aq,
\&                                    \-id => \*(Aqtest\*(Aq);
\&  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 "\en$key\et$hash{$key}";
\&  }
\&
\&  # Or:
\&
\&  my $hash_ref =
\&     Bio::Tools::SeqWords\->count_words($seqobj,$word_length);
.Ve
.SH "DESCRIPTION"
.IX Header "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 \s-1DNA.\s0  Triplet
frequency is already handled by Bio::Tools::SeqStats (author: Peter
Schattner).
.PP
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.
.PP
See Synopsis above for object creation code.
.SS "Rationale"
.IX Subsection "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.
.PP
In \fBcount_words()\fR the words are counted in a non-overlapping manner,
ie. in the style of a codon table, but with any word length.
.PP
In \fBcount_overlap_words()\fR the words are counted in an overlapping
manner.
.PP
For counts on opposite strand (\s-1DNA/RNA\s0), a reverse complement method
should be performed, and then the count repeated.
.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"
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.
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Jason Stajich, jason\-at\-bioperl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "count_words"
.IX Subsection "count_words"
.Vb 10
\& 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.
.Ve
.SS "count_overlap_words"
.IX Subsection "count_overlap_words"
.Vb 9
\& 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.
.Ve