Bio/OntologyIO.pm

   1 #
   2 # BioPerl module for Bio::OntologyIO
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
   7 #
   8 # Copyright Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 #
  13 # (c) Hilmar Lapp, hlapp at gmx.net, 2003.
  14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2003.
  15 #
  16 # You may distribute this module under the same terms as perl itself.
  17 # Refer to the Perl Artistic License (see the license accompanying this
  18 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  19 # for the terms under which you may use, modify, and redistribute this module.
  20 #
  21 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  22 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  23 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  24 #
  25
  26 # POD documentation - main docs before the code
  27
  28 =head1 NAME
  29
  30 Bio::OntologyIO - Parser factory for Ontology formats
  31
  32 =head1 SYNOPSIS
  33
  34     use Bio::OntologyIO;
  35
  36     my $parser = Bio::OntologyIO->new(-format => "go",
  37                                       -file=> $file);
  38
  39     while(my $ont = $parser->next_ontology()) {
  40          print "read ontology ",$ont->name()," with ",
  41                scalar($ont->get_root_terms)," root terms, and ",
  42                scalar($ont->get_leaf_terms)," leaf terms\n";
  43     }
  44
  45 =head1 DESCRIPTION
  46
  47 This is the parser factory for different ontology sources and
  48 formats. Conceptually, it is very similar to L<Bio::SeqIO>, but the
  49 difference is that the chunk of data returned as an object is an
  50 entire ontology.
  51
  52 =head1 FEEDBACK
  53
  54 =head2 Mailing Lists
  55
  56 User feedback is an integral part of the evolution of this and other
  57 Bioperl modules. Send your comments and suggestions preferably to
  58 the Bioperl mailing list.  Your participation is much appreciated.
  59
  60   bioperl-l@bioperl.org                  - General discussion
  61   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  62
  63 =head2 Support
  64
  65 Please direct usage questions or support issues to the mailing list:
  66
  67 I<bioperl-l@bioperl.org>
  68
  69 rather than to the module maintainer directly. Many experienced and
  70 reponsive experts will be able look at the problem and quickly
  71 address it. Please include a thorough description of the problem
  72 with code and data examples if at all possible.
  73
  74 =head2 Reporting Bugs
  75
  76 Report bugs to the Bioperl bug tracking system to help us keep track
  77 of the bugs and their resolution. Bug reports can be submitted via
  78 the web:
  79
  80   https://redmine.open-bio.org/projects/bioperl/
  81
  82 =head1 AUTHOR - Hilmar Lapp
  83
  84 Email hlapp at gmx.net
  85
  86 =head1 APPENDIX
  87
  88 The rest of the documentation details each of the object methods.
  89 Internal methods are usually preceded with a _
  90
  91 =cut
  92
  93
  94 # Let the code begin...
  95
  96
  97 package Bio::OntologyIO;
  98 use strict;
  99
 100 # Object preamble - inherits from Bio::Root::Root
 101
 102
 103 use base qw(Bio::Root::Root Bio::Root::IO);
 104
 105 #
 106 # Maps from format name to driver suitable for the format.
 107 #
 108 my %format_driver_map = (
 109                          "go"          => "goflat",
 110                          "so"          => "soflat",
 111                          "interpro"    => "InterProParser",
 112                          "interprosax" => "Handlers::InterPro_BioSQL_Handler",
 113                          "evoc"        => "simplehierarchy",
 114                          "obo"        => "obo"
 115                          );
 116
 117 =head2 new
 118
 119  Title   : new
 120  Usage   : my $parser = Bio::OntologyIO->new(-format => 'go', @args);
 121  Function: Returns a stream of ontologies opened on the specified input
 122            for the specified format.
 123  Returns : An ontology parser (an instance of Bio::OntologyIO) initialized
 124            for the specified format.
 125  Args    : Named parameters. Common parameters are
 126
 127               -format    - the format of the input; the following are
 128                            presently supported:
 129                   goflat: DAG-Edit Gene Ontology flat files
 130                   go    : synonymous to goflat
 131                   soflat: DAG-Edit Sequence Ontology flat files
 132                   so    : synonymous to soflat
 133                   simplehierarchy: text format with one term per line
 134                           and indentation giving the hierarchy
 135                   evoc  : synonymous to simplehierarchy
 136                   interpro: InterPro XML
 137                   interprosax: InterPro XML - this is actually not a
 138                           Bio::OntologyIO compliant parser; instead it
 139                           persists terms as they are encountered.
 140                           L<Bio::OntologyIO::Handlers::InterPro_BioSQL_Handler>
 141                   obo   : OBO format style from Gene Ontology Consortium
 142               -file      - the file holding the data
 143               -fh        - the stream providing the data (-file and -fh are
 144                           mutually exclusive)
 145               -ontology_name - the name of the ontology
 146               -engine    - the L<Bio::Ontology::OntologyEngineI> object
 147                           to be reused (will be created otherwise); note
 148                           that every L<Bio::Ontology::OntologyI> will
 149                           qualify as well since that one inherits from the
 150                           former.
 151               -term_factory - the ontology term factory to use. Provide a
 152                           value only if you know what you are doing.
 153
 154            DAG-Edit flat file parsers will usually also accept the
 155            following parameters.
 156
 157               -defs_file - the name of the file holding the term
 158                           definitions
 159               -files     - an array ref holding the file names (for GO,
 160                           there will usually be 3 files: component.ontology,
 161                           function.ontology, process.ontology)
 162
 163            Other parameters are specific to the parsers.
 164
 165 =cut
 166
 167 sub new {
 168     my ($caller,@args) = @_;
 169     my $class = ref($caller) || $caller;
 170     # or do we want to call SUPER on an object if $caller is an
 171     # object?
 172     if( $class =~ /Bio::OntologyIO::(\S+)/ ) {
 173         my ($self) = $class->SUPER::new(@args);
 174         $self->_initialize(@args);
 175         return $self;
 176     } else {
 177         my %param = @args;
 178         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 179         my $format = $class->_map_format($param{'-format'});
 180
 181         # normalize capitalization
 182         return unless( $class->_load_format_module($format) );
 183         return "Bio::OntologyIO::$format"->new(@args);
 184     }
 185
 186 }
 187
 188 sub _initialize {
 189     my($self, @args) = @_;
 190
 191     # initialize factories etc
 192     my ($eng,$fact,$ontname) =
 193         $self->_rearrange([qw(TERM_FACTORY)
 194                            ], @args);
 195     # term object factory
 196     $self->term_factory($fact) if $fact;
 197
 198     # initialize the Bio::Root::IO part
 199     $self->_initialize_io(@args);
 200 }
 201
 202 =head2 next_ontology
 203
 204  Title   : next_ontology
 205  Usage   : $ont = $stream->next_ontology()
 206  Function: Reads the next ontology object from the stream and returns it.
 207  Returns : a L<Bio::Ontology::OntologyI> compliant object, or undef at the
 208            end of the stream
 209  Args    : none
 210
 211
 212 =cut
 213
 214 sub next_ontology {
 215     shift->throw_not_implemented();
 216 }
 217
 218 =head2 term_factory
 219
 220  Title   : term_factory
 221  Usage   : $obj->term_factory($newval)
 222  Function: Get/set the ontology term factory to use.
 223
 224            As a user of this module it is not necessary to call this
 225            method as there will be default. In order to change the
 226            default, the easiest way is to instantiate
 227            L<Bio::Ontology::TermFactory> with the proper -type
 228            argument. Most if not all parsers will actually use this
 229            very implementation, so even easier than the aforementioned
 230            way is to simply call
 231            $ontio->term_factory->type("Bio::Ontology::MyTerm").
 232
 233  Example :
 234  Returns : value of term_factory (a Bio::Factory::ObjectFactoryI object)
 235  Args    : on set, new value (a Bio::Factory::ObjectFactoryI object, optional)
 236
 237
 238 =cut
 239
 240 sub term_factory{
 241     my $self = shift;
 242
 243     return $self->{'term_factory'} = shift if @_;
 244     return $self->{'term_factory'};
 245 }
 246
 247 =head1 Private Methods
 248
 249   Some of these are actually 'protected' in OO speak, which means you
 250   may or will want to utilize them in a derived ontology parser, but
 251   you should not call them from outside.
 252
 253 =cut
 254
 255 =head2 _load_format_module
 256
 257  Title   : _load_format_module
 258  Usage   : *INTERNAL OntologyIO stuff*
 259  Function: Loads up (like use) a module at run time on demand
 260  Example :
 261  Returns :
 262  Args    :
 263
 264 =cut
 265
 266 sub _load_format_module {
 267     my ($self, $format) = @_;
 268     my $module = "Bio::OntologyIO::" . $format;
 269     my $ok;
 270
 271     eval {
 272         $ok = $self->_load_module($module);
 273     };
 274     if ( $@ ) {
 275         print STDERR <<END;
 276 $self: $format cannot be found
 277 Exception $@
 278 For more information about the OntologyIO system please see the docs.
 279 This includes ways of checking for formats at compile time, not run time
 280 END
 281     }
 282     return $ok;
 283 }
 284
 285 sub DESTROY {
 286     my $self = shift;
 287
 288     $self->close();
 289 }
 290
 291 sub _map_format {
 292     my $self = shift;
 293     my $format = shift;
 294     my $mod;
 295
 296     if($format) {
 297         $mod = $format_driver_map{lc($format)};
 298         $mod = lc($format) unless $mod;
 299     } else {
 300         $self->throw("unable to guess ontology format, specify -format");
 301     }
 302     return $mod;
 303 }
 304
 305 sub unescape {
 306   my( $self, $ref ) = @_;
 307   $ref =~ s/&lt\\;/\</g;
 308   $ref =~ s/&gt\\;/\>/g;
 309   $ref =~ s/&pct\\;/\%/g;
 310   $ref =~ s/\\n/\n/g;
 311   $ref =~ s/\\t/\t/g;
 312   return $ref;
 313 }
 314
 315 1;