Bio/PopGen/PopulationI.pm

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