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

NAME

       Bio::Align::DNAStatistics - Calculate some statistics for a DNA alignment

SYNOPSIS

         use Bio::AlignIO;
         use Bio::Align::DNAStatistics;

         my $stats = Bio::Align::DNAStatistics->new();
         my $alignin = Bio::AlignIO->new(-format => 'emboss',
                                        -file   => 't/data/insulin.water');
         my $aln = $alignin->next_aln;
         my $jcmatrix = $stats->distance(-align => $aln,
                                         -method => 'Jukes-Cantor');

         print $jcmatrix->print_matrix;
         ## and for measurements of synonymous /nonsynonymous substitutions ##

         my $in = Bio::AlignIO->new(-format => 'fasta',
                                   -file   => 't/data/nei_gojobori_test.aln');
         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]{'Seq1'}." and ".$results->[0]{'Seq2'}."\n";
         for (sort keys %{$results->[0]} ){
             next if /Seq/;
             printf("%-9s %.4f \n",$_ , $results->[0]{$_});
         }

         my $results2 = $stats->calc_all_KaKs_pairs($alnobj);
         for my $an (@$results2){
             print "comparing ". $an->{'Seq1'}." and ". $an->{'Seq2'}. " \n";
             for (sort keys %$an ){
                 next if /Seq/;
                 printf("%-9s %.4f \n",$_ , $an->{$_});
             }
             print "\n\n";
         }

         my $result3 = $stats->calc_average_KaKs($alnobj, 1000);
         for (sort keys %$result3 ){
             next if /Seq/;
             printf("%-9s %.4f \n",$_ , $result3->{$_});
         }

DESCRIPTION

       This object contains routines for calculating various statistics and distances for DNA
       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 PHLYIP or EMBOSS packages to calculate the
       distances.

       Several different distance method calculations are supported.  Listed in brackets are the
       pattern which will match

       •  JukesCantor [jc|jukes|jukescantor|jukes-cantor]

       •  Uncorrected [jcuncor|uncorrected]

       •  F81 [f81|felsenstein]

       •  Kimura [k2|k2p|k80|kimura]

       •  Tamura [t92|tamura|tamura92]

       •  F84 [f84|felsenstein84]

       •  TajimaNei [tajimanei|tajima\-nei]

       •  JinNei [jinnei|jin\-nei] (not implemented)

       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.

       1. DNA alignment must be based on protein alignment. Use the subroutine "aa_to_dna_aln" in
          Bio::Align::Utilities to achieve this.

       2. Therefore alignment gaps must be in multiples of 3 (representing an aa
          deletion/insertion) and at present must be indicated by a '-' symbol.

       3. Alignment must be solely of coding region and be in reading frame 0 to achieve
          meaningful results

       4. Alignment must therefore be a multiple of 3 nucleotides long.

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

       6. Only the standard codon alphabet is supported at present.

       calc_KaKs_pair() calculates a number of statistics for a named pair of sequences in the
       alignment.

       calc_all_KaKs_pairs() calculates these statistics for all pairwise comparisons in an MSA.
       The statistics returned are:

       •  S_d - Number of synonymous mutations between the 2 sequences.

       •  N_d - Number of non-synonymous mutations between the 2 sequences.

       •  S -  Mean number of  synonymous sites in both sequences.

       •  N -  mean number of  synonymous sites in both sequences.

       •  P_s - proportion of synonymous differences in both sequences given by P_s = S_d/S.

       •  P_n - proportion of non-synonymous differences in both sequences given by P_n = S_n/S.

       •  D_s - estimation of synonymous mutations per synonymous site (by Jukes-Cantor).

       •  D_n - estimation of non-synonymous mutations per non-synonymous site (by Jukes-Cantor).

       •  D_n_var - estimation of variance of D_n .

       •  D_s_var - estimation of variance of S_n.

       •  z_value - calculation of z value.Positive value indicates D_n > D_s, negative value
          indicates D_s > D_n.

       The statistics returned by calc_average_KaKs are:

       •  D_s - Average number of synonymous mutations/synonymous site.

       •  D_n - Average number of non-synonymous mutations/non-synonymous site.

       •  D_s_var - Estimated variance of Ds from bootstrapped alignments.

       •  D_n_var - Estimated variance of Dn from bootstrapped alignments.

       •  z_score - calculation of z value. Positive value indicates D_n >D_s, negative values
          vice versa.

       The design of the code is based around the explanation of the Nei-Gojobori algorithm in
       the excellent book "Molecular Evolution and Phylogenetics" 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.

       Much of the DNA distance code is based on implementations in EMBOSS (Rice et al,
       www.emboss.org) [distmat.c] and PHYLIP (J. Felsenstein et al) [dnadist.c].  Insight also
       gained from Eddy, Durbin, Krogh, & Mitchison.

REFERENCES

       •  D_JukesCantor

          "Phylogenetic Inference", Swoffrod, Olsen, Waddell and Hillis, in Mol. Systematics, 2nd
          ed, 1996, Ch 11.  Derived from "Evolution of Protein Molecules", Jukes & Cantor, in
          Mammalian Prot. Metab., III, 1969, pp. 21-132.

       •  D_Tamura

          K Tamura, Mol. Biol. Evol. 1992, 9, 678.

       •  D_Kimura

          M Kimura, J. Mol. Evol., 1980, 16, 111.

       •  JinNei

          Jin and Nei, Mol. Biol. Evol. 82, 7, 1990.

       •  D_TajimaNei

          Tajima and Nei, Mol. Biol. Evol. 1984, 1, 269.

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 the Bioperl mailing list.  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 of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR - Jason Stajich

       Email jason-AT-bioperl.org

CONTRIBUTORS

       Richard Adams, richard.adams@ed.ac.uk

APPENDIX

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

   new
        Title   : new
        Usage   : my $obj = Bio::Align::DNAStatistics->new();
        Function: Builds a new Bio::Align::DNAStatistics object
        Returns : Bio::Align::DNAStatistics
        Args    : none

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

   available_distance_methods
        Title   : available_distance_methods
        Usage   : my @methods = $stats->available_distance_methods();
        Function: Enumerates the possible distance methods
        Returns : Array of strings
        Args    : none

   D - distance methods
   D_JukesCantor
        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

   D_F81
        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

   D_Uncorrected
        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, 'NA' is
                  substituted for the distance.
        Returns : L<Bio::Matrix::PhylipDist>
        Args    : L<Bio::Align::AlignI> (DNA Alignment)
                  [optional] gap penalty

   D_Kimura
        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

   D_Kimura_variance
        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

   D_Tamura
        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

   D_F84
        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

   D_TajimaNei
        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

   D_JinNei
        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

   transversions
        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

   transitions
        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

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

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

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

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

   get_syn_changes
        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

   dnds_pattern_number
        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 ('patterns' in PAML notation)
        Args    : A Bio::Align::AlignI compliant object such as a
                   Bio::SimpleAlign object.