branch-1-6/Bio/Restriction/IO.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Restriction::IO
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Rob Edwards <redwards@utmem.edu>
   8 #
   9 # Copyright Rob Edwards
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12 #
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Restriction::IO - Handler for sequence variation IO Formats
  18
  19 =head1 SYNOPSIS
  20
  21     use Bio::Restriction::IO;
  22
  23     $in  = Bio::Restriction::IO->new(-file => "inputfilename" ,
  24                                      -format => 'withrefm');
  25     my $res = $in->read; # a Bio::Restriction::EnzymeCollection
  26
  27 =head1 DESCRIPTION
  28
  29 L<Bio::Restriction::IO> is a handler module for the formats in the
  30 Restriction IO set, e.g. C<Bio::Restriction::IO::xxx>. It is the
  31 officially sanctioned way of getting at the format objects, which most
  32 people should use.
  33
  34 The structure, conventions and most of the code is inherited from
  35 L<Bio::SeqIO>. The main difference is that instead of using methods
  36 C<next_seq>, you drop C<_seq> from the method name.
  37
  38 Also, instead of dealing only with individual L<Bio::Restriction::Enzyme>
  39 objects, C<read()> will slurp in all enzymes into a
  40 L<Bio::Restriction::EnzymeCollection> object.
  41
  42 For more details, see documentation in L<Bio::SeqIO>.
  43
  44 =head1 TO DO
  45
  46 At the moment, these can be use mainly to get a custom set if enzymes in
  47 C<withrefm> or C<itype2> formats into L<Bio::Restriction::Enzyme> or
  48 L<Bio::Restriction::EnzymeCollection> objects.  Using C<bairoch> format is
  49 highly experimental and is not recommmended at this time.
  50
  51 This class inherits from L<Bio::SeqIO> for convenience sake, though this should
  52 inherit from L<Bio::Root::Root>.  Get rid of L<Bio::SeqIO> inheritance by
  53 copying relevant methods in.
  54
  55 C<write()> methods are currently not implemented for any format except C<base>.
  56 Using C<write()> even with C<base> format is not recommended as it does not
  57 support multicut/multisite enzyme output.
  58
  59 Should additional formats be supported (such as XML)?
  60
  61 =head1 SEE ALSO
  62
  63 L<Bio::SeqIO>,
  64 L<Bio::Restriction::Enzyme>,
  65 L<Bio::Restriction::EnzymeCollection>
  66
  67 =head1 FEEDBACK
  68
  69 =head2 Mailing Lists
  70
  71 User feedback is an integral part of the evolution of this and other
  72 Bioperl modules. Send your comments and suggestions preferably to the
  73 Bioperl mailing lists Your participation is much appreciated.
  74
  75   bioperl-l@bioperl.org                  - General discussion
  76   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  77
  78 =head2 Support
  79
  80 Please direct usage questions or support issues to the mailing list:
  81
  82 I<bioperl-l@bioperl.org>
  83
  84 rather than to the module maintainer directly. Many experienced and
  85 reponsive experts will be able look at the problem and quickly
  86 address it. Please include a thorough description of the problem
  87 with code and data examples if at all possible.
  88
  89 =head2 Reporting Bugs
  90
  91 report bugs to the Bioperl bug tracking system to help us keep track
  92 the bugs and their resolution.  Bug reports can be submitted via the
  93 web:
  94
  95   http://bugzilla.open-bio.org/
  96
  97 =head1 AUTHOR
  98
  99 Rob Edwards, redwards@utmem.edu
 100
 101 =head1 CONTRIBUTORS
 102
 103 Heikki Lehvaslaiho, heikki-at-bioperl-dot-org
 104
 105 =head1 APPENDIX
 106
 107 The rest of the documentation details each of the object
 108 methods. Internal methods are usually preceded with a _
 109
 110 =cut
 111
 112 # Let the code begin...
 113
 114 package Bio::Restriction::IO;
 115
 116 use strict;
 117 use vars qw(%FORMAT);
 118 use base qw(Bio::SeqIO);
 119
 120 %FORMAT = (
 121             'itype2'    => 'itype2',
 122             '8'         => 'itype2',
 123             'withrefm'  => 'withrefm',
 124             '31'        => 'withrefm',
 125             'base'      => 'base',
 126             '0'         => 'base',
 127             'bairoch'   => 'bairoch',
 128             '19'        => 'bairoch',
 129             'macvector' => 'bairoch',
 130             'vectorNTI' => 'bairoch',
 131             'neo'       => 'prototype',
 132             'prototype' => 'prototype'
 133 );
 134
 135 =head2 new
 136
 137  Title   : new
 138  Usage   : $stream = Bio::Restriction::IO->new(-file => $filename,
 139                                                -format => 'Format')
 140  Function: Returns a new seqstream
 141  Returns : A Bio::Restriction::IO::Handler initialised with
 142            the appropriate format
 143  Args    : -file => $filename
 144            -format => format
 145            -fh => filehandle to attach to
 146
 147 =cut
 148
 149 sub new {
 150    my ($class, %param) = @_;
 151    my ($format);
 152
 153    @param{ map { lc $_ } keys %param } = values %param;  # lowercase keys
 154    $format = $FORMAT{$param{'-format'}} if defined $param{'-format'};
 155    $format ||= $class->_guess_format( $param{-file} || $ARGV[0] )
 156              || 'base';
 157    $format = "\L$format"; # normalize capitalization to lower case
 158
 159    return unless $class->_load_format_module($format);
 160    return "Bio::Restriction::IO::$format"->new(%param);
 161 }
 162
 163
 164 sub _load_format_module {
 165   my ($class, $format) = @_;
 166   my $module = "Bio::Restriction::IO::" . $format;
 167   my $ok;
 168   eval {
 169       $ok = $class->_load_module($module);
 170   };
 171   if ( $@ ) {
 172     print STDERR <<END;
 173 $class: $format cannot be found
 174 Exception $@
 175 For more information about the IO system please see the IO docs.
 176 This includes ways of checking for formats at compile time, not run time
 177 END
 178   ;
 179   }
 180   return $ok;
 181 }
 182
 183 =head2 read
 184
 185  Title   : read
 186  Usage   : $renzs = $stream->read
 187  Function: reads all the restrction enzymes from the stream
 188  Returns : a Bio::Restriction::EnzymeCollection object
 189  Args    :
 190
 191 =cut
 192
 193 sub read {
 194    my ($self, $seq) = @_;
 195    $self->throw_not_implemented();
 196 }
 197
 198 sub next {
 199    my ($self, $seq) = @_;
 200    $self->throw_not_implemented();
 201 }
 202
 203 sub next_seq {
 204    my ($self, $seq) = @_;
 205    $self->throw_not_implemented();
 206 }
 207
 208 =head2 write
 209
 210  Title   : write
 211  Usage   : $stream->write($seq)
 212  Function: writes the $seq object into the stream
 213  Returns : 1 for success and 0 for error
 214  Args    : Bio::Restriction::EnzymeCollection object
 215
 216 =cut
 217
 218 sub write {
 219     my ($self, $seq) = @_;
 220     $self->throw("Sorry, you cannot write to a generic ".
 221                  "Bio::Restricion::IO object.");
 222 }
 223
 224 sub write_seq {
 225    my ($self, $seq) = @_;
 226    $self->warn("These are not sequence objects. ".
 227                "Use method 'write' instead of 'write_seq'.");
 228    $self->write($seq);
 229 }
 230
 231 =head2 _guess_format
 232
 233  Title   : _guess_format
 234  Usage   : $obj->_guess_format($filename)
 235  Function:
 236  Example :
 237  Returns : guessed format of filename (lower case)
 238  Args    :
 239
 240 =cut
 241
 242 sub _guess_format {
 243    my $class = shift;
 244    return  unless $_ = shift;
 245    return 'flat' if /\.dat$/i;
 246    return 'xml'  if /\.xml$/i;
 247 }
 248
 249
 250 1;