Bio/Matrix/IO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Matrix::IO
   4 #
   5 # Cared for by Jason Stajich <jason-at-bioperl-dot-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::Matrix::IO - A factory for Matrix parsing
  16
  17 =head1 SYNOPSIS
  18
  19   use Bio::Matrix::IO;
  20   my $parser = Bio::Matrix::IO->new(-format => 'scoring',
  21                                    -file   => 'BLOSUMN50');
  22
  23   my $matrix = $parser->next_matrix;
  24
  25 =head1 DESCRIPTION
  26
  27 This is a general factory framework for writing parsers for Matricies.
  28 This includes parsing output from distance output like PHYLIP's
  29 ProtDist.  Additionally it should be possible to fit parsers for PWM
  30 and PSSMs once their Matrix objects are written.
  31
  32 =head1 FEEDBACK
  33
  34 =head2 Mailing Lists
  35
  36 User feedback is an integral part of the evolution of this and other
  37 Bioperl modules. Send your comments and suggestions preferably to
  38 the Bioperl mailing list.  Your participation is much appreciated.
  39
  40   bioperl-l@bioperl.org                  - General discussion
  41   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  42
  43 =head2 Reporting Bugs
  44
  45 Report bugs to the Bioperl bug tracking system to help us keep track
  46 of the bugs and their resolution. Bug reports can be submitted via
  47 the web:
  48
  49   http://bugzilla.open-bio.org/
  50
  51 =head1 AUTHOR - Jason Stajich
  52
  53 Email jason-at-bioperl-dot-org
  54
  55 =head1 APPENDIX
  56
  57 The rest of the documentation details each of the object methods.
  58 Internal methods are usually preceded with a _
  59
  60 =cut
  61
  62
  63 # Let the code begin...
  64
  65
  66 package Bio::Matrix::IO;
  67 use strict;
  68
  69
  70 use base qw(Bio::Root::IO);
  71
  72 =head2 new
  73
  74  Title   : new
  75  Usage   : my $obj = Bio::Matrix::IO->new();
  76  Function: Builds a new Bio::Matrix::IO object
  77  Returns : an instance of Bio::Matrix::IO
  78  Args    :
  79
  80
  81 =cut
  82
  83 sub new {
  84   my($caller,@args) = @_;
  85   my $class = ref($caller) || $caller;
  86
  87     # or do we want to call SUPER on an object if $caller is an
  88     # object?
  89     if( $class =~ /Bio::Matrix::IO::(\S+)/ ) {
  90         my ($self) = $class->SUPER::new(@args);
  91         $self->_initialize(@args);
  92         return $self;
  93     } else {
  94
  95         my %param = @args;
  96         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
  97         my $format = $param{'-format'} ||
  98             $class->_guess_format( $param{'-file'} || $ARGV[0] ) ||
  99                 'scoring';
 100         $format = "\L$format";  # normalize capitalization to lower case
 101
 102         # normalize capitalization
 103         return unless( $class->_load_format_module($format) );
 104         return "Bio::Matrix::IO::$format"->new(@args);
 105     }
 106 }
 107
 108 =head2 newFh
 109
 110  Title   : newFh
 111  Usage   : $fh = Bio::Matrix::IO->newFh(-file=>$filename,-format=>'Format')
 112  Function: does a new() followed by an fh()
 113  Example : $fh = Bio::Matrix::IO->newFh(-file=>$filename,-format=>'Format')
 114            $matrix = <$fh>;   # read a matrix object
 115            print $fh $matrix; # write a matrix object
 116  Returns : filehandle tied to the Bio::SeqIO::Fh class
 117  Args    :
 118
 119 =cut
 120
 121 sub newFh {
 122   my $class = shift;
 123   return unless my $self = $class->new(@_);
 124   return $self->fh;
 125 }
 126
 127 =head2 fh
 128
 129  Title   : fh
 130  Usage   : $obj->fh
 131  Function: Get a filehandle type access to the matrix parser
 132  Example : $fh = $obj->fh;      # make a tied filehandle
 133            $matrix = <$fh>;     # read a matrix object
 134            print $fh $matrix;   # write a matrix object
 135  Returns : filehandle tied to Bio::Matrix::IO class
 136  Args    : none
 137
 138 =cut
 139
 140
 141 sub fh {
 142   my $self = shift;
 143   my $class = ref($self) || $self;
 144   my $s = Symbol::gensym;
 145   tie $$s,$class,$self;
 146   return $s;
 147 }
 148
 149
 150 =head2 next_matrix
 151
 152  Title   : next_matrix
 153  Usage   : my $matrix = $matixio->next_matrix;
 154  Function: Parse the next matrix from the data stream
 155  Returns : L<Bio::Matrix::MatrixI> type object or undef when finished
 156  Args    : none
 157
 158
 159 =cut
 160
 161 sub next_matrix{
 162    my ($self) = @_;
 163    $self->throw_not_implemented();
 164 }
 165
 166 =head2 write_matrix
 167
 168  Title   : write_matrix
 169  Usage   : $io->write_matrix($matrix)
 170  Function: Writes a matrix out to the data stream
 171  Returns : none
 172  Args    : Array of Bio::Matrix::MatrixI object
 173           - note that not all matricies can be converted to
 174             each format, beware with mixing matrix types and output formats
 175
 176 =cut
 177
 178 sub write_matrix{
 179    my ($self) = @_;
 180    $self->throw_not_implemented();
 181 }
 182
 183 sub _initialize {
 184     my ($self,@args) = @_;
 185     $self->_initialize_io(@args);
 186 }
 187
 188 =head2 _load_format_module
 189
 190  Title   : _load_format_module
 191  Usage   : *INTERNAL Matrix::IO stuff*
 192  Function: Loads up (like use) a module at run time on demand
 193
 194 =cut
 195
 196 sub _load_format_module {
 197   my ($self,$format) = @_;
 198   my $module = "Bio::Matrix::IO::" . $format;
 199   my $ok;
 200
 201   eval {
 202       $ok = $self->_load_module($module);
 203   };
 204   if ( $@ ) {
 205     print STDERR <<END;
 206 $self: $format cannot be found
 207 Exception $@
 208 For more information about the Matrix::IO system please see the
 209 Matrix::IO docs.  This includes ways of checking for formats at
 210 compile time, not run time
 211 END
 212   ;
 213   }
 214   return $ok;
 215 }
 216
 217
 218 =head2 _guess_format
 219
 220  Title   : _guess_format
 221  Usage   : $obj->_guess_format($filename)
 222  Returns : guessed format of filename (lower case)
 223  Args    : filename
 224
 225 =cut
 226
 227 sub _guess_format {
 228    my $class = shift;
 229    return unless $_ = shift;
 230    return 'scoring'   if /BLOSUM|PAM$/i;
 231    return 'phylip'   if /\.dist$/i;
 232 }
 233
 234 sub DESTROY {
 235     my $self = shift;
 236     $self->close();
 237 }
 238
 239 sub TIEHANDLE {
 240   my $class = shift;
 241   return bless {'matrixio' => shift},$class;
 242 }
 243
 244 sub READLINE {
 245   my $self = shift;
 246   return $self->{'matrixio'}->next_tree() unless wantarray;
 247   my (@list,$obj);
 248   push @list,$obj  while $obj = $self->{'treeio'}->next_tree();
 249   return @list;
 250 }
 251
 252 sub PRINT {
 253   my $self = shift;
 254   $self->{'matrixio'}->write_tree(@_);
 255 }
 256
 257 1;