Provided by: libbio-perl-perl_1.7.2-2_all bug

NAME

       Bio::PopGen::Statistics - Population Genetics statistical tests

SYNOPSIS

         use Bio::PopGen::Statistics;
         use Bio::AlignIO;
         use Bio::PopGen::IO;
         use Bio::PopGen::Simulation::Coalescent;

         my $sim = Bio::PopGen::Simulation::Coalescent->new( -sample_size => 12);

         my $tree = $sim->next_tree;

         $sim->add_Mutations($tree,20);

         my $stats = Bio::PopGen::Statistics->new();
         my $individuals = [ $tree->get_leaf_nodes];
         my $pi = $stats->pi($individuals);
         my $D  = $stats->tajima_D($individuals);

         # Alternatively to do this on input data from
         # See the tests in t/PopGen.t for more examples
         my $parser = Bio::PopGen::IO->new(-format => 'prettybase',
                                          -file   => 't/data/popstats.prettybase');
         my $pop = $parser->next_population;
         # Note that you can also call the stats as a class method if you like
         # the only reason to instantiate it (as above) is if you want
         # to set the verbosity for debugging
         $pi     = Bio::PopGen::Statistics->pi($pop);
         $theta  = Bio::PopGen::Statistics->theta($pop);

         # Pi and Theta also take additional arguments,
         # see the documentation for more information

         use Bio::PopGen::Utilities;
         use Bio::AlignIO;

         my $in = Bio::AlignIO->new(-file   => 't/data/t7.aln',
                                   -format => 'clustalw');
         my $aln = $in->next_aln;
         # get a population, each sequence is an individual and
         # for the default case, every site which is not monomorphic
         # is a 'marker'.  Each individual will have a 'genotype' for the
         # site which will be the specific base in the alignment at that
         # site

         my $pop = Bio::PopGen::Utilities->aln_to_population(-alignment => $aln);

DESCRIPTION

       This object is intended to provide implementations some standard population genetics
       statistics about alleles in populations.

       This module was previously named Bio::Tree::Statistics.

       This object is a place to accumulate routines for calculating various statistics from the
       coalescent simulation, marker/allele, or from aligned sequence data given that you can
       calculate alleles, number of segregating sites.

       Currently implemented:
        Fu and Li's D    (fu_and_li_D)
        Fu and Li's D*   (fu_and_li_D_star)
        Fu and Li's F    (fu_and_li_F)
        Fu and Li's F*   (fu_and_li_F_star)
        Tajima's D       (tajima_D)
        Watterson's theta (theta)
        pi               (pi) - number of pairwise differences
        composite_LD     (composite_LD)
        McDonald-Kreitman (mcdonald_kreitman or MK)

       Count based methods also exist in case you have already calculated the key statistics (seg
       sites, num individuals, etc) and just want to compute the statistic.

       In all cases where a the method expects an arrayref of Bio::PopGen::IndividualI objects
       and Bio::PopGen::PopulationI object will also work.

   REFERENCES
       Fu Y.X and Li W.H. (1993) "Statistical Tests of Neutrality of Mutations." Genetics
       133:693-709.

       Fu Y.X. (1996) "New Statistical Tests of Neutrality for DNA samples from a Population."
       Genetics 143:557-570.

       McDonald J, Kreitman M.

       Tajima F. (1989) "Statistical method for testing the neutral mutation hypothesis by DNA
       polymorphism." Genetics 123:585-595.

   CITING THIS WORK
       Please see this reference for use of this implementation.

       Stajich JE and Hahn MW "Disentangling the Effects of Demography and Selection in Human
       History." (2005) Mol Biol Evol 22(1):63-73.

       If you use these Bio::PopGen modules please cite the Bioperl publication (see FAQ) and the
       above reference.

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, Matthew Hahn

       Email jason-at-bioperl-dot-org Email matthew-dot-hahn-at-duke-dot-edu

       McDonald-Kreitman implementation based on work by Alisha Holloway at UC Davis.

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::PopGen::Statistics->new();
        Function: Builds a new Bio::PopGen::Statistics object
        Returns : an instance of Bio::PopGen::Statistics
        Args    : none

   fu_and_li_D
        Title   : fu_and_li_D
        Usage   : my $D = $statistics->fu_and_li_D(\@ingroup,\@outgroup);
                   OR
                  my $D = $statistics->fu_and_li_D(\@ingroup,$extmutations);
        Function: Fu and Li D statistic for a list of individuals
                  given an outgroup and the number of external mutations
                  (either provided or calculated from list of outgroup individuals)
        Returns : decimal
        Args    : $individuals - array reference which contains ingroup individuals
                  (L<Bio::PopGen::Individual> or derived classes)
                  $extmutations - number of external mutations OR
                  arrayref of outgroup individuals

   fu_and_li_D_counts
        Title   : fu_li_D_counts
        Usage   : my $D = $statistics->fu_and_li_D_counts($samps,$sites,
                                                          $external);
        Function: Fu and Li D statistic for the raw counts of the number
                  of samples, sites, external and internal mutations
        Returns : decimal number
        Args    : number of samples (N)
                  number of segregating sites (n)
                  number of external mutations (n_e)

   fu_and_li_D_star
        Title   : fu_and_li_D_star
        Usage   : my $D = $statistics->fu_an_li_D_star(\@individuals);
        Function: Fu and Li's D* statistic for a set of samples
                   Without an outgroup
        Returns : decimal number
        Args    : array ref of L<Bio::PopGen::IndividualI> objects
                  OR
                  L<Bio::PopGen::PopulationI> object

   fu_and_li_D_star_counts
        Title   : fu_li_D_star_counts
        Usage   : my $D = $statistics->fu_and_li_D_star_counts($samps,$sites,
                                                               $singletons);

        Function: Fu and Li D statistic for the raw counts of the number
                  of samples, sites, external and internal mutations
        Returns : decimal number
        Args    : number of samples (N)
                  number of segregating sites (n)
                  singletons (n_s)

   fu_and_li_F
        Title   : fu_and_li_F
        Usage   : my $F = Bio::PopGen::Statistics->fu_and_li_F(\@ingroup,$ext_muts);
        Function: Calculate Fu and Li's F on an ingroup with either the set of
                  outgroup individuals, or the number of external mutations
        Returns : decimal number
        Args    : array ref of L<Bio::PopGen::IndividualI> objects for the ingroup
                  OR a L<Bio::PopGen::PopulationI> object
                  number of external mutations OR list of individuals for the outgroup

   fu_and_li_F_counts
        Title   : fu_li_F_counts
        Usage   : my $F = $statistics->fu_and_li_F_counts($samps,$pi,
                                                          $sites,
                                                          $external);
        Function: Fu and Li F statistic for the raw counts of the number
                  of samples, sites, external and internal mutations
        Returns : decimal number
        Args    : number of samples (N)
                  average pairwise differences (pi)
                  number of segregating sites (n)
                  external mutations (n_e)

   fu_and_li_F_star
        Title   : fu_and_li_F_star
        Usage   : my $F = Bio::PopGen::Statistics->fu_and_li_F_star(\@ingroup);
        Function: Calculate Fu and Li's F* on an ingroup without an outgroup
                  It uses count of singleton alleles instead
        Returns : decimal number
        Args    : array ref of L<Bio::PopGen::IndividualI> objects for the ingroup
                  OR
                  L<Bio::PopGen::PopulationI> object

   fu_and_li_F_star_counts
        Title   : fu_li_F_star_counts
        Usage   : my $F = $statistics->fu_and_li_F_star_counts($samps,
                                                          $pi,$sites,
                                                          $singletons);
        Function: Fu and Li F statistic for the raw counts of the number
                  of samples, sites, external and internal mutations
        Returns : decimal number
        Args    : number of samples (N)
                  average pairwise differences (pi)
                  number of segregating sites (n)
                  singleton  mutations (n_s)

   tajima_D
        Title   : tajima_D
        Usage   : my $D = Bio::PopGen::Statistics->tajima_D(\@samples);
        Function: Calculate Tajima's D on a set of samples
        Returns : decimal number
        Args    : array ref of L<Bio::PopGen::IndividualI> objects
                  OR
                  L<Bio::PopGen::PopulationI> object

   tajima_D_counts
        Title   : tajima_D_counts
        Usage   : my $D = $statistics->tajima_D_counts($samps,$sites,$pi);
        Function: Tajima's D statistic for the raw counts of the number
                  of samples, sites, and avg pairwise distances (pi)
        Returns : decimal number
        Args    : number of samples (N)
                  number of segregating sites (n)
                  average pairwise differences (pi)

   pi
        Title   : pi
        Usage   : my $pi = Bio::PopGen::Statistics->pi(\@inds)
        Function: Calculate pi (average number of pairwise differences) given
                  a list of individuals which have the same number of markers
                  (also called sites) as available from the get_Genotypes()
                  call in L<Bio::PopGen::IndividualI>
        Returns : decimal number
        Args    : Arg1= array ref of L<Bio::PopGen::IndividualI> objects
                    which have markers/mutations.  We expect all individuals to
                    have a marker - we will deal with missing data as a special case.
                  OR
                  Arg1= L<Bio::PopGen::PopulationI> object.  In the event that
                        only allele frequency data is available, storing it in
                        Population object will make this available.
                  num sites [optional], an optional second argument (integer)
                    which is the number of sites, then pi returned is pi/site.

   theta
        Title   : theta
        Usage   : my $theta = Bio::PopGen::Statistics->theta($sampsize,$segsites);
        Function: Calculates Watterson's theta from the sample size
                  and the number of segregating sites.
                  Providing the third parameter, total number of sites will
                  return theta per site.
                  This is also known as K-hat = K / a_n
        Returns : decimal number
        Args    : sample size (integer),
                  num segregating sites (integer)
                  total sites (integer) [optional] (to calculate theta per site)
                  OR
                  provide an arrayref of the L<Bio::PopGen::IndividualI> objects
                  total sites (integer) [optional] (to calculate theta per site)
                  OR
                  provide an L<Bio::PopGen::PopulationI> object
                  total sites (integer)[optional]

   singleton_count
        Title   : singleton_count
        Usage   : my ($singletons) = Bio::PopGen::Statistics->singleton_count(\@inds)
        Function: Calculate the number of mutations/alleles which only occur once in
                  a list of individuals for all sites/markers
        Returns : (integer) number of alleles which only occur once (integer)
        Args    : arrayref of L<Bio::PopGen::IndividualI> objects
                  OR
                  L<Bio::PopGen::PopulationI> object

   segregating_sites_count
        Title   : segregating_sites_count
        Usage   : my $segsites = Bio::PopGen::Statistics->segregating_sites_count
        Function: Gets the number of segregating sites (number of polymorphic sites)
        Returns : (integer) number of segregating sites
        Args    : arrayref of L<Bio::PopGen::IndividualI> objects
                  OR
                  L<Bio::PopGen::PopulationI> object

   heterozygosity
        Title   : heterozygosity
        Usage   : my $het = Bio::PopGen::Statistics->heterozygosity($sampsize,$freq1);
        Function: Calculate the heterozgosity for a sample set for a set of alleles
        Returns : decimal number
        Args    : sample size (integer)
                  frequency of one allele (fraction - must be less than 1)
                  [optional] frequency of another allele - this is only needed
                             in a non-binary allele system

       Note     : p^2 + 2pq + q^2

   derived_mutations
        Title   : derived_mutations
        Usage   : my $ext = Bio::PopGen::Statistics->derived_mutations($ingroup,$outgroup);
        Function: Calculate the number of alleles or (mutations) which are ancestral
                  and the number which are derived (occurred only on the tips)
        Returns : array of 2 items - number of external and internal derived
                  mutation
        Args    : ingroup - L<Bio::PopGen::IndividualI>s arrayref OR
                            L<Bio::PopGen::PopulationI>
                  outgroup- L<Bio::PopGen::IndividualI>s arrayref OR
                            L<Bio::PopGen::PopulationI> OR
                            a single L<Bio::PopGen::IndividualI>

   composite_LD
        Title   : composite_LD
        Usage   : %matrix = Bio::PopGen::Statistics->composite_LD($population);
        Function: Calculate the Linkage Disequilibrium
                  This is for calculating LD for unphased data.
                  Other methods will be appropriate for phased haplotype data.

        Returns : Hash of Hashes - first key is site 1,second key is site 2
                  and value is LD for those two sites.
                  my $LDarrayref = $matrix{$site1}->{$site2};
                  my ($ldval, $chisquared) = @$LDarrayref;
        Args    : L<Bio::PopGen::PopulationI> or arrayref of
                  L<Bio::PopGen::IndividualI>s
        Reference: Weir B.S. (1996) "Genetic Data Analysis II",
                             Sinauer, Sunderlanm MA.

   mcdonald_kreitman
        Title   : mcdonald_kreitman
        Usage   : $Fstat = mcdonald_kreitman($ingroup, $outgroup);
        Function: Calculates McDonald-Kreitman statistic based on a set of ingroup
                  individuals and an outgroup by computing the number of
                  differences at synonymous and non-synonymous sites
                  for intraspecific comparisons and with the outgroup
        Returns : 2x2 table, followed by a hash reference indicating any
                  warning messages about the status of the alleles or codons
        Args    : -ingroup    => L<Bio::PopGen::Population> object or
                                 arrayref of L<Bio::PopGen::Individual>s
                  -outgroup   => L<Bio::PopGen::Population> object or
                                 arrayef of L<Bio::PopGen::Individual>s
                  -polarized  => Boolean, to indicate if this should be
                                 a polarized test. Must provide two individuals
                                 as outgroups.

   mcdonald_kreitman_counts
        Title   : mcdonald_kreitman_counts
        Usage   : my $MK = $statistics->mcdonald_kreitman_counts(

                    N_poly -> integer of count of non-syn polymorphism
                    N_fix  -> integer of count of non-syn fixed substitutions
                    S_poly -> integer of count of syn polymorphism
                    S_fix  -> integer of count of syn fixed substitutions
                                                                 );
        Function:
        Returns : decimal number
        Args    :