.\" 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::SeqStats 3pm"
.TH Bio::Tools::SeqStats 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::SeqStats \- Object holding statistics for one 
particular sequence
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # build a primary nucleic acid or protein sequence object somehow
\&  # then build a statistics object from the sequence object
\&
\&  $seqobj = Bio::PrimarySeq\->new(\-seq      => \*(AqACTGTGGCGTCAACTG\*(Aq,
\&                                 \-alphabet => \*(Aqdna\*(Aq,
\&                                 \-id       => \*(Aqtest\*(Aq);
\&  $seq_stats  =  Bio::Tools::SeqStats\->new(\-seq => $seqobj);
\&
\&  # obtain a hash of counts of each type of monomer
\&  # (i.e. amino or nucleic acid)
\&  print "\enMonomer counts using statistics object\en";
\&  $seq_stats  =  Bio::Tools::SeqStats\->new(\-seq=>$seqobj);
\&  $hash_ref = $seq_stats\->count_monomers();  # e.g. for DNA sequence
\&  foreach $base (sort keys %$hash_ref) {
\&      print "Number of bases of type ", $base, "= ", 
\&         %$hash_ref\->{$base},"\en";
\&  }
\&
\&  # obtain the count directly without creating a new statistics object
\&  print "\enMonomer counts without statistics object\en";
\&  $hash_ref = Bio::Tools::SeqStats\->count_monomers($seqobj);
\&  foreach $base (sort keys %$hash_ref) {
\&      print "Number of bases of type ", $base, "= ", 
\&         %$hash_ref\->{$base},"\en";
\&  }
\&
\&
\&  # obtain hash of counts of each type of codon in a nucleic acid sequence
\&  print "\enCodon counts using statistics object\en";
\&  $hash_ref = $seq_stats\-> count_codons();  # for nucleic acid sequence
\&  foreach $base (sort keys %$hash_ref) {
\&      print "Number of codons of type ", $base, "= ", 
\&         %$hash_ref\->{$base},"\en";
\&  }
\&
\&  #  or
\&  print "\enCodon counts without statistics object\en";
\&  $hash_ref = Bio::Tools::SeqStats\->count_codons($seqobj);
\&  foreach $base (sort keys %$hash_ref) {
\&      print "Number of codons of type ", $base, "= ", 
\&         %$hash_ref\->{$base},"\en";
\&  }
\&
\&  # Obtain the molecular weight of a sequence. Since the sequence 
\&  # may contain ambiguous monomers, the molecular weight is returned 
\&  # as a (reference to) a two element array containing greatest lower 
\&  # bound (GLB) and least upper bound (LUB) of the molecular weight
\&  $weight = $seq_stats\->get_mol_wt();
\&  print "\enMolecular weight (using statistics object) of sequence ", 
\&          $seqobj\->id(), " is between ", $$weight[0], " and " ,
\&          $$weight[1], "\en";
\&
\&  #  or
\&  $weight = Bio::Tools::SeqStats\->get_mol_wt($seqobj);
\&  print "\enMolecular weight (without statistics object) of sequence ", 
\&        $seqobj\->id(), " is between ", $$weight[0], " and " ,
\&        $$weight[1], "\en";
\&
\&  # Calculate mean Kyte\-Doolittle hydropathicity (aka "gravy" score)
\&  my $prot = Bio::PrimarySeq\->new(\-seq=>\*(AqMSFVLVAPDMLATAAADVVQIGSAVSAGS\*(Aq,
\&                                  \-alphabet=>\*(Aqprotein\*(Aq);
\&  my $gravy = Bio::Tools::SeqStats\->hydropathicity($seqobj);
\&  print "might be hydropathic" if $gravy > 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::Tools::SeqStats is a lightweight object for the calculation of
simple statistical and numerical properties of a sequence. By
\&\*(L"lightweight\*(R" I mean that only \*(L"primary\*(R" sequences are handled by the
object.  The calling script needs to create the appropriate primary
sequence to be passed to SeqStats if statistics on a sequence feature
are required.  Similarly if a codon count is desired for a
frame-shifted sequence and/or a negative strand sequence, the calling
script needs to create that sequence and pass it to the SeqStats
object.
.PP
Nota that nucleotide sequences in bioperl do not strictly separate \s-1RNA\s0
and \s-1DNA\s0 sequences. By convention, sequences from \s-1RNA\s0 molecules are
shown as is they were \s-1DNA.\s0 Objects are supposed to make the
distinction when needed. This class is one of the few where this
distinctions needs to be made. Internally, it changes all Ts into Us
before weight and monomer count.
.PP
SeqStats can be called in two distinct manners.  If only a single
computation is required on a given sequence object, the method can be
called easily using the SeqStats object directly:
.PP
.Vb 1
\&  $weight = Bio::Tools::SeqStats\->get_mol_wt($seqobj);
.Ve
.PP
Alternately, if several computations will be required on a given
sequence object, an \*(L"instance\*(R" statistics object can be constructed
and used for the method calls:
.PP
.Vb 5
\&  $seq_stats = Bio::Tools::SeqStats\->new($seqobj);
\&  $monomers = $seq_stats\->count_monomers();
\&  $codons = $seq_stats\->count_codons();
\&  $weight = $seq_stats\->get_mol_wt();
\&  $gravy = $seq_stats\->hydropathicity();
.Ve
.PP
As currently implemented the object can return the following values
from a sequence:
.IP "\(bu" 4
The molecular weight of the sequence: \fBget_mol_wt()\fR
.IP "\(bu" 4
The number of each type of monomer present: \fBcount_monomers()\fR
.IP "\(bu" 4
The number of each codon present in a nucleic acid sequence:
\&\fBcount_codons()\fR
.IP "\(bu" 4
The mean hydropathicity (\*(L"gravy\*(R" score) of a protein:
\&\fBhydropathicity()\fR
.PP
For \s-1DNA\s0 and \s-1RNA\s0 sequences single-stranded weights are returned. The
molecular weights are calculated for neutral, or not ionized,
nucleic acids. The returned weight is the sum of the
base-sugar-phosphate residues of the chain plus one weight of water to
to account for the additional \s-1OH\s0 on the phosphate of the 5' residue
and the additional H on the sugar ring of the 3' residue.  Note that
this leads to a difference of 18 in calculated molecular weights
compared to some other available programs (e.g. Informax VectorNTI).
.PP
Note that since sequences may contain ambiguous monomers (e.g. \*(L"M\*(R",
meaning \*(L"A\*(R" or \*(L"C\*(R" in a nucleic acid sequence), the method get_mol_wt
returns a two-element array containing the greatest lower bound and
least upper bound of the molecule. For a sequence with no ambiguous
monomers, the two elements of the returned array will be equal. The
method \fBcount_codons()\fR handles ambiguous bases by simply counting all
ambiguous codons together and issuing a warning to that effect.
.SH "DEVELOPERS NOTES"
.IX Header "DEVELOPERS NOTES"
Ewan moved it from Bio::SeqStats to Bio::Tools::SeqStats
.PP
Heikki made tiny adjustments (+/\- 0.01 daltons) to amino acid
molecular weights to have the output match values in SWISS-PROT.
.PP
Torsten added hydropathicity calculation.
.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 the web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Peter Schattner"
.IX Header "AUTHOR - Peter Schattner"
Email schattner \s-1AT\s0 alum.mit.edu
.SH "CONTRIBUTOR \- Torsten Seemann"
.IX Header "CONTRIBUTOR - Torsten Seemann"
Email torsten.seemann \s-1AT\s0 infotech.monash.edu.au
.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_monomers"
.IX Subsection "count_monomers"
.Vb 10
\& Title   : count_monomers
\& Usage   : $rcount = $seq_stats\->count_monomers();
\&           or $rcount = $seq_stats\->Bio::Tools::SeqStats\->($seqobj);
\& Function: Counts the number of each type of monomer (amino acid or
\&                base) in the sequence.
\&           Ts are counted as Us in RNA sequences.
\& Example :
\& Returns : Reference to a hash in which keys are letters of the
\&           genetic alphabet used and values are number of occurrences
\&           of the letter in the sequence.
\& Args    : None or reference to sequence object
\& Throws  : Throws an exception if type of sequence is unknown (ie amino
\&           or nucleic)or if unknown letter in alphabet. Ambiguous
\&           elements are allowed.
.Ve
.SS "get_mol_wt"
.IX Subsection "get_mol_wt"
.Vb 6
\& Title   : get_mol_wt
\& Usage   : $wt = $seqobj\->get_mol_wt() or
\&           $wt = Bio::Tools::SeqStats \->get_mol_wt($seqobj);
\& Function: Calculate molecular weight of sequence
\&           Ts are counted as Us in RNA sequences.
\& Example :
\&
\& Returns : Reference to two element array containing lower and upper
\&           bounds of molecule molecular weight. For DNA and RNA
\&           sequences single\-stranded weights are returned. If
\&           sequence contains no ambiguous elements, both entries in
\&           array are equal to molecular weight of molecule.
\& Args    : None or reference to sequence object
\& Throws  : Exception if type of sequence is unknown (ie not amino or
\&           nucleic) or if unknown letter in alphabet. Ambiguous
\&           elements are allowed.
.Ve
.SS "count_codons"
.IX Subsection "count_codons"
.Vb 12
\& Title   : count_codons
\& Usage   : $rcount = $seqstats\->count_codons() or
\&           $rcount = Bio::Tools::SeqStats\->count_codons($seqobj)
\& Function: Counts the number of each type of codons for a dna or rna 
\&           sequence, starting at the 1st triple of the input sequence.
\& Example :
\& Returns : Reference to a hash in which keys are codons of the genetic
\&           alphabet used and values are number of occurrences of the
\&           codons in the sequence. All codons with "ambiguous" bases
\&           are counted together.
\& Args    : None or sequence object
\& Throws  : an exception if type of sequence is unknown or protein.
.Ve
.SS "hydropathicity"
.IX Subsection "hydropathicity"
.Vb 3
\& Title   : hydropathicity
\& Usage   : $gravy = $seqstats\->hydropathicity(); or
\&           $gravy = Bio::Tools::SeqStats\->hydropathicity($seqobj);
\&
\& Function: Calculates the mean Kyte\-Doolittle hydropathicity for a
\&           protein sequence. Also known as the "gravy" score. Refer to 
\&           Kyte J., Doolittle R.F., J. Mol. Biol. 157:105\-132(1982). 
\& Example :
\& Returns : float 
\& Args    : None or reference to sequence object
\&
\& Throws  : an exception if type of sequence is not protein.
.Ve
.SS "_is_alphabet_strict"
.IX Subsection "_is_alphabet_strict"
.Vb 8
\& Title   :  _is_alphabet_strict
\& Usage   :
\& Function: internal function to determine whether there are
\&           any ambiguous elements in the current sequence
\& Example :
\& Returns : 1 if strict alphabet is being used,
\&           0 if ambiguous elements are present
\& Args    :
\&
\& Throws  : an exception if type of sequence is unknown (ie amino or
\&           nucleic) or if unknown letter in alphabet. Ambiguous
\&           monomers are allowed.
.Ve
.SS "_print_data"
.IX Subsection "_print_data"
.Vb 5
\& Title   : _print_data
\& Usage   : $seqobj\->_print_data() or Bio::Tools::SeqStats\->_print_data();
\& Function: Displays dna / rna parameters (used for debugging)
\& Returns : 1
\& Args    : None
.Ve
.PP
Used for debugging.