lib/Bio/Matrix/IO.pm

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