branch-1-6/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 I<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
 153 =head2 annotation
 154
 155  Title   : annotation
 156  Usage   : my $annotation_collection = $pop->annotation;
 157  Function: Get/set a Bio::AnnotationCollectionI for this population
 158  Returns : Bio::AnnotationCollectionI object
 159  Args    : [optional set] Bio::AnnotationCollectionI object
 160
 161
 162 =cut
 163
 164 sub annotation{
 165    my ($self) = @_;
 166    $self->throw_not_implemented();
 167 }
 168
 169 =head2 get_Individuals
 170
 171  Title   : get_Individuals
 172  Usage   : my @inds = $pop->get_Individuals();
 173  Function: Return the individuals, alternatively restrict by a criteria
 174  Returns : Array of L<Bio::PopGen::IndividualI> objects
 175  Args    : none if want all the individuals OR,
 176            -unique_id => To get an individual with a specific id
 177            -marker    => To only get individuals which have a genotype specific
 178                         for a specific marker name
 179
 180
 181 =cut
 182
 183
 184 sub get_Individuals{
 185     shift->throw_not_implemented();
 186 }
 187
 188 =head2 get_Genotypes
 189
 190  Title   : get_Genotypes
 191  Usage   : my @genotypes = $pop->get_Genotypes(-marker => $name)
 192  Function: Get the genotypes for all the individuals for a specific
 193            marker name
 194  Returns : Array of L<Bio::PopGen::GenotypeI> objects
 195  Args    : -marker => name of the marker
 196
 197
 198 =cut
 199
 200 sub get_Genotypes{
 201     shift->throw_not_implemented;
 202 }
 203
 204 =head2 get_Marker
 205
 206  Title   : get_Marker
 207  Usage   : my $marker = $population->get_Marker($name)
 208  Function: Get a Bio::PopGen::Marker object based on this population
 209  Returns : L<Bio::PopGen::MarkerI> object
 210  Args    : name of the marker
 211
 212
 213 =cut
 214
 215 sub get_Marker{
 216     shift->throw_not_implemented();
 217 }
 218
 219 =head2 get_marker_names
 220
 221  Title   : get_marker_names
 222  Usage   : my @names = $pop->get_marker_names;
 223  Function: Get the names of the markers
 224  Returns : Array of strings
 225  Args    : none
 226
 227
 228 =cut
 229
 230 sub get_marker_names{
 231     my ($self) = @_;
 232     $self->throw_not_implemented();
 233 }
 234
 235 =head2 get_Markers
 236
 237  Title   : get_Markers
 238  Usage   : my @markers = $pop->get_Markers();
 239  Function: Will retrieve a list of instantiated MarkerI objects
 240            for a population.  This is a convience method combining
 241            get_marker_names with get_Marker
 242  Returns : List of array of Bio::PopGen::MarkerI objects
 243  Args    : none
 244
 245
 246 =cut
 247
 248 sub get_Markers{
 249     my ($self) = shift;
 250     return map { $self->get_Marker($_) } $self->get_marker_names();
 251 }
 252
 253
 254 =head2 get_number_individuals
 255
 256  Title   : get_number_individuals
 257  Usage   : my $count = $pop->get_number_individuals;
 258  Function: Get the count of the number of individuals
 259  Returns : integer >= 0
 260  Args    : [optional] marker name, will return a count of the number
 261            of individuals which have this marker
 262
 263
 264 =cut
 265
 266 sub get_number_individuals{
 267    my ($self) = @_;
 268    $self->throw_not_implemented();
 269 }
 270
 271 1;