Bio/OntologyIO/InterProParser.pm

   1 #
   2 # BioPerl module for InterProParser
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Peter Dimitrov <dimitrov@gnf.org>
   7 #
   8 # Copyright Peter Dimitrov
   9 # (c) Peter Dimitrov, dimitrov@gnf.org, 2002.
  10 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  11 #
  12 # You may distribute this module under the same terms as perl itself.
  13 # Refer to the Perl Artistic License (see the license accompanying this
  14 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  15 # for the terms under which you may use, modify, and redistribute this module.
  16 #
  17 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  18 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  19 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  20 #
  21 # POD documentation - main docs before the code
  22
  23 =head1 NAME
  24
  25 Bio::OntologyIO::InterProParser - Parser for InterPro xml files.
  26
  27 =head1 SYNOPSIS
  28
  29     # don't use this module directly - use Bio::OntologyIO with instead
  30     my $ipp = Bio::OntologyIO->new( -format  => 'interpro',
  31                                     -file    => 't/data/interpro.xml',
  32                                     -ontology_engine => 'simple' );
  33
  34 =head1 DESCRIPTION
  35
  36   Use InterProParser to parse InterPro files in xml format. Typical
  37   use is the interpro.xml file published by EBI. The xml records
  38   should follow the format described in interpro.dtd, although the dtd
  39   file is not needed, and the XML file will not be validated against it.
  40
  41 =head1 FEEDBACK
  42
  43 =head2 Mailing Lists
  44
  45 User feedback is an integral part of the evolution of this and other
  46 Bioperl modules. Send your comments and suggestions preferably to
  47 the Bioperl mailing list.  Your participation is much appreciated.
  48
  49   bioperl-l@bioperl.org                  - General discussion
  50   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  51
  52 =head2 Support
  53
  54 Please direct usage questions or support issues to the mailing list:
  55
  56 I<bioperl-l@bioperl.org>
  57
  58 rather than to the module maintainer directly. Many experienced and
  59 reponsive experts will be able look at the problem and quickly
  60 address it. Please include a thorough description of the problem
  61 with code and data examples if at all possible.
  62
  63 =head2 Reporting Bugs
  64
  65 Report bugs to the Bioperl bug tracking system to help us keep track
  66 of the bugs and their resolution. Bug reports can be submitted via the
  67 web:
  68
  69   https://github.com/bioperl/bioperl-live/issues
  70
  71 =head1 AUTHOR - Peter Dimitrov
  72
  73 Email dimitrov@gnf.org
  74
  75 =head1 APPENDIX
  76
  77 The rest of the documentation details each of the object methods.
  78 Internal methods are usually preceded with a _
  79
  80 =cut
  81
  82
  83 # Let the code begin...
  84
  85
  86 package Bio::OntologyIO::InterProParser;
  87 use strict;
  88 #use Carp;
  89 use XML::Parser::PerlSAX;
  90 use Bio::Ontology::SimpleOntologyEngine;
  91 use Bio::Ontology::TermFactory;
  92 use Bio::OntologyIO::Handlers::InterProHandler;
  93
  94 use base qw(Bio::OntologyIO);
  95
  96 =head2 new
  97
  98  Title   : new
  99  Usage   :
 100  Function: Initializes objects needed for parsing.
 101  Example : $ipp = Bio::OntologyIO::InterProParser->new(
 102                                   -file => 't/data/interpro.xml',
 103                                   -ontology_engine => 'simple' )
 104
 105  Returns : Object of class Bio::OntologyIO::InterProParser.
 106  Args    :
 107
 108   -file            - file name
 109   -ontology_engine - type of ontology engine. Should satisfy the
 110                      OntologyEngine interface requirements. Currently
 111                      the only option is 'simple'. In the future
 112                      Graph.pm based engine will be added to the
 113                      choices.
 114
 115
 116 =cut
 117
 118 # in reality we let OntologyIO handle the first pass initialization
 119 # and instead override _initialize().
 120 sub _initialize{
 121     my $self = shift;
 122
 123     $self->SUPER::_initialize(@_);
 124
 125     my ($eng,$eng_type,$name) =
 126         $self->_rearrange([qw(ENGINE
 127                               ONTOLOGY_ENGINE
 128                               ONTOLOGY_NAME)
 129                            ], @_);
 130
 131     my $ip_h = Bio::OntologyIO::Handlers::InterProHandler->new(
 132                                                      -ontology_name => $name);
 133
 134     if(! $eng) {
 135         $eng_type = 'simple' unless $eng_type;
 136         if(lc($eng_type) eq 'simple') {
 137             $eng = Bio::Ontology::SimpleOntologyEngine->new();
 138         } else {
 139             $self->throw("ontology engine type '$eng_type' ".
 140                          "not implemented yet");
 141         }
 142     }
 143     if($eng->isa("Bio::Ontology::OntologyI")) {
 144         $ip_h->ontology($eng);
 145         $eng = $eng->engine() if $eng->can('engine');
 146     }
 147     $self->{_ontology_engine} = $eng;
 148     $ip_h->ontology_engine($eng);
 149
 150     $self->{_parser} = XML::Parser::PerlSAX->new( Handler => $ip_h );
 151     $self->{_interpro_handler} = $ip_h;
 152
 153     # default term object factory
 154     $self->term_factory(Bio::Ontology::TermFactory->new(
 155                                    -type => "Bio::Ontology::InterProTerm"))
 156         unless $self->term_factory();
 157     $ip_h->term_factory($self->term_factory());
 158
 159 }
 160
 161 =head2 parse
 162
 163  Title   : parse
 164  Usage   :
 165  Function: Performs the actual parsing.
 166  Example : $ipp->parse();
 167  Returns :
 168  Args    :
 169
 170 =cut
 171
 172 sub parse{
 173    my $self = shift;
 174
 175    my $ret;
 176    if ($self->file()) {
 177          $ret = $self->{_parser}->parse( Source => {
 178                         SystemId => $self->file() } );
 179    } elsif ($self->_fh()) {
 180         $ret = $self->{_parser}->parse( Source => {
 181                 ByteStream => $self->_fh() } );
 182    } else {
 183         $ret = undef;
 184         $self->throw("Only filenames and filehandles are understood here.\n");
 185    }
 186
 187    $self->_is_parsed(1);
 188    return $ret;
 189 }
 190
 191 =head2 next_ontology
 192
 193  Title   : next_ontology
 194  Usage   : $ipp->next_ontology()
 195  Function: Parses the input file and returns the next InterPro ontology
 196            available.
 197
 198            Usually there will be only one ontology returned from an
 199            InterPro XML input.
 200
 201  Example : $ipp->next_ontology();
 202  Returns : Returns the ontology as a Bio::Ontology::OntologyEngineI
 203            compliant object.
 204  Args    :
 205
 206 See L<Bio::Ontology::OntologyEngineI>.
 207
 208 =cut
 209
 210 sub next_ontology{
 211   my $self = shift;
 212
 213   $self->parse() unless $self->_is_parsed();
 214   # there is only one ontology in an InterPro source file
 215   if(exists($self->{'_ontology_engine'})) {
 216       my $ont = $self->{_interpro_handler}->ontology();
 217       delete $self->{_ontology_engine};
 218       return $ont;
 219   }
 220   return;
 221 }
 222
 223 =head2 _is_parsed
 224
 225  Title   : _is_parsed
 226  Usage   : $obj->_is_parsed($newval)
 227  Function:
 228  Example :
 229  Returns : value of _is_parsed (a scalar)
 230  Args    : on set, new value (a scalar or undef, optional)
 231
 232 =cut
 233
 234 sub _is_parsed{
 235     my $self = shift;
 236
 237     return $self->{'_is_parsed'} = shift if @_;
 238     return $self->{'_is_parsed'};
 239 }
 240
 241 =head2 secondary_accessions_map
 242
 243  Title   : secondary_accessions_map
 244  Usage   : $obj->secondary_accessions_map()
 245  Function: This method is merely for convenience, and one should
 246            normally use the InterProTerm secondary_ids method to
 247            access the secondary accessions.
 248  Example : $map = $interpro_parser->secondary_accessions_map;
 249  Returns : Reference to a hash that maps InterPro identifier to an
 250            array reference of secondary accessions following the
 251            InterPro xml schema.
 252  Args    : Empty hash reference
 253
 254 =cut
 255
 256 sub secondary_accessions_map{
 257   my ($self) = @_;
 258
 259   return $self->{_interpro_handler}->{secondary_accessions_map};
 260 }
 261
 262 1;