Bio/FeatureIO.pm

   1 #
   2 # BioPerl module for Bio::FeatureIO
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Allen Day <allenday@ucla.edu>
   7 #
   8 # Copyright Allen Day
   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::FeatureIO - Handler for FeatureIO
  17
  18 =head1 SYNOPSIS
  19
  20   use Bio::FeatureIO;
  21
  22   #read from a file
  23   $in  = Bio::FeatureIO->new(-file => "my.gff" , -format => 'GFF');
  24
  25   #read from a filehandle
  26   $in  = Bio::FeatureIO->new(-fh => \*GFF , -format => 'GFF');
  27
  28   #read features already attached to a sequence
  29   my $feat = Bio::FeatureIO->new(-seq => $seq , -format => 'features');
  30
  31   #read new features for existing sequence
  32   my $seq = Bio::FeatureIO->new(-seq => $seq , -format => 'Das');
  33
  34   #write out features
  35   $out = Bio::FeatureIO->new(-file    => ">outputfilename" ,
  36                              -format  => 'GFF' ,
  37                              -version => 3);
  38
  39   while ( my $feature = $in->next_feature() ) {
  40     $out->write_feature($feature);
  41   }
  42
  43 =head1 DESCRIPTION
  44
  45 NOTE:  This is a highly experimental I/O iterator subsystem for genomic sequence
  46 features. It is not complete, and is now undergoing a significant refactoring in
  47 a separate branch of BioPerl to address specific issues regarding the current
  48 implementation. Use at your own risk.
  49
  50 Bio::FeatureIO is a handler module for the formats in the FeatureIO set (eg,
  51 Bio::FeatureIO::GFF).
  52
  53 The Bio::FeatureIO system can be thought of like biological file handles.
  54 They are attached to filehandles with smart formatting rules (eg,
  55 GFF format, or BED format) and
  56 can either read or write feature objects (Bio::SeqFeature objects, or
  57 more correctly, Bio::FeatureHolderI implementing objects, of which
  58 Bio::SeqFeature is one such object). If you want to know what to
  59 do with a Bio::SeqFeatureI object, read L<Bio::SeqFeatureI>.
  60
  61 The idea is that you request a stream object for a particular format.
  62 All the stream objects have a notion of an internal file that is read
  63 from or written to. A particular FeatureIO object instance is configured
  64 for either input or output. A specific example of a stream object is
  65 the Bio::FeatureIO::gff object.
  66
  67 Each stream object has functions:
  68
  69   $stream->next_feature();
  70   $stream->write_feature($feature);
  71
  72 =head1 SUPPORTED FORMATS
  73
  74  name                         module
  75  -----------------------------------
  76  BED                          bed.pm
  77  GFF                          gff.pm
  78  GTF                          gtf.pm
  79  InterPro (IPRScan 4.0)  interpro.pm
  80  PTT (NCBI protein table)     ptt.pm
  81
  82
  83 =head1 CONSTRUCTORS
  84
  85 =head2 Bio::FeatureIO-E<gt>new()
  86
  87    $featureIO = Bio::FeatureIO->new(-file => 'filename',   -format=>$format);
  88    $featureIO = Bio::FeatureIO->new(-fh   => \*FILEHANDLE, -format=>$format);
  89    $featureIO = Bio::FeatureIO->new(-seq  => $seq,         -format=>$format);
  90
  91 The new() class method constructs a new Bio::FeatureIO object.  The
  92 returned object can be used to retrieve or print Seq objects. new()
  93 accepts the following parameters:
  94
  95 =over 4
  96
  97 =item -file
  98
  99 A file path to be opened for reading or writing.  The usual Perl
 100 conventions apply:
 101
 102    'file'       # open file for reading
 103    '>file'      # open file for writing
 104    '>>file'     # open file for appending
 105    '+<file'     # open file read/write
 106    'command |'  # open a pipe from the command
 107    '| command'  # open a pipe to the command
 108
 109 =item -fh
 110
 111 You may provide new() with a previously-opened filehandle.  For
 112 example, to read from STDIN:
 113
 114    $featio = Bio::FeatureIO->new(-fh => \*STDIN);
 115
 116 Note that you must pass filehandles as references to globs.
 117
 118 If neither a filehandle nor a filename is specified, then the module
 119 will read from the @ARGV array or STDIN, using the familiar E<lt>E<gt>
 120 semantics.
 121
 122 A string filehandle is handy if you want to modify the output in the
 123 memory, before printing it out. The following program reads in EMBL
 124 formatted entries from a file and prints them out in fasta format with
 125 some HTML tags:
 126
 127   use Bio::FeatureIO;
 128   use IO::String;
 129   my $in  = Bio::FeatureIO->new('-file' => "my.gff" ,
 130                             '-format' => 'EMBL');
 131   while ( my $f = $in->next_feature() ) {
 132       # the output handle is reset for every file
 133       my $stringio = IO::String->new($string);
 134       my $out = Bio::FeatureIO->new('-fh' => $stringio,
 135                                 '-format' => 'gtf');
 136       # output goes into $string
 137       $out->write_feature($f);
 138       # modify $string
 139       $string =~ s|(>)(\w+)|$1<font color="Red">$2</font>|g;
 140       # print into STDOUT
 141       print $string;
 142   }
 143
 144 =item -format
 145
 146 Specify the format of the file.  See above for list of supported formats
 147
 148 =item -flush
 149
 150 By default, all files (or filehandles) opened for writing sequences
 151 will be flushed after each write_seq() (making the file immediately
 152 usable).  If you don't need this facility and would like to marginally
 153 improve the efficiency of writing multiple sequences to the same file
 154 (or filehandle), pass the -flush option '0' or any other value that
 155 evaluates as defined but false:
 156
 157   my $f1 = Bio::FeatureIO->new -file   => "<a.f1",
 158                               -format => "f1";
 159   my $f2 = Bio::FeatureIO->new -file   => ">a.f2",
 160                               -format => "f2",
 161                               -flush  => 0; # go as fast as we can!
 162
 163   while($feature = $f1->next_feature) { $f2->write_feature($feature) }
 164
 165 =back
 166
 167 =head2 Bio::FeatureIO-E<gt>newFh()
 168
 169    $fh = Bio::FeatureIO->newFh(-fh   => \*FILEHANDLE, -format=>$format);
 170    $fh = Bio::FeatureIO->newFh(-format => $format);
 171    # etc.
 172
 173 This constructor behaves like new(), but returns a tied filehandle
 174 rather than a Bio::FeatureIO object.  You can read sequences from this
 175 object using the familiar E<lt>E<gt> operator, and write to it using
 176 print().  The usual array and $_ semantics work.  For example, you can
 177 read all sequence objects into an array like this:
 178
 179   @features = <$fh>;
 180
 181 Other operations, such as read(), sysread(), write(), close(), and printf()
 182 are not supported.
 183
 184 =head1 OBJECT METHODS
 185
 186 See below for more detailed summaries.  The main methods are:
 187
 188 =head2 $feature = $featureIO-E<gt>next_feature()
 189
 190 Fetch the next feature from the stream.
 191
 192 =head2 $featureIO-E<gt>write_feature($feature [,$another_feature,...])
 193
 194 Write the specified feature(s) to the stream.
 195
 196 =head2 TIEHANDLE(), READLINE(), PRINT()
 197
 198 These provide the tie interface.  See L<perltie> for more details.
 199
 200 =head1 FEEDBACK
 201
 202 =head2 Mailing Lists
 203
 204 User feedback is an integral part of the evolution of this
 205 and other Bioperl modules. Send your comments and suggestions preferably
 206 to one of the Bioperl mailing lists.
 207
 208 Your participation is much appreciated.
 209
 210   bioperl-l@bioperl.org                  - General discussion
 211   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 212
 213 =head2 Support
 214
 215 Please direct usage questions or support issues to the mailing list:
 216
 217 I<bioperl-l@bioperl.org>
 218
 219 rather than to the module maintainer directly. Many experienced and
 220 reponsive experts will be able look at the problem and quickly
 221 address it. Please include a thorough description of the problem
 222 with code and data examples if at all possible.
 223
 224 =head2 Reporting Bugs
 225
 226 Report bugs to the Bioperl bug tracking system to help us keep track
 227 the bugs and their resolution.  Bug reports can be submitted via the
 228 web:
 229
 230   https://redmine.open-bio.org/projects/bioperl/
 231
 232 =head1 AUTHOR - Allen Day
 233
 234 Email allenday@ucla.edu
 235
 236 =head1 APPENDIX
 237
 238 The rest of the documentation details each of the object
 239 methods. Internal methods are usually preceded with a _
 240
 241 =cut
 242
 243 #' Let the code begin...
 244
 245 package Bio::FeatureIO;
 246
 247 use strict;
 248
 249 use Symbol;
 250
 251 use base qw(Bio::Root::Root Bio::Root::IO);
 252
 253 =head2 new
 254
 255  Title   : new
 256  Usage   : $stream = Bio::FeatureIO->new(-file => $filename, -format => 'Format')
 257  Function: Returns a new feature stream
 258  Returns : A Bio::FeatureIO stream initialised with the appropriate format
 259  Args    : Named parameters:
 260              -file => $filename
 261              -fh => filehandle to attach to
 262              -format => format
 263
 264 =cut
 265
 266 my $entry = 0;
 267
 268 sub new {
 269   my ($caller,@args) = @_;
 270   my $class = ref($caller) || $caller;
 271
 272   # or do we want to call SUPER on an object if $caller is an
 273   # object?
 274   if( $class =~ /Bio::FeatureIO::(\S+)/ ) {
 275
 276     my ($self) = $class->SUPER::new(@args);
 277     $self->_initialize(@args);
 278     return $self;
 279
 280   } else {
 281
 282         my %param = @args;
 283
 284         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 285         my $format = $param{'-format'} ||
 286       $class->_guess_format( $param{-file} || $ARGV[0] );
 287
 288         if( ! $format ) {
 289       if ($param{-file}) {
 290         $format = $class->_guess_format($param{-file});
 291       } elsif ($param{-fh}) {
 292         $format = $class->_guess_format(undef);
 293       }
 294         }
 295         $format = "\L$format";  # normalize capitalization to lower case
 296         return unless( $class->_load_format_module($format) );
 297         return "Bio::FeatureIO::$format"->new(@args);
 298
 299   }
 300 }
 301
 302 =head2 newFh
 303
 304  Title   : newFh
 305  Usage   : $fh = Bio::FeatureIO->newFh(-file=>$filename,-format=>'Format')
 306  Function: does a new() followed by an fh()
 307  Example : $fh = Bio::FeatureIO->newFh(-file=>$filename,-format=>'Format')
 308            $feature = <$fh>;   # read a feature object
 309            print $fh $feature; # write a feature object
 310  Returns : filehandle tied to the Bio::FeatureIO::Fh class
 311  Args    :
 312
 313 See L<Bio::FeatureIO::Fh>
 314
 315 =cut
 316
 317 sub newFh {
 318   my $class = shift;
 319   return unless my $self = $class->new(@_);
 320   return $self->fh;
 321 }
 322
 323 =head2 fh
 324
 325  Title   : fh
 326  Usage   : $obj->fh
 327  Function:
 328  Example : $fh = $obj->fh;      # make a tied filehandle
 329            $feature = <$fh>;   # read a feature object
 330            print $fh $feature; # write a feature object
 331  Returns : filehandle tied to Bio::FeatureIO class
 332  Args    : none
 333
 334 =cut
 335
 336
 337 sub fh {
 338   my $self = shift;
 339   my $class = ref($self) || $self;
 340   my $s = Symbol::gensym;
 341   tie $$s,$class,$self;
 342   return $s;
 343 }
 344
 345 =head2 format
 346
 347  Title   : format
 348  Usage   : $format = $stream->format()
 349  Function: Get the feature format
 350  Returns : feature format
 351  Args    : none
 352
 353 =cut
 354
 355 # format() method inherited from Bio::Root::IO
 356
 357
 358 # _initialize is chained for all FeatureIO classes
 359
 360 sub _initialize {
 361     my($self, %arg) = @_;
 362
 363     # flush is initialized by the Root::IO init
 364
 365     # initialize the IO part
 366     $self->seq($arg{-seq});
 367     $self->_initialize_io(%arg);
 368 }
 369
 370 =head2 next_feature
 371
 372  Title   : next_feature
 373  Usage   : $feature = stream->next_feature
 374  Function: Reads the next feature object from the stream and returns it.
 375
 376            Certain driver modules may encounter entries in the stream
 377            that are either misformatted or that use syntax not yet
 378            understood by the driver. If such an incident is
 379            recoverable, e.g., by dismissing a feature of a feature
 380            table or some other non-mandatory part of an entry, the
 381            driver will issue a warning. In the case of a
 382            non-recoverable situation an exception will be thrown.  Do
 383            not assume that you can resume parsing the same stream
 384            after catching the exception. Note that you can always turn
 385            recoverable errors into exceptions by calling
 386            $stream->verbose(2).
 387
 388  Returns : a Bio::SeqFeatureI feature object
 389  Args    : none
 390
 391 See L<Bio::Root::RootI>, L<Bio::SeqFeatureI>
 392
 393 =cut
 394
 395 sub next_feature {
 396    my ($self, $seq) = @_;
 397    $self->throw("Sorry, you cannot read from a generic Bio::FeatureIO object.");
 398 }
 399
 400 =head2 write_feature
 401
 402  Title   : write_feature
 403  Usage   : $stream->write_feature($feature)
 404  Function: writes the $feature object into the stream
 405  Returns : 1 for success and 0 for error
 406  Args    : Bio::SeqFeature object
 407
 408 =cut
 409
 410 sub write_feature {
 411     my ($self, $seq) = @_;
 412     if(ref($self) eq __PACKAGE__){
 413       $self->throw("Sorry, you cannot write to a generic Bio::FeatureIO object.");
 414     } else {
 415       $self->throw_not_implemented();
 416     }
 417 }
 418
 419 =head2 _load_format_module
 420
 421  Title   : _load_format_module
 422  Usage   : *INTERNAL FeatureIO stuff*
 423  Function: Loads up (like use) a module at run time on demand
 424  Example :
 425  Returns :
 426  Args    :
 427
 428 =cut
 429
 430 sub _load_format_module {
 431     my ($self, $format) = @_;
 432     my $class = ref($self) || $self;
 433     my $module = $class."::$format";#"Bio::Feature::" . $format;
 434     my $ok;
 435
 436     eval {
 437         $ok = $self->_load_module($module);
 438     };
 439     if ( $@ ) {
 440     print STDERR <<END;
 441 $self: $format cannot be found
 442 Exception $@
 443 For more information about the FeatureIO system please see the FeatureIO docs.
 444 This includes ways of checking for formats at compile time, not run time
 445 END
 446   ;
 447   }
 448   return $ok;
 449 }
 450
 451 =head2 seq
 452
 453  Title   : seq
 454  Usage   : $obj->seq() OR $obj->seq($newSeq)
 455  Example :
 456  Returns : Bio::SeqI object
 457  Args    : newSeq (optional)
 458
 459 =cut
 460
 461 sub seq {
 462   my $self = shift;
 463   my $val = shift;
 464
 465   $self->{'seq'} = $val if defined($val);
 466   return $self->{'seq'};
 467 }
 468
 469 =head2 _filehandle
 470
 471  Title   : _filehandle
 472  Usage   : $obj->_filehandle($newval)
 473  Function: This method is deprecated. Call _fh() instead.
 474  Example :
 475  Returns : value of _filehandle
 476  Args    : newvalue (optional)
 477
 478
 479 =cut
 480
 481 sub _filehandle {
 482     my ($self,@args) = @_;
 483     return $self->_fh(@args);
 484 }
 485
 486 =head2 _guess_format
 487
 488  Title   : _guess_format
 489  Usage   : $obj->_guess_format($filename)
 490  Function: guess format based on file suffix
 491  Example :
 492  Returns : guessed format of filename (lower case)
 493  Args    :
 494  Notes   : See "SUPPORTED FORMATS"
 495
 496 =cut
 497
 498 sub _guess_format {
 499    my $class = shift;
 500    return unless $_ = shift;
 501    return 'gff'     if /\.gff3?$/i;
 502    return 'gff'     if /\.gtf$/i;
 503    return 'bed'     if /\.bed$/i;
 504    return 'ptt'     if /\.ptt$/i;
 505
 506    return 'gff'; #the default
 507 }
 508
 509 sub DESTROY {
 510     my $self = shift;
 511     $self->close();
 512 }
 513
 514 sub TIEHANDLE {
 515     my ($class,$val) = @_;
 516     return bless {'featio' => $val}, $class;
 517 }
 518
 519 sub READLINE {
 520   my $self = shift;
 521   return $self->{'featio'}->next_feature() unless wantarray;
 522   my (@list, $obj);
 523   push @list, $obj while $obj = $self->{'featio'}->next_feature();
 524   return @list;
 525 }
 526
 527 sub PRINT {
 528   my $self = shift;
 529   $self->{'featio'}->write_feature(@_);
 530 }
 531
 532 1;
 533