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 use strict;
  80
  81
  82 use base qw(Bio::Root::IO);
  83
  84 =head2 new
  85
  86  Title   : new
  87  Usage   : my $obj = Bio::Matrix::IO->new();
  88  Function: Builds a new Bio::Matrix::IO object
  89  Returns : an instance of Bio::Matrix::IO
  90  Args    :
  91
  92
  93 =cut
  94
  95 sub new {
  96   my($caller,@args) = @_;
  97   my $class = ref($caller) || $caller;
  98
  99     # or do we want to call SUPER on an object if $caller is an
 100     # object?
 101     if( $class =~ /Bio::Matrix::IO::(\S+)/ ) {
 102         my ($self) = $class->SUPER::new(@args);
 103         $self->_initialize(@args);
 104         return $self;
 105     } else {
 106
 107         my %param = @args;
 108         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 109         my $format = $param{'-format'} ||
 110             $class->_guess_format( $param{'-file'} || $ARGV[0] ) ||
 111                 'scoring';
 112         $format = "\L$format";  # normalize capitalization to lower case
 113
 114         # normalize capitalization
 115         return unless( $class->_load_format_module($format) );
 116         return "Bio::Matrix::IO::$format"->new(@args);
 117     }
 118 }
 119
 120 =head2 newFh
 121
 122  Title   : newFh
 123  Usage   : $fh = Bio::Matrix::IO->newFh(-file=>$filename,-format=>'Format')
 124  Function: does a new() followed by an fh()
 125  Example : $fh = Bio::Matrix::IO->newFh(-file=>$filename,-format=>'Format')
 126            $matrix = <$fh>;   # read a matrix object
 127            print $fh $matrix; # write a matrix object
 128  Returns : filehandle tied to the Bio::SeqIO::Fh class
 129  Args    :
 130
 131 =cut
 132
 133 sub newFh {
 134   my $class = shift;
 135   return unless my $self = $class->new(@_);
 136   return $self->fh;
 137 }
 138
 139 =head2 fh
 140
 141  Title   : fh
 142  Usage   : $obj->fh
 143  Function: Get a filehandle type access to the matrix parser
 144  Example : $fh = $obj->fh;      # make a tied filehandle
 145            $matrix = <$fh>;     # read a matrix object
 146            print $fh $matrix;   # write a matrix object
 147  Returns : filehandle tied to Bio::Matrix::IO class
 148  Args    : none
 149
 150 =cut
 151
 152
 153 sub fh {
 154   my $self = shift;
 155   my $class = ref($self) || $self;
 156   my $s = Symbol::gensym;
 157   tie $$s,$class,$self;
 158   return $s;
 159 }
 160
 161
 162 =head2 format
 163
 164  Title   : format
 165  Usage   : $format = $obj->format()
 166  Function: Get the matrix format
 167  Returns : matrix format
 168  Args    : none
 169
 170 =cut
 171
 172 # format() method inherited from Bio::Root::IO
 173
 174
 175 =head2 next_matrix
 176
 177  Title   : next_matrix
 178  Usage   : my $matrix = $matixio->next_matrix;
 179  Function: Parse the next matrix from the data stream
 180  Returns : L<Bio::Matrix::MatrixI> type object or undef when finished
 181  Args    : none
 182
 183
 184 =cut
 185
 186 sub next_matrix{
 187    my ($self) = @_;
 188    $self->throw_not_implemented();
 189 }
 190
 191 =head2 write_matrix
 192
 193  Title   : write_matrix
 194  Usage   : $io->write_matrix($matrix)
 195  Function: Writes a matrix out to the data stream
 196  Returns : none
 197  Args    : Array of Bio::Matrix::MatrixI object
 198           - note that not all matricies can be converted to
 199             each format, beware with mixing matrix types and output formats
 200
 201 =cut
 202
 203 sub write_matrix{
 204    my ($self) = @_;
 205    $self->throw_not_implemented();
 206 }
 207
 208 sub _initialize {
 209     my ($self,@args) = @_;
 210     $self->_initialize_io(@args);
 211 }
 212
 213 =head2 _load_format_module
 214
 215  Title   : _load_format_module
 216  Usage   : *INTERNAL Matrix::IO stuff*
 217  Function: Loads up (like use) a module at run time on demand
 218
 219 =cut
 220
 221 sub _load_format_module {
 222   my ($self,$format) = @_;
 223   my $module = "Bio::Matrix::IO::" . $format;
 224   my $ok;
 225
 226   eval {
 227       $ok = $self->_load_module($module);
 228   };
 229   if ( $@ ) {
 230     print STDERR <<END;
 231 $self: $format cannot be found
 232 Exception $@
 233 For more information about the Matrix::IO system please see the
 234 Matrix::IO docs.  This includes ways of checking for formats at
 235 compile time, not run time
 236 END
 237   ;
 238   }
 239   return $ok;
 240 }
 241
 242
 243 =head2 _guess_format
 244
 245  Title   : _guess_format
 246  Usage   : $obj->_guess_format($filename)
 247  Returns : guessed format of filename (lower case)
 248  Args    : filename
 249
 250 =cut
 251
 252 sub _guess_format {
 253    my $class = shift;
 254    return unless $_ = shift;
 255    return 'scoring'   if /BLOSUM|PAM$/i;
 256    return 'phylip'   if /\.dist$/i;
 257 }
 258
 259 sub DESTROY {
 260     my $self = shift;
 261     $self->close();
 262 }
 263
 264 sub TIEHANDLE {
 265   my $class = shift;
 266   return bless {'matrixio' => shift},$class;
 267 }
 268
 269 sub READLINE {
 270   my $self = shift;
 271   return $self->{'matrixio'}->next_tree() || undef unless wantarray;
 272   my (@list,$obj);
 273   push @list,$obj  while $obj = $self->{'treeio'}->next_tree();
 274   return @list;
 275 }
 276
 277 sub PRINT {
 278   my $self = shift;
 279   $self->{'matrixio'}->write_tree(@_);
 280 }
 281
 282 1;