Bio/Matrix/PSM/IO.pm

   1 #---------------------------------------------------------
   2
   3 =head1 NAME
   4
   5 Bio::Matrix::PSM::IO - PSM parser
   6
   7 =head1 SYNOPSIS
   8
   9   use Bio::Matrix::PSM::IO;
  10
  11   my $psmIO= Bio::Matrix::PSM::IO->new(-file=>$file, -format=>'transfac');
  12
  13   my $release=$psmIO->release; #Using Bio::Matrix::PSM::PsmHeader methods
  14
  15   my $release=$psmIO->release;
  16
  17   while (my $psm=$psmIO->next_psm) {
  18    my %psm_header=$psm->header;
  19    my $ic=$psm_header{IC};
  20    my $sites=$psm_header{sites};
  21    my $width=$psm_header{width};
  22    my $score=$psm_header{e_val};
  23    my $IUPAC=$psm->IUPAC;
  24   }
  25
  26   my $instances=$psm->instances;
  27   foreach my $instance (@{$instances}) {
  28     my $id=$instance->primary_id;
  29   }
  30
  31
  32 =head1 DESCRIPTION
  33
  34 This module allows you to read DNA position scoring matrices and/or
  35 their respective sequence matches from a file.
  36
  37 There are two header methods, one belonging to
  38 Bio::Matrix::PSM::IO::driver and the other to
  39 Bio::Matrix::PSM::Psm. They provide general information about the file
  40 (driver) and for the current PSM result (Psm) respectively. Psm header
  41 method always returns the same thing, but some values in the hash
  42 might be empty, depending on the file you are parsing. You will get
  43 undef in this case (no exceptions are thrown).
  44
  45 Please note that the file header data (commenatries, version, input
  46 data, configuration, etc.)  might be obtained through
  47 Bio::Matrix::PSM::PsmHeader methods. Some methods are driver specific
  48 (meme, transfac, etc.): meme: weight mast: seq, instances
  49
  50 If called when you parse a different file type you will get undef. For
  51 example:
  52
  53   my $psmIO= Bio::Matrix::PSM::IO->new(file=>$file, format=>'transfac');
  54   my %seq=$psmIO->seq;
  55
  56 will return an empty hash. To see all methods and how to use them go
  57 to Bio::Matrix::PSM::PsmHeaderI.
  58
  59 See also Bio::Matrix::PSM::PsmI for details on using and manipulating
  60 the parsed data.
  61
  62 The only way to write PFM/PWM is through masta module (something like fasta for
  63 DNA matrices). You can see an example by reading Bio::Matrix::PSM::IO::masta
  64 documentation.
  65
  66 =head1 See also
  67
  68 Bio::Matrix::PSM::PsmI, Bio::Matrix::PSM::PsmHeaderI, Bio::Matrix::PSM::IO::masta
  69
  70 =head1 FEEDBACK
  71
  72 =head2 Mailing Lists
  73
  74 User feedback is an integral part of the evolution of this and other
  75 Bioperl modules. Send your comments and suggestions preferably to one
  76 of the Bioperl mailing lists.  Your participation is much appreciated.
  77
  78   bioperl-l@bioperl.org                  - General discussion
  79   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  80
  81 =head2 Support
  82
  83 Please direct usage questions or support issues to the mailing list:
  84
  85 I<bioperl-l@bioperl.org>
  86
  87 rather than to the module maintainer directly. Many experienced and
  88 reponsive experts will be able look at the problem and quickly
  89 address it. Please include a thorough description of the problem
  90 with code and data examples if at all possible.
  91
  92 =head2 Reporting Bugs
  93
  94 Report bugs to the Bioperl bug tracking system to help us keep track
  95 the bugs and their resolution.  Bug reports can be submitted via the
  96 web:
  97
  98   https://github.com/bioperl/bioperl-live/issues
  99
 100 =head1 AUTHOR - Stefan Kirov
 101
 102 Email skirov@utk.edu
 103
 104 =head1 APPENDIX
 105
 106 =cut
 107
 108
 109 # Let the code begin...
 110 package Bio::Matrix::PSM::IO;
 111 use vars qw(@PSMFORMATS);
 112 use strict;
 113
 114 use base qw(Bio::Root::IO);
 115
 116 @PSMFORMATS = qw(meme transfac mast psiblast masta);
 117
 118 =head2 new
 119
 120  Title   : new
 121  Usage   : my $psmIO =  Bio::Matrix::PSM::IO->new(-format=>'meme',
 122                                                  -file=>$file);
 123  Function: Associates a file with the appropriate parser
 124  Throws  : Throws if the file passed is in HTML format or
 125            if some criteria for the file
 126            format are not met. See L<Bio::Matrix::PSM::IO::meme> and
 127            L<Bio::Matrix::PSM::IO::transfac> for more details.
 128  Example :
 129  Returns : psm object, associated with a file with matrix file
 130  Args    : hash
 131
 132 =cut
 133
 134 sub new {
 135     my($caller,@args) = @_;
 136     my $class = ref($caller) || $caller;
 137     my $self;
 138     # or do we want to call SUPER on an object if $caller is an
 139     # object?
 140     if( $class =~ /Bio::Matrix::PSM::IO(\S+)/ ) {
 141         $self = $class->SUPER::new(@args);
 142         $self->_initialize(@args);
 143         return $self;
 144     } else {
 145         my %param = @args;
 146         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 147         my $format = $param{'-format'} ||
 148             $class->_guess_format( $param{'-file'} || $ARGV[0] ) ||
 149             'scoring';
 150         $class->throw("$format format unrecognized or an argument error occurred\n.") if (!grep(/$format/,@Bio::Matrix::PSM::IO::PSMFORMATS));
 151         $format = "\L$format"; # normalize capitalization to lower case
 152
 153         # normalize capitalization
 154         return unless( $class->_load_format_module($format) );
 155         return "Bio::Matrix::PSM::IO::$format"->new(@args);
 156     }
 157 }
 158
 159 =head2 fh
 160
 161  Title   : fh
 162  Usage   : $obj->fh
 163  Function: Get a filehandle type access to the matrix parser
 164  Example : $fh = $obj->fh;      # make a tied filehandle
 165            $matrix = <$fh>;     # read a matrix object
 166  Returns : filehandle tied to Bio::Matrix::PSM::IO class
 167  Args    : none
 168
 169 =cut
 170
 171 sub fh {
 172     my $self = shift;
 173     my $class = ref($self) || $self;
 174     my $s = Symbol::gensym;
 175     tie $$s,$class,$self;
 176     return $s;
 177 }
 178
 179
 180 =head2 _load_format_module
 181
 182  Title   : _load_format_module
 183  Usage   : *INTERNAL Matrix::PSM::IO stuff*
 184  Function: Loads up (like use) a module at run time on demand
 185
 186 =cut
 187
 188 sub _load_format_module {
 189   my ($self,$format) = @_;
 190   my $module = "Bio::Matrix::PSM::IO::" . $format;
 191   my $ok;
 192
 193   eval {
 194       $ok = $self->_load_module($module);
 195   };
 196   if ( $@ ) {
 197     print STDERR <<END;
 198 $self: $format cannot be found
 199 Exception $@
 200 For more information about the Matrix::PSM::IO system please see the
 201 Matrix::PSM::IO docs.  This includes ways of checking for formats at
 202 compile time, not run time
 203 END
 204   ;
 205   }
 206   return $ok;
 207 }
 208
 209
 210 =head2 _guess_format
 211
 212  Title   : _guess_format
 213  Usage   : $obj->_guess_format($filename)
 214  Returns : guessed format of filename (lower case)
 215  Args    : filename
 216
 217 =cut
 218
 219 sub _guess_format {
 220     my $class = shift;
 221     return unless $_ = shift;
 222     return 'meme'   if /.meme$|meme.html$/i;
 223     return 'transfac'   if /\.dat$/i;
 224     return 'mast'   if /^mast\.|\.mast.html$|.mast$/i;
 225 }
 226
 227 =head2 next_psm
 228
 229  Title   : next_psm
 230  Usage   : my $psm=$psmIO->next_psm();
 231  Function: Reads the next PSM from the input file, associated with this object
 232  Throws  : Throws if there ara format violations in the input file (checking is not
 233             very strict with all drivers).
 234  Example :
 235  Returns : Bio::Matrix::PSM::Psm object
 236  Args    : none
 237
 238 =cut
 239
 240 sub next_psm {
 241     my $self = shift;
 242     $self->throw_not_implemented();
 243 }
 244
 245 =head2 _parseMatrix
 246
 247  Title   : _parseMatrix
 248  Usage   :
 249  Function: Parses the next site matrix information in the meme file
 250  Throws  :
 251  Example :  Internal stuff
 252  Returns :  hash as for constructing a SiteMatrix object (see SiteMatrixI)
 253  Args    :  string
 254
 255 =cut
 256
 257 sub _parseMatrix {
 258     my $self = shift;
 259     $self->throw_not_implemented();
 260 }
 261
 262 =head2 _parseInstance
 263
 264  Title   : _parseInstance
 265  Usage   :
 266  Function: Parses the next sites instances from the meme file
 267  Throws  :
 268  Example : Internal stuff
 269  Returns : Bio::Matrix::PSM::SiteMatrix object
 270  Args    : array references
 271
 272 =cut
 273
 274 sub _parseInstance {
 275     my $self = shift;
 276     $self->throw_not_implemented();
 277 }
 278
 279 =head2 _parse_coordinates
 280
 281  Title   : _parse_coordinates
 282  Usage   :
 283  Function:
 284  Throws  :
 285  Example : Internal stuff
 286  Returns :
 287  Args    :
 288
 289 =cut
 290
 291 sub _parse_coordinates {
 292     my $self = shift;
 293     $self->throw_not_implemented();
 294 }
 295
 296 =head2 header
 297
 298  Title   : header
 299  Usage   :  my %header=$psmIO->header;
 300  Function:  Returns the header for the PSM file, format specific
 301  Throws  :
 302  Example :
 303  Returns :  Hash or a single string with driver specific information
 304  Args    :  none
 305
 306 =cut
 307
 308 sub header {
 309     my $self = shift;
 310     $self->throw_not_implemented();
 311 }
 312
 313 =head2 _make_matrix
 314
 315  Title   : _make_matrix
 316  Usage   :
 317  Function: makes a matrix from 4 array references (A C G T)
 318  Throws  :
 319  Example :
 320  Returns : SiteMatrix object
 321  Args    : array of references(A C G T)
 322
 323 =cut
 324
 325 sub _make_matrix {
 326     my $self = shift;
 327     $self->throw_not_implemented();
 328 }
 329
 330
 331 sub DESTROY {
 332     my $self = shift;
 333     $self->close();
 334 }
 335
 336 1;
 337