Bio/PopGen/PopulationI.pm

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