Bio/PopGen/PopulationI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::PopGen::PopulationI
   4 #
   5 # Cared for by Jason Stajich <jason@bioperl.org>
   6 #
   7 # Copyright Jason Stajich
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::PopGen::PopulationI - Interface for Populations
  16
  17 =head1 SYNOPSIS
  18
  19   # Get Bio::PopGen::PopulationI object somehow, like
  20   # from Bio::Population::Population
  21
  22   print "name is ", $population->name(), "\n";
  23   print "source is ", $population->source(), "\n";
  24   print "description is ", $population->description(), "\n";
  25
  26   print "For marker $markername:\n";
  27   foreach my $genotype ( $population->get_Genotypes(-marker => $markername) ) {
  28       print "Individual ", $genotype->individual_id, " genotype alleles are ",
  29       join(',', $genotype->get_Alleles()), "\n";
  30   }
  31   # get a marker with allele frequencies calculated from the population
  32   my $marker = $population->get_Marker($markername);
  33   my %af = $marker->get_Allele_Frequencies;
  34   foreach my $allele ( keys %af ) {
  35       print "$allele $af{$allele}\n";
  36   }
  37
  38 =head1 DESCRIPTION
  39
  40 This interface describes the basics of a population.  One can use this
  41 object to get the genotypes of specific individuals, only those
  42 individuals which have a certain marker, or create a marker with
  43 allele frequency information.
  44
  45 =head1 FEEDBACK
  46
  47 =head2 Mailing Lists
  48
  49 User feedback is an integral part of the evolution of this and other
  50 Bioperl modules. Send your comments and suggestions preferably to the
  51 Bioperl mailing list.  Your participation is much appreciated.
  52
  53   bioperl-l@bioperl.org                  - General discussion
  54   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  55
  56 =head2 Reporting Bugs
  57
  58 Report bugs to the Bioperl bug tracking system to help us keep track
  59 of the bugs and their resolution. Bug reports can be submitted via
  60 email or the web:
  61
  62   http://bugzilla.open-bio.org/
  63
  64 =head1 AUTHOR - Jason Stajich
  65
  66 Email jason-at-bioperl.org
  67
  68 =head1 CONTRIBUTORS
  69
  70 Matthew Hahn, matthew.hahn-at-duke.edu
  71
  72 =head1 APPENDIX
  73
  74 The rest of the documentation details each of the object methods.
  75 Internal methods are usually preceded with a _
  76
  77 =cut
  78
  79
  80 # Let the code begin...
  81
  82
  83 package Bio::PopGen::PopulationI;
  84 use strict;
  85 use Carp;
  86
  87 use base qw(Bio::Root::RootI);
  88
  89 =head2 name
  90
  91  Title   : name
  92  Usage   : my $name = $pop->name
  93  Function: Get the population name
  94  Returns : string representing population name
  95  Args    : [optional] string representing population name
  96
  97
  98 =cut
  99
 100 sub name{
 101    my ($self,@args) = @_;
 102    $self->throw_not_implemented();
 103 }
 104
 105
 106
 107 =head2 description
 108
 109  Title   : description
 110  Usage   : my $description = $pop->description
 111  Function: Get the population description
 112  Returns : string representing population description
 113  Args    : [optional] string representing population description
 114
 115
 116 =cut
 117
 118 sub description{
 119    my ($self,@args) = @_;
 120    $self->throw_not_implemented();
 121 }
 122
 123 =head2 source
 124
 125  Title   : source
 126  Usage   : my $source = $pop->source
 127  Function: Get the population source
 128  Returns : string representing population source
 129  Args    : [optional] string representing population source
 130
 131
 132 =cut
 133
 134 sub source{
 135    my ($self,@args) = @_;
 136    $self->throw_not_implemented();
 137 }
 138
 139 =head2 get_Individuals
 140
 141  Title   : get_Individuals
 142  Usage   : my @inds = $pop->get_Individuals();
 143  Function: Return the individuals, alternatively restrict by a criteria
 144  Returns : Array of L<Bio::PopGen::IndividualI> objects
 145  Args    : none if want all the individuals OR,
 146            -unique_id => To get an individual with a specific id
 147            -marker    => To only get individuals which have a genotype specific
 148                         for a specific marker name
 149
 150
 151 =cut
 152
 153 sub get_Individuals{
 154     shift->throw_not_implemented();
 155 }
 156
 157 =head2 get_Genotypes
 158
 159  Title   : get_Genotypes
 160  Usage   : my @genotypes = $pop->get_Genotypes(-marker => $name)
 161  Function: Get the genotypes for all the individuals for a specific
 162            marker name
 163  Returns : Array of L<Bio::PopGen::GenotypeI> objects
 164  Args    : -marker => name of the marker
 165
 166
 167 =cut
 168
 169 sub get_Genotypes{
 170     shift->throw_not_implemented;
 171 }
 172
 173 =head2 get_Marker
 174
 175  Title   : get_Marker
 176  Usage   : my $marker = $population->get_Marker($name)
 177  Function: Get a Bio::PopGen::Marker object based on this population
 178  Returns : L<Bio::PopGen::MarkerI> object
 179  Args    : name of the marker
 180
 181
 182 =cut
 183
 184 sub get_Marker{
 185     shift->throw_not_implemented();
 186 }
 187
 188 =head2 get_marker_names
 189
 190  Title   : get_marker_names
 191  Usage   : my @names = $pop->get_marker_names;
 192  Function: Get the names of the markers
 193  Returns : Array of strings
 194  Args    : none
 195
 196
 197 =cut
 198
 199 sub get_marker_names{
 200     my ($self) = @_;
 201     $self->throw_not_implemented();
 202 }
 203
 204 =head2 get_Markers
 205
 206  Title   : get_Markers
 207  Usage   : my @markers = $pop->get_Markers();
 208  Function: Will retrieve a list of instantiated MarkerI objects
 209            for a population.  This is a convience method combining
 210            get_marker_names with get_Marker
 211  Returns : List of array of Bio::PopGen::MarkerI objects
 212  Args    : none
 213
 214
 215 =cut
 216
 217 sub get_Markers{
 218     my ($self) = shift;
 219     return map { $self->get_Marker($_) } $self->get_marker_names();
 220 }
 221
 222
 223 =head2 get_number_individuals
 224
 225  Title   : get_number_individuals
 226  Usage   : my $count = $pop->get_number_individuals;
 227  Function: Get the count of the number of individuals
 228  Returns : integer >= 0
 229  Args    : [optional] marker name, will return a count of the number
 230            of individuals which have this marker
 231
 232
 233 =cut
 234
 235 sub get_number_individuals{
 236    my ($self) = @_;
 237    $self->throw_not_implemented();
 238 }
 239
 240 1;