.\" 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::Align::DNAStatistics 3pm"
.TH Bio::Align::DNAStatistics 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::Align::DNAStatistics \- Calculate some statistics for a DNA alignment
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Bio::AlignIO;
\&  use Bio::Align::DNAStatistics;
\&
\&  my $stats = Bio::Align::DNAStatistics\->new();
\&  my $alignin = Bio::AlignIO\->new(\-format => \*(Aqemboss\*(Aq,
\&                                 \-file   => \*(Aqt/data/insulin.water\*(Aq);
\&  my $aln = $alignin\->next_aln;
\&  my $jcmatrix = $stats\->distance(\-align => $aln, 
\&                                  \-method => \*(AqJukes\-Cantor\*(Aq);
\&
\&  print $jcmatrix\->print_matrix;
\&  ## and for measurements of synonymous /nonsynonymous substitutions ##
\&
\&  my $in = Bio::AlignIO\->new(\-format => \*(Aqfasta\*(Aq,
\&                            \-file   => \*(Aqt/data/nei_gojobori_test.aln\*(Aq);
\&  my $alnobj = $in\->next_aln;
\&  my ($seq1id,$seq2id) = map { $_\->display_id } $alnobj\->each_seq;
\&  my $results = $stats\->calc_KaKs_pair($alnobj, $seq1id, $seq2id);
\&  print "comparing ".$results\->[0]{\*(AqSeq1\*(Aq}." and ".$results\->[0]{\*(AqSeq2\*(Aq}."\en";
\&  for (sort keys %{$results\->[0]} ){
\&      next if /Seq/;
\&      printf("%\-9s %.4f \en",$_ , $results\->[0]{$_});
\&  }
\&
\&  my $results2 = $stats\->calc_all_KaKs_pairs($alnobj);
\&  for my $an (@$results2){
\&      print "comparing ". $an\->{\*(AqSeq1\*(Aq}." and ". $an\->{\*(AqSeq2\*(Aq}. " \en";
\&      for (sort keys %$an ){
\&          next if /Seq/;
\&          printf("%\-9s %.4f \en",$_ , $an\->{$_});
\&      }
\&      print "\en\en";
\&  }
\&
\&  my $result3 = $stats\->calc_average_KaKs($alnobj, 1000);
\&  for (sort keys %$result3 ){
\&      next if /Seq/;
\&      printf("%\-9s %.4f \en",$_ , $result3\->{$_});
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object contains routines for calculating various statistics and
distances for \s-1DNA\s0 alignments.  The routines are not well tested and do
contain errors at this point.  Work is underway to correct them, but
do not expect this code to give you the right answer currently!  Use
dnadist/distmat in the \s-1PHLYIP\s0 or \s-1EMBOSS\s0 packages to calculate the
distances.
.PP
Several different distance method calculations are supported.  Listed
in brackets are the pattern which will match
.IP "\(bu" 3
JukesCantor [jc|jukes|jukescantor|jukes\-cantor]
.IP "\(bu" 3
Uncorrected [jcuncor|uncorrected]
.IP "\(bu" 3
F81 [f81|felsenstein]
.IP "\(bu" 3
Kimura [k2|k2p|k80|kimura]
.IP "\(bu" 3
Tamura [t92|tamura|tamura92]
.IP "\(bu" 3
F84 [f84|felsenstein84]
.IP "\(bu" 3
TajimaNei [tajimanei|tajima\e\-nei]
.IP "\(bu" 3
JinNei [jinnei|jin\e\-nei] (not implemented)
.PP
There are also three methods to calculate the ratio of synonymous to
non-synonymous mutations.  All are implementations of the Nei-Gojobori
evolutionary pathway method and use the Jukes-Cantor method of
nucleotide substitution. This method works well so long as the
nucleotide frequencies are roughly equal and there is no significant
transition/transversion bias.  In order to use these methods there are
several pre-requisites for the alignment.
.IP "1." 3
\&\s-1DNA\s0 alignment must be based on protein alignment. Use the subroutine
\&\*(L"aa_to_dna_aln\*(R" in Bio::Align::Utilities to achieve this.
.IP "2." 3
Therefore alignment gaps must be in multiples of 3 (representing an aa
deletion/insertion) and at present must be indicated by a '\-' symbol.
.IP "3." 3
Alignment must be solely of coding region and be in reading frame 0 to
achieve meaningful results
.IP "4." 3
Alignment must therefore be a multiple of 3 nucleotides long.
.IP "5." 3
All sequences must be the same length (including gaps). This should be
the case anyway if the sequences have been automatically aligned using
a program like Clustal.
.IP "6." 3
Only the standard codon alphabet is supported at present.
.PP
\&\fBcalc_KaKs_pair()\fR calculates a number of statistics for a named pair of
sequences in the alignment.
.PP
\&\fBcalc_all_KaKs_pairs()\fR calculates these statistics for all pairwise
comparisons in an \s-1MSA.\s0  The statistics returned are:
.IP "\(bu" 3
S_d \- Number of synonymous mutations between the 2 sequences.
.IP "\(bu" 3
N_d \- Number of non-synonymous mutations between the 2 sequences.
.IP "\(bu" 3
S \-  Mean number of  synonymous sites in both sequences.
.IP "\(bu" 3
N \-  mean number of  synonymous sites in both sequences.
.IP "\(bu" 3
P_s \- proportion of synonymous differences in both sequences given by
P_s = S_d/S.
.IP "\(bu" 3
P_n \- proportion of non-synonymous differences in both sequences given
by P_n = S_n/S.
.IP "\(bu" 3
D_s \- estimation of synonymous mutations per synonymous site (by
Jukes-Cantor).
.IP "\(bu" 3
D_n \- estimation of non-synonymous mutations per non-synonymous site (by
Jukes-Cantor).
.IP "\(bu" 3
D_n_var \- estimation of variance of D_n .
.IP "\(bu" 3
D_s_var \- estimation of variance of S_n.
.IP "\(bu" 3
z_value \- calculation of z value.Positive value indicates D_n > D_s,
negative value indicates D_s > D_n.
.PP
The statistics returned by calc_average_KaKs are:
.IP "\(bu" 3
D_s \- Average number of synonymous mutations/synonymous site.
.IP "\(bu" 3
D_n \- Average number of non-synonymous mutations/non\-synonymous site.
.IP "\(bu" 3
D_s_var \- Estimated variance of Ds from bootstrapped alignments.
.IP "\(bu" 3
D_n_var \- Estimated variance of Dn from bootstrapped alignments.
.IP "\(bu" 3
z_score \- calculation of z value. Positive value indicates D_n >D_s,
negative values vice versa.
.PP
The design of the code is based around the explanation of the
Nei-Gojobori algorithm in the excellent book \*(L"Molecular Evolution and
Phylogenetics\*(R" by Nei and Kumar, published by Oxford University
Press. The methods have been tested using the worked example 4.1 in
the book, and reproduce those results. If people like having this sort
of analysis in BioPerl other methods for estimating Ds and Dn can be
provided later.
.PP
Much of the \s-1DNA\s0 distance code is based on implementations in \s-1EMBOSS\s0
(Rice et al, www.emboss.org) [distmat.c] and \s-1PHYLIP\s0 (J. Felsenstein et
al) [dnadist.c].  Insight also gained from Eddy, Durbin, Krogh, &
Mitchison.
.SH "REFERENCES"
.IX Header "REFERENCES"
.IP "\(bu" 3
D_JukesCantor
.Sp
\&\*(L"Phylogenetic Inference\*(R", Swoffrod, Olsen, Waddell and Hillis, in
Mol. Systematics, 2nd ed, 1996, Ch 11.  Derived from \*(L"Evolution of
Protein Molecules\*(R", Jukes & Cantor, in Mammalian Prot. Metab., \s-1III,
1969,\s0 pp. 21\-132.
.IP "\(bu" 3
D_Tamura
.Sp
K Tamura, Mol. Biol. Evol. 1992, 9, 678.
.IP "\(bu" 3
D_Kimura
.Sp
M Kimura, J. Mol. Evol., 1980, 16, 111.
.IP "\(bu" 3
JinNei
.Sp
Jin and Nei, Mol. Biol. Evol. 82, 7, 1990.
.IP "\(bu" 3
D_TajimaNei
.Sp
Tajima and Nei, Mol. Biol. Evol. 1984, 1, 269.
.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
the Bioperl mailing list.  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
of 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 \- Jason Stajich"
.IX Header "AUTHOR - Jason Stajich"
Email jason\-AT\-bioperl.org
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Richard Adams, richard.adams@ed.ac.uk
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 5
\& Title   : new
\& Usage   : my $obj = Bio::Align::DNAStatistics\->new();
\& Function: Builds a new Bio::Align::DNAStatistics object 
\& Returns : Bio::Align::DNAStatistics
\& Args    : none
.Ve
.SS "distance"
.IX Subsection "distance"
.Vb 10
\& Title   : distance
\& Usage   : my $distance_mat = $stats\->distance(\-align  => $aln, 
\&                                               \-method => $method);
\& Function: Calculates a distance matrix for all pairwise distances of
\&           sequences in an alignment.
\& Returns : L<Bio::Matrix::PhylipDist> object
\& Args    : \-align  => Bio::Align::AlignI object
\&           \-method => String specifying specific distance method 
\&                      (implementing class may assume a default)
\&See also: L<Bio::Matrix::PhylipDist>
.Ve
.SS "available_distance_methods"
.IX Subsection "available_distance_methods"
.Vb 5
\& Title   : available_distance_methods
\& Usage   : my @methods = $stats\->available_distance_methods();
\& Function: Enumerates the possible distance methods
\& Returns : Array of strings
\& Args    : none
.Ve
.SS "D \- distance methods"
.IX Subsection "D - distance methods"
.SS "D_JukesCantor"
.IX Subsection "D_JukesCantor"
.Vb 7
\& Title   : D_JukesCantor
\& Usage   : my $d = $stat\->D_JukesCantor($aln)
\& Function: Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using the Jukes\-Cantor 1 parameter model. 
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
\&           double \- gap penalty
.Ve
.SS "D_F81"
.IX Subsection "D_F81"
.Vb 8
\& Title   : D_F81
\& Usage   : my $d = $stat\->D_F81($aln)
\& Function: Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using the Felsenstein 1981 distance model. 
\&           Relaxes the assumption of equal base frequencies that is
\&           in JC.
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
.Ve
.SS "D_Uncorrected"
.IX Subsection "D_Uncorrected"
.Vb 8
\& Title   : D_Uncorrected
\& Usage   : my $d = $stats\->D_Uncorrected($aln)
\& Function: Calculate a distance D, no correction for multiple substitutions 
\&           is used.  In rare cases where sequences may not overlap, \*(AqNA\*(Aq is
\&           substituted for the distance.
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> (DNA Alignment)
\&           [optional] gap penalty
.Ve
.SS "D_Kimura"
.IX Subsection "D_Kimura"
.Vb 6
\& Title   : D_Kimura
\& Usage   : my $d = $stat\->D_Kimura($aln)
\& Function: Calculates D (pairwise distance) between all pairs of sequences 
\&           in an alignment using the Kimura 2 parameter model.
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
.Ve
.SS "D_Kimura_variance"
.IX Subsection "D_Kimura_variance"
.Vb 8
\& Title   : D_Kimura
\& Usage   : my $d = $stat\->D_Kimura_variance($aln)
\& Function: Calculates D (pairwise distance) between all pairs of sequences 
\&           in an alignment using the Kimura 2 parameter model.
\& Returns : array of 2 L<Bio::Matrix::PhylipDist>,
\&           the first is the Kimura distance and the second is
\&           a matrix of variance V(K)
\& Args    : L<Bio::Align::AlignI> of DNA sequences
.Ve
.SS "D_Tamura"
.IX Subsection "D_Tamura"
.Vb 5
\& Title   : D_Tamura
\& Usage   : Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using Tamura 1992 distance model. 
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
.Ve
.SS "D_F84"
.IX Subsection "D_F84"
.Vb 7
\& Title   : D_F84
\& Usage   : my $d = $stat\->D_F84($aln)
\& Function: Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using the Felsenstein 1984 distance model. 
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
\&           [optional] double \- gap penalty
.Ve
.SS "D_TajimaNei"
.IX Subsection "D_TajimaNei"
.Vb 6
\& Title   : D_TajimaNei
\& Usage   : my $d = $stat\->D_TajimaNei($aln)
\& Function: Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using the TajimaNei 1984 distance model. 
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : Bio::Align::AlignI of DNA sequences
.Ve
.SS "D_JinNei"
.IX Subsection "D_JinNei"
.Vb 6
\& Title   : D_JinNei
\& Usage   : my $d = $stat\->D_JinNei($aln)
\& Function: Calculates D (pairwise distance) between 2 sequences in an 
\&           alignment using the Jin\-Nei 1990 distance model. 
\& Returns : L<Bio::Matrix::PhylipDist>
\& Args    : L<Bio::Align::AlignI> of DNA sequences
.Ve
.SS "transversions"
.IX Subsection "transversions"
.Vb 6
\& Title   : transversions
\& Usage   : my $transversions = $stats\->transversion($aln);
\& Function: Calculates the number of transversions between two sequences in 
\&           an alignment
\& Returns : integer
\& Args    : Bio::Align::AlignI
.Ve
.SS "transitions"
.IX Subsection "transitions"
.Vb 5
\& Title   : transitions
\& Usage   : my $transitions = Bio::Align::DNAStatistics\->transitions($aln);
\& Function: Calculates the number of transitions in a given DNA alignment
\& Returns : integer representing the number of transitions
\& Args    : Bio::Align::AlignI object
.Ve
.SS "Data Methods"
.IX Subsection "Data Methods"
.SS "pairwise_stats"
.IX Subsection "pairwise_stats"
.Vb 5
\& Title   : pairwise_stats
\& Usage   : $obj\->pairwise_stats($newval)
\& Function: 
\& Returns : value of pairwise_stats
\& Args    : newvalue (optional)
.Ve
.SS "calc_KaKs_pair"
.IX Subsection "calc_KaKs_pair"
.Vb 9
\& Title    : calc_KaKs_pair
\& Useage   : my $results = $stats\->calc_KaKs_pair($alnobj,
\&            $name1, $name2).
\& Function : calculates Nei\-Gojobori statistics for pairwise 
\&            comparison.
\& Args     : A Bio::Align::AlignI compliant object such as a 
\&            Bio::SimpleAlign object, and 2 sequence name strings.
\& Returns  : a reference to a hash of statistics with keys as 
\&            listed in Description.
.Ve
.SS "calc_all_KaKs_pairs"
.IX Subsection "calc_all_KaKs_pairs"
.Vb 8
\& Title    : calc_all_KaKs_pairs
\& Useage   : my $results2 = $stats\->calc_KaKs_pair($alnobj).
\& Function : Calculates Nei_gojobori statistics for all pairwise
\&            combinations in sequence.
\& Arguments: A Bio::Align::ALignI compliant object such as
\&            a Bio::SimpleAlign object.
\& Returns  : A reference to an array of hashes of statistics of
\&            all pairwise comparisons in the alignment.
.Ve
.SS "calc_average_KaKs"
.IX Subsection "calc_average_KaKs"
.Vb 8
\& Title    : calc_average_KaKs.  
\& Useage   : my $res= $stats\->calc_average_KaKs($alnobj, 1000).
\& Function : calculates Nei_Gojobori stats for average of all 
\&            sequences in the alignment.
\& Args     : A Bio::Align::AlignI compliant object such as a
\&            Bio::SimpleAlign object, number of bootstrap iterations
\&            (default 1000).
\& Returns  : A reference to a hash of statistics as listed in Description.
.Ve
.SS "get_syn_changes"
.IX Subsection "get_syn_changes"
.Vb 10
\& Title   : get_syn_changes
\& Usage   : Bio::Align::DNAStatitics\->get_syn_changes
\& Function: Generate a hashref of all pairwise combinations of codns
\&           differing by 1
\& Returns : Symetic matrix using hashes
\&           First key is codon
\&           and each codon points to a hashref of codons
\&           the values of which describe type of change.
\&           my $type = $hash{$codon1}\->{$codon2};
\&           values are :
\&             1   synonymous
\&             0   non\-syn
\&            \-1   either codon is a stop codon
\& Args    : none
.Ve
.SS "dnds_pattern_number"
.IX Subsection "dnds_pattern_number"
.Vb 6
\& Title   : dnds_pattern_number
\& Usage   : my $patterns = $stats\->dnds_pattern_number($alnobj);
\& Function: Counts the number of codons with no gaps in the MSA
\& Returns : Number of codons with no gaps (\*(Aqpatterns\*(Aq in PAML notation)
\& Args    : A Bio::Align::AlignI compliant object such as a
\&            Bio::SimpleAlign object.
.Ve