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 # _initialize is chained for all FeatureIO classes
 346
 347 sub _initialize {
 348     my($self, %arg) = @_;
 349
 350     # flush is initialized by the Root::IO init
 351
 352     # initialize the IO part
 353     $self->seq($arg{-seq});
 354     $self->_initialize_io(%arg);
 355 }
 356
 357 =head2 next_feature
 358
 359  Title   : next_feature
 360  Usage   : $feature = stream->next_feature
 361  Function: Reads the next feature object from the stream and returns it.
 362
 363            Certain driver modules may encounter entries in the stream
 364            that are either misformatted or that use syntax not yet
 365            understood by the driver. If such an incident is
 366            recoverable, e.g., by dismissing a feature of a feature
 367            table or some other non-mandatory part of an entry, the
 368            driver will issue a warning. In the case of a
 369            non-recoverable situation an exception will be thrown.  Do
 370            not assume that you can resume parsing the same stream
 371            after catching the exception. Note that you can always turn
 372            recoverable errors into exceptions by calling
 373            $stream->verbose(2).
 374
 375  Returns : a Bio::SeqFeatureI feature object
 376  Args    : none
 377
 378 See L<Bio::Root::RootI>, L<Bio::SeqFeatureI>
 379
 380 =cut
 381
 382 sub next_feature {
 383    my ($self, $seq) = @_;
 384    $self->throw("Sorry, you cannot read from a generic Bio::FeatureIO object.");
 385 }
 386
 387 =head2 write_feature
 388
 389  Title   : write_feature
 390  Usage   : $stream->write_feature($feature)
 391  Function: writes the $feature object into the stream
 392  Returns : 1 for success and 0 for error
 393  Args    : Bio::SeqFeature object
 394
 395 =cut
 396
 397 sub write_feature {
 398     my ($self, $seq) = @_;
 399     if(ref($self) eq __PACKAGE__){
 400       $self->throw("Sorry, you cannot write to a generic Bio::FeatureIO object.");
 401     } else {
 402       $self->throw_not_implemented();
 403     }
 404 }
 405
 406 =head2 _load_format_module
 407
 408  Title   : _load_format_module
 409  Usage   : *INTERNAL FeatureIO stuff*
 410  Function: Loads up (like use) a module at run time on demand
 411  Example :
 412  Returns :
 413  Args    :
 414
 415 =cut
 416
 417 sub _load_format_module {
 418     my ($self, $format) = @_;
 419     my $class = ref($self) || $self;
 420     my $module = $class."::$format";#"Bio::Feature::" . $format;
 421     my $ok;
 422
 423     eval {
 424         $ok = $self->_load_module($module);
 425     };
 426     if ( $@ ) {
 427     print STDERR <<END;
 428 $self: $format cannot be found
 429 Exception $@
 430 For more information about the FeatureIO system please see the FeatureIO docs.
 431 This includes ways of checking for formats at compile time, not run time
 432 END
 433   ;
 434   }
 435   return $ok;
 436 }
 437
 438 =head2 seq
 439
 440  Title   : seq
 441  Usage   : $obj->seq() OR $obj->seq($newSeq)
 442  Example :
 443  Returns : Bio::SeqI object
 444  Args    : newSeq (optional)
 445
 446 =cut
 447
 448 sub seq {
 449   my $self = shift;
 450   my $val = shift;
 451
 452   $self->{'seq'} = $val if defined($val);
 453   return $self->{'seq'};
 454 }
 455
 456 =head2 _filehandle
 457
 458  Title   : _filehandle
 459  Usage   : $obj->_filehandle($newval)
 460  Function: This method is deprecated. Call _fh() instead.
 461  Example :
 462  Returns : value of _filehandle
 463  Args    : newvalue (optional)
 464
 465
 466 =cut
 467
 468 sub _filehandle {
 469     my ($self,@args) = @_;
 470     return $self->_fh(@args);
 471 }
 472
 473 =head2 _guess_format
 474
 475  Title   : _guess_format
 476  Usage   : $obj->_guess_format($filename)
 477  Function: guess format based on file suffix
 478  Example :
 479  Returns : guessed format of filename (lower case)
 480  Args    :
 481  Notes   : See "SUPPORTED FORMATS"
 482
 483 =cut
 484
 485 sub _guess_format {
 486    my $class = shift;
 487    return unless $_ = shift;
 488    return 'gff'     if /\.gff3?$/i;
 489    return 'gff'     if /\.gtf$/i;
 490    return 'bed'     if /\.bed$/i;
 491    return 'ptt'     if /\.ptt$/i;
 492
 493    return 'gff'; #the default
 494 }
 495
 496 sub DESTROY {
 497     my $self = shift;
 498     $self->close();
 499 }
 500
 501 sub TIEHANDLE {
 502     my ($class,$val) = @_;
 503     return bless {'featio' => $val}, $class;
 504 }
 505
 506 sub READLINE {
 507   my $self = shift;
 508   return $self->{'featio'}->next_feature() unless wantarray;
 509   my (@list, $obj);
 510   push @list, $obj while $obj = $self->{'featio'}->next_feature();
 511   return @list;
 512 }
 513
 514 sub PRINT {
 515   my $self = shift;
 516   $self->{'featio'}->write_feature(@_);
 517 }
 518
 519 1;
 520