Summary

Bio::PopGen::IO - Input individual,marker,allele information

Package variables

Included modules

Inherit

Bio::Root::IO

Synopsis

  use Bio::PopGen::IO;
  my $io = new Bio::PopGen::IO(-format => 'csv',
                               -file   => 'data.csv');

  # Some IO might support reading in a population at a time

  my @population;
  while( my $ind = $io->next_individual ) {
      push @population, $ind;
  }

Description

This is a generic interface to reading in population genetic data (of
which there really isn't too many standard formats). This implementation
makes it easy to provide your own parser for the data. You need to
only implement one function next_individual. You can also implement
next_population if your data has explicit information about population
memberhsip for the indidviduals.

Methods

Methods description

 Title   : new
 Usage   : my $obj = new Bio::PopGen::IO();
 Function: Builds a new Bio::PopGen::IO object 
 Returns : an instance of Bio::PopGen::IO
 Args    :

 Title   : next_individual
 Usage   : my $ind = $popgenio->next_individual;
 Function: Retrieve the next individual from a dataset
 Returns : Bio::PopGen::IndividualI object
 Args    : none

 Title   : next_population
 Usage   : my $pop = $popgenio->next_population;
 Function: Retrieve the next population from a dataset
 Returns : Bio::PopGen::PopulationI object
 Args    : none
 Note    : Many implementation will not implement this

 Title   : write_individual
 Usage   : $popgenio->write_individual($ind);
 Function: Write an individual out in the implementation format
 Returns : none
 Args    : Bio::PopGen::PopulationI object(s)

 Title   : write_population
 Usage   : $popgenio->write_population($pop);
 Function: Write a population out in the implementation format
 Returns : none
 Args    : Bio::PopGen::PopulationI object(s)
 Note    : Many implementation will not implement this

 Title   : newFh
 Usage   : $fh = Bio::SeqIO->newFh(-file=>$filename,-format=>'Format')
 Function: does a new() followed by an fh()
 Example : $fh = Bio::SeqIO->newFh(-file=>$filename,-format=>'Format')
           $sequence = <$fh>;   # read a sequence object
           print $fh $sequence; # write a sequence object
 Returns : filehandle tied to the Bio::SeqIO::Fh class
 Args    :

 Title   : fh
 Usage   : $obj->fh
 Function:
 Example : $fh = $obj->fh;      # make a tied filehandle
           $sequence = <$fh>;   # read a sequence object
           print $fh $sequence; # write a sequence object
 Returns : filehandle tied to Bio::SeqIO class
 Args    : none

 Title   : _load_format_module
 Usage   : *INTERNAL SearchIO stuff*
 Function: Loads up (like use) a module at run time on demand
 Example : 
 Returns : 
 Args    :

 Title   : _guess_format
 Usage   : $obj->_guess_format($filename)
 Function:
 Example :
 Returns : guessed format of filename (lower case)
 Args    :

Methods code

sub new {

  my($class,@args) = @_;

  if( $class =~ /Bio::PopGen::IO::(\S+)/ ) {
    my ($self) = $class->SUPER::new(@args);	
    $self->_initialize(@args);
    return $self;
  } else { 
    my %param = @args;
    @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
    my $format = $param{'-format'} ||
      $class->_guess_format( $param{'-file'} || $ARGV[0] ) || 'csv';

    # normalize capitalization to lower case
    $format = "\L$format";
    
    return undef unless( $class->_load_format_module($format) );
    return "Bio::PopGen::IO::${format}"->new(@args);
  }

}

sub _initialize {

    my($self, @args) = @_;
#    my ($indfact, $popfact) = $self->_rearrange([qw(INDIVIDUAL_FACTORY
#						    POPULATION_FACTORY)],
#						@args);
#    $indfact = Bio::PopGen::IndividualBuilder->new() unless $indfact;
#    $indfact = Bio::PopGen::PopulationBuilder->new() unless $indfact;

    # initialize the IO part
    $self->_initialize_io(@args);
    return 1;

}

sub next_individual {

    my ($self) = @_;
    $self->throw_not_implemented();

}

sub next_population {

    my ($self) = @_;
    $self->throw_not_implemented();

}

sub write_individual {

    my ($self) = @_;
    $self->throw_not_implemented();

}

sub write_population {

    my ($self) = @_;
    $self->throw_not_implemented();

}

sub newFh {

  my $class = shift;
  return unless my $self = $class->new(@_);
  return $self->fh;

}

sub fh {

  my $self = shift;
  my $class = ref($self) || $self;
  my $s = Symbol::gensym;
  tie $$s,$class,$self;
  return $s;

}

sub _load_format_module {

  my ($self,$format) = @_;
  my $module = "Bio::PopGen::IO::" . $format;
  my $ok;
  
  eval {
      $ok = $self->_load_module($module);
  };
  if ( $@ ) {
      print STDERR <<END
$self: $format cannot be found
Exception $@
For more information about the Bio::PopGen::IO system please see the 
Bio::PopGen::IO docs.  This includes ways of checking for formats at 
compile time, not run time
END
  ;
  }
  return $ok;

}

sub _guess_format {

   my $class = shift;
   return unless $_ = shift;
   return 'csv'   if (/csv/i or /\.dat\w$/i);

}

sub close {

     my $self = shift;
    $self->SUPER::close(@_);

}

sub DESTROY {

    my $self = shift;
    $self->close();

}

sub TIEHANDLE {

  my $class = shift;
  return bless {processor => shift}, $class;

}

sub READLINE {

  my $self = shift;
  return $self->{'processor'}->next_result() unless wantarray;
  my (@list, $obj);
  push @list, $obj while $obj = $self->{'processor'}->next_result();
  return @list;

}

sub PRINT {

  my $self = shift;
  $self->{'processor'}->write_result(@_);

}

General documentation

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/MailList.shtml  - About the mailing lists

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

  http://bugzilla.bioperl.org/

Email jason-at-bioperl.org
Describe contact details here

Additional contributors names and emails here

The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _