NAME

       Bio::PopGen::Population - A population of individuals

SYNOPSIS

         use Bio::PopGen::Population;
         use Bio::PopGen::Individual;
         my $population = Bio::PopGen::Population->new();
         my $ind = Bio::PopGen::Individual->new(-unique_id => 'id');
         $population->add_Individual($ind);

         for my $ind ( $population->get_Individuals ) {
           # iterate through the individuals
         }

         for my $name ( $population->get_marker_names ) {
           my $marker = $population->get_Marker($name);
         }

         my $num_inds = $population->get_number_individuals;

         my $homozygote_f   = $population->get_Frequency_Homozygotes;
         my $heterozygote_f = $population->get_Frequency_Heterozygotes;

         # make a population haploid by making fake chromosomes through
         # haplotypes -- ala allele 1 is on chrom 1 and allele 2 is on chrom 2
         # the number of individuals created will thus be 2 x number in
         # population
         my $happop = $population->haploid_population;

DESCRIPTION

       This is a collection of individuals.  We'll have ways of generating Bio::PopGen::MarkerI
       objects out so we can calculate allele_frequencies for implementing the various
       statistical tests.

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 email or the web:

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

AUTHOR - Jason Stajich

       Email jason-at-bioperl.org

CONTRIBUTORS

       Matthew Hahn, matthew.hahn-at-duke.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 = Bio::PopGen::Population->new();
        Function: Builds a new Bio::PopGen::Population object
        Returns : an instance of Bio::PopGen::Population
        Args    : -individuals => array ref of individuals (optional)
                  -name        => population name (optional)
                  -source      => a source tag (optional)
                  -description => a short description string of the population (optional)

   name
        Title   : name
        Usage   : my $name = $pop->name
        Function: Get the population name
        Returns : string representing population name
        Args    : [optional] string representing population name

   description
        Title   : description
        Usage   : my $description = $pop->description
        Function: Get the population description
        Returns : string representing population description
        Args    : [optional] string representing population description

   source
        Title   : source
        Usage   : my $source = $pop->source
        Function: Get the population source
        Returns : string representing population source
        Args    : [optional] string representing population source

   annotation
        Title   : annotation
        Usage   : my $annotation_collection = $pop->annotation;
        Function: Get/set a Bio::AnnotationCollectionI for this population
        Returns : Bio::AnnotationCollectionI object
        Args    : [optional set] Bio::AnnotationCollectionI object

   set_Allele_Frequency
        Title   : set_Allele_Frequency
        Usage   : $population->set_Allele_Frequency('marker' => { 'allele1' => 0.1});
        Function: Sets an allele frequency for a Marker for this Population
                  This allows the Population to not have individual individual
                  genotypes but rather a set of overall allele frequencies
        Returns : Count of the number of markers
        Args    : -name      => (string) marker name
                  -allele    => (string) allele name
                  -frequency => (double) allele frequency - must be between 0 and 1
                  OR
                  -frequencies => { 'marker1' => { 'allele1' => 0.01,
                                                   'allele2' => 0.99},
                                    'marker2' => ...
                                   }

   add_Individual
        Title   : add_Individual
        Usage   : $population->add_Individual(@individuals);
        Function: Add individuals to a population
        Returns : count of the current number in the object
        Args    : Array of Individuals

   remove_Individuals
        Title   : remove_Individuals
        Usage   : $population->remove_Individuals(@ids);
        Function: Remove individual(s) to a population
        Returns : count of the current number in the object
        Args    : Array of ids

   get_Individuals
        Title   : get_Individuals
        Usage   : my @inds = $pop->get_Individuals();
        Function: Return the individuals, alternatively restrict by a criteria
        Returns : Array of Bio::PopGen::IndividualI objects
        Args    : none if want all the individuals OR,
                  -unique_id => To get an individual with a specific id
                  -marker    => To only get individuals which have a genotype specific
                               for a specific marker name

   get_Genotypes
        Title   : get_Genotypes
        Usage   : my @genotypes = $pop->get_Genotypes(-marker => $name)
        Function: Get the genotypes for all the individuals for a specific
                  marker name
        Returns : Array of Bio::PopGen::GenotypeI objects
        Args    : -marker => name of the marker

   get_marker_names
        Title   : get_marker_names
        Usage   : my @names = $pop->get_marker_names;
        Function: Get the names of the markers
        Returns : Array of strings
        Args    : [optional] boolean flag to ignore internal cache status

   get_Marker
        Title   : get_Marker
        Usage   : my $marker = $population->get_Marker($name)
        Function: Get a Bio::PopGen::Marker object based on this population
        Returns : Bio::PopGen::MarkerI object
        Args    : name of the marker

   get_number_individuals
        Title   : get_number_individuals
        Usage   : my $count = $pop->get_number_individuals;
        Function: Get the count of the number of individuals
        Returns : integer >= 0
        Args    : none

   set_number_individuals
        Title   : set_number_individuals
           Usage   : $pop->set_number_individuals($num);
        Function: Fixes the number of individuals, call this with
                  0 to unset.
                  Only use this if you know what you are doing,
                  this is only relevant when you are just adding
                  allele frequency data for a population and want to
                  calculate something like theta
        Returns : none
        Args    : individual count, calling it with undef or 0
                   will reset the value to return a number
                   calculated from the number of individuals
                   stored for this population.

   get_Frequency_Homozygotes
        Title   : get_Frequency_Homozygotes
        Usage   : my $freq = $pop->get_Frequency_Homozygotes;
        Function: Calculate the frequency of homozygotes in the population
        Returns : fraction between 0 and 1
        Args    : $markername

   get_Frequency_Heterozygotes
        Title   : get_Frequency_Heterozygotes
        Usage   : my $freq = $pop->get_Frequency_Homozygotes;
        Function: Calculate the frequency of homozygotes in the population
        Returns : fraction between 0 and 1
        Args    : $markername

   haploid_population
        Title   : haploid_population
        Usage   : my $pop = $population->haploid_population;
        Function: Make a new population where all the individuals
                  are haploid - effectively an individual out of each
                  chromosome an individual has.
        Returns : L<Bio::PopGen::PopulationI>
        Args    : None