.\" Automatically generated by Pod::Man 4.09 (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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::PopGen::Statistics 3pm"
.TH Bio::PopGen::Statistics 3pm "2018-10-27" "perl v5.26.2" "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::PopGen::Statistics \- Population Genetics statistical tests
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  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 => \*(Aqprettybase\*(Aq,
\&                                   \-file   => \*(Aqt/data/popstats.prettybase\*(Aq);
\&  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   => \*(Aqt/data/t7.aln\*(Aq,
\&                            \-format => \*(Aqclustalw\*(Aq);
\&  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 \*(Aqmarker\*(Aq.  Each individual will have a \*(Aqgenotype\*(Aq 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object is intended to provide implementations some standard
population genetics statistics about alleles in populations.
.PP
This module was previously named Bio::Tree::Statistics.
.PP
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.
.PP
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 \s-1MK\s0)
.PP
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.
.PP
In all cases where a the method expects an arrayref of
Bio::PopGen::IndividualI objects and Bio::PopGen::PopulationI
object will also work.
.SS "\s-1REFERENCES\s0"
.IX Subsection "REFERENCES"
Fu Y.X and Li W.H. (1993) \*(L"Statistical Tests of Neutrality of
Mutations.\*(R" Genetics 133:693\-709.
.PP
Fu Y.X. (1996) \*(L"New Statistical Tests of Neutrality for \s-1DNA\s0 samples
from a Population.\*(R" Genetics 143:557\-570.
.PP
McDonald J, Kreitman M.
.PP
Tajima F. (1989) \*(L"Statistical method for testing the neutral mutation
hypothesis by \s-1DNA\s0 polymorphism.\*(R" Genetics 123:585\-595.
.SS "\s-1CITING THIS WORK\s0"
.IX Subsection "CITING THIS WORK"
Please see this reference for use of this implementation.
.PP
Stajich \s-1JE\s0 and Hahn \s-1MW\s0 \*(L"Disentangling the Effects of Demography and Selection in Human History.\*(R" (2005) Mol Biol Evol 22(1):63\-73.
.PP
If you use these Bio::PopGen modules please cite the Bioperl
publication (see \s-1FAQ\s0) and the above reference.
.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, Matthew Hahn"
.IX Header "AUTHOR - Jason Stajich, Matthew Hahn"
Email jason-at-bioperl-dot-org
Email matthew-dot-hahn-at-duke-dot-edu
.PP
McDonald-Kreitman implementation based on work by Alisha Holloway at
\&\s-1UC\s0 Davis.
.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::PopGen::Statistics\->new();
\& Function: Builds a new Bio::PopGen::Statistics object 
\& Returns : an instance of Bio::PopGen::Statistics
\& Args    : none
.Ve
.SS "fu_and_li_D"
.IX Subsection "fu_and_li_D"
.Vb 12
\& Title   : fu_and_li_D
\& Usage   : my $D = $statistics\->fu_and_li_D(\e@ingroup,\e@outgroup);
\&            OR
\&           my $D = $statistics\->fu_and_li_D(\e@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
.Ve
.SS "fu_and_li_D_counts"
.IX Subsection "fu_and_li_D_counts"
.Vb 9
\& 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)
.Ve
.SS "fu_and_li_D_star"
.IX Subsection "fu_and_li_D_star"
.Vb 8
\& Title   : fu_and_li_D_star
\& Usage   : my $D = $statistics\->fu_an_li_D_star(\e@individuals);
\& Function: Fu and Li\*(Aqs 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
.Ve
.SS "fu_and_li_D_star_counts"
.IX Subsection "fu_and_li_D_star_counts"
.Vb 3
\& 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)
.Ve
.SS "fu_and_li_F"
.IX Subsection "fu_and_li_F"
.Vb 8
\& Title   : fu_and_li_F
\& Usage   : my $F = Bio::PopGen::Statistics\->fu_and_li_F(\e@ingroup,$ext_muts);
\& Function: Calculate Fu and Li\*(Aqs 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
.Ve
.SS "fu_and_li_F_counts"
.IX Subsection "fu_and_li_F_counts"
.Vb 11
\& 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)
.Ve
.SS "fu_and_li_F_star"
.IX Subsection "fu_and_li_F_star"
.Vb 8
\& Title   : fu_and_li_F_star
\& Usage   : my $F = Bio::PopGen::Statistics\->fu_and_li_F_star(\e@ingroup);
\& Function: Calculate Fu and Li\*(Aqs 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
.Ve
.SS "fu_and_li_F_star_counts"
.IX Subsection "fu_and_li_F_star_counts"
.Vb 11
\& 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)
.Ve
.SS "tajima_D"
.IX Subsection "tajima_D"
.Vb 7
\& Title   : tajima_D
\& Usage   : my $D = Bio::PopGen::Statistics\->tajima_D(\e@samples);
\& Function: Calculate Tajima\*(Aqs D on a set of samples 
\& Returns : decimal number
\& Args    : array ref of L<Bio::PopGen::IndividualI> objects
\&           OR 
\&           L<Bio::PopGen::PopulationI> object
.Ve
.SS "tajima_D_counts"
.IX Subsection "tajima_D_counts"
.Vb 8
\& Title   : tajima_D_counts
\& Usage   : my $D = $statistics\->tajima_D_counts($samps,$sites,$pi);
\& Function: Tajima\*(Aqs 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)
.Ve
.SS "pi"
.IX Subsection "pi"
.Vb 10
\& Title   : pi
\& Usage   : my $pi = Bio::PopGen::Statistics\->pi(\e@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.
.Ve
.SS "theta"
.IX Subsection "theta"
.Vb 10
\& Title   : theta
\& Usage   : my $theta = Bio::PopGen::Statistics\->theta($sampsize,$segsites);
\& Function: Calculates Watterson\*(Aqs 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]
.Ve
.SS "singleton_count"
.IX Subsection "singleton_count"
.Vb 8
\& Title   : singleton_count
\& Usage   : my ($singletons) = Bio::PopGen::Statistics\->singleton_count(\e@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
.Ve
.SS "segregating_sites_count"
.IX Subsection "segregating_sites_count"
.Vb 7
\& 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
.Ve
.SS "heterozygosity"
.IX Subsection "heterozygosity"
.Vb 8
\& 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
.Ve
.PP
Note     : p^2 + 2pq + q^2
.SS "derived_mutations"
.IX Subsection "derived_mutations"
.Vb 11
\& 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>
.Ve
.SS "composite_LD"
.IX Subsection "composite_LD"
.Vb 5
\& 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.
.Ve
.SS "mcdonald_kreitman"
.IX Subsection "mcdonald_kreitman"
.Vb 10
\& 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.
.Ve
.SS "mcdonald_kreitman_counts"
.IX Subsection "mcdonald_kreitman_counts"
.Vb 2
\& 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    :
.Ve