/ 
bioperl-1.5.2_100
/ Bio::PopGen::Statistics

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 = new Bio::PopGen::Simulation::Coalescent( -sample_size => 12);

my $tree = $sim->next_tree;

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

my $stats = new Bio::PopGen::Statistics();
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 = new Bio::PopGen::IO(-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 = new Bio::AlignIO(-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)

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.

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

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:

http://bugzilla.open-bio.org/

AUTHOR - Jason Stajich, Matthew Hahn

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

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 = new Bio::PopGen::Statistics();
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,$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.