lib/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://github.com/bioperl/bioperl-live/issues
  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
  99 use strict;
 100
 101 # Object preamble - inherits from Bio::Root::Root
 102
 103
 104 use base qw(Bio::Root::Root Bio::Root::IO);
 105
 106 #
 107 # Maps from format name to driver suitable for the format.
 108 #
 109 my %format_driver_map = (
 110                          "go"          => "goflat",
 111                          "so"          => "soflat",
 112                          "interpro"    => "InterProParser",
 113                          "interprosax" => "Handlers::InterPro_BioSQL_Handler",
 114                          "evoc"        => "simplehierarchy",
 115                          "obo"         => "obo"
 116                          );
 117
 118 =head2 new
 119
 120  Title   : new
 121  Usage   : my $parser = Bio::OntologyIO->new(-format => 'go', @args);
 122  Function: Returns a stream of ontologies opened on the specified input
 123            for the specified format.
 124  Returns : An ontology parser (an instance of Bio::OntologyIO) initialized
 125            for the specified format.
 126  Args    : Named parameters. Common parameters are
 127
 128               -format    - the format of the input; the following are
 129                            presently supported:
 130                   goflat: DAG-Edit Gene Ontology flat files
 131                   go    : synonymous to goflat
 132                   soflat: DAG-Edit Sequence Ontology flat files
 133                   so    : synonymous to soflat
 134                   simplehierarchy: text format with one term per line
 135                           and indentation giving the hierarchy
 136                   evoc  : synonymous to simplehierarchy
 137                   interpro: InterPro XML
 138                   interprosax: InterPro XML - this is actually not a
 139                           Bio::OntologyIO compliant parser; instead it
 140                           persists terms as they are encountered.
 141                           L<Bio::OntologyIO::Handlers::InterPro_BioSQL_Handler>
 142                   obo   : OBO format style from Gene Ontology Consortium
 143               -file      - the file holding the data
 144               -fh        - the stream providing the data (-file and -fh are
 145                           mutually exclusive)
 146               -ontology_name - the name of the ontology
 147               -engine    - the L<Bio::Ontology::OntologyEngineI> object
 148                           to be reused (will be created otherwise); note
 149                           that every L<Bio::Ontology::OntologyI> will
 150                           qualify as well since that one inherits from the
 151                           former.
 152               -term_factory - the ontology term factory to use. Provide a
 153                           value only if you know what you are doing.
 154
 155            DAG-Edit flat file parsers will usually also accept the
 156            following parameters.
 157
 158               -defs_file - the name of the file holding the term
 159                           definitions
 160               -files     - an array ref holding the file names (for GO,
 161                           there will usually be 3 files: component.ontology,
 162                           function.ontology, process.ontology)
 163
 164            Other parameters are specific to the parsers.
 165
 166 =cut
 167
 168 sub new {
 169     my ($caller,@args) = @_;
 170     my $class = ref($caller) || $caller;
 171     # or do we want to call SUPER on an object if $caller is an
 172     # object?
 173     if( $class =~ /Bio::OntologyIO::(\S+)/ ) {
 174         my ($self) = $class->SUPER::new(@args);
 175         $self->_initialize(@args);
 176         return $self;
 177     } else {
 178         my %param = @args;
 179         @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
 180         my $format = $class->_map_format($param{'-format'});
 181
 182         # normalize capitalization
 183         return unless( $class->_load_format_module($format) );
 184         return "Bio::OntologyIO::$format"->new(@args);
 185     }
 186
 187 }
 188
 189
 190 =head2 format
 191
 192  Title   : format
 193  Usage   : $format = $parser->format()
 194  Function: Get the ontology format
 195  Returns : ontology format
 196  Args    : none
 197
 198 =cut
 199
 200 # format() method inherited from Bio::Root::IO
 201
 202
 203 sub _initialize {
 204     my($self, @args) = @_;
 205
 206     # initialize factories etc
 207     my ($eng,$fact,$ontname) =
 208         $self->_rearrange([qw(TERM_FACTORY)
 209                            ], @args);
 210     # term object factory
 211     $self->term_factory($fact) if $fact;
 212
 213     # initialize the Bio::Root::IO part
 214     $self->_initialize_io(@args);
 215 }
 216
 217 =head2 next_ontology
 218
 219  Title   : next_ontology
 220  Usage   : $ont = $stream->next_ontology()
 221  Function: Reads the next ontology object from the stream and returns it.
 222  Returns : a L<Bio::Ontology::OntologyI> compliant object, or undef at the
 223            end of the stream
 224  Args    : none
 225
 226
 227 =cut
 228
 229 sub next_ontology {
 230     shift->throw_not_implemented();
 231 }
 232
 233 =head2 term_factory
 234
 235  Title   : term_factory
 236  Usage   : $obj->term_factory($newval)
 237  Function: Get/set the ontology term factory to use.
 238
 239            As a user of this module it is not necessary to call this
 240            method as there will be default. In order to change the
 241            default, the easiest way is to instantiate
 242            L<Bio::Ontology::TermFactory> with the proper -type
 243            argument. Most if not all parsers will actually use this
 244            very implementation, so even easier than the aforementioned
 245            way is to simply call
 246            $ontio->term_factory->type("Bio::Ontology::MyTerm").
 247
 248  Example :
 249  Returns : value of term_factory (a Bio::Factory::ObjectFactoryI object)
 250  Args    : on set, new value (a Bio::Factory::ObjectFactoryI object, optional)
 251
 252
 253 =cut
 254
 255 sub term_factory{
 256     my $self = shift;
 257
 258     return $self->{'term_factory'} = shift if @_;
 259     return $self->{'term_factory'};
 260 }
 261
 262 =head1 Private Methods
 263
 264   Some of these are actually 'protected' in OO speak, which means you
 265   may or will want to utilize them in a derived ontology parser, but
 266   you should not call them from outside.
 267
 268 =cut
 269
 270 =head2 _load_format_module
 271
 272  Title   : _load_format_module
 273  Usage   : *INTERNAL OntologyIO stuff*
 274  Function: Loads up (like use) a module at run time on demand
 275  Example :
 276  Returns :
 277  Args    :
 278
 279 =cut
 280
 281 sub _load_format_module {
 282     my ($self, $format) = @_;
 283     my $module = "Bio::OntologyIO::" . $format;
 284     my $ok;
 285
 286     eval {
 287         $ok = $self->_load_module($module);
 288     };
 289     if ( $@ ) {
 290         print STDERR <<END;
 291 $self: $format cannot be found
 292 Exception $@
 293 For more information about the OntologyIO system please see the docs.
 294 This includes ways of checking for formats at compile time, not run time
 295 END
 296     }
 297     return $ok;
 298 }
 299
 300 sub DESTROY {
 301     my $self = shift;
 302
 303     $self->close();
 304 }
 305
 306 sub _map_format {
 307     my $self = shift;
 308     my $format = shift;
 309     my $mod;
 310
 311     if($format) {
 312         $mod = $format_driver_map{lc($format)};
 313         $mod = lc($format) unless $mod;
 314     } else {
 315         $self->throw("unable to guess ontology format, specify -format");
 316     }
 317     return $mod;
 318 }
 319
 320 sub unescape {
 321   my( $self, $ref ) = @_;
 322   $ref =~ s/&lt\\;/\</g;
 323   $ref =~ s/&gt\\;/\>/g;
 324   $ref =~ s/&pct\\;/\%/g;
 325   $ref =~ s/\\n/\n/g;
 326   $ref =~ s/\\t/\t/g;
 327   return $ref;
 328 }
 329
 330 1;