lib/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
  88 use strict;
  89 #use Carp;
  90 use XML::Parser::PerlSAX;
  91 use Bio::Ontology::SimpleOntologyEngine;
  92 use Bio::Ontology::TermFactory;
  93 use Bio::OntologyIO::Handlers::InterProHandler;
  94
  95 use base qw(Bio::OntologyIO);
  96
  97 =head2 new
  98
  99  Title   : new
 100  Usage   :
 101  Function: Initializes objects needed for parsing.
 102  Example : $ipp = Bio::OntologyIO::InterProParser->new(
 103                                   -file => 't/data/interpro.xml',
 104                                   -ontology_engine => 'simple' )
 105
 106  Returns : Object of class Bio::OntologyIO::InterProParser.
 107  Args    :
 108
 109   -file            - file name
 110   -ontology_engine - type of ontology engine. Should satisfy the
 111                      OntologyEngine interface requirements. Currently
 112                      the only option is 'simple'. In the future
 113                      Graph.pm based engine will be added to the
 114                      choices.
 115
 116
 117 =cut
 118
 119 # in reality we let OntologyIO handle the first pass initialization
 120 # and instead override _initialize().
 121 sub _initialize{
 122     my $self = shift;
 123
 124     $self->SUPER::_initialize(@_);
 125
 126     my ($eng,$eng_type,$name) =
 127         $self->_rearrange([qw(ENGINE
 128                               ONTOLOGY_ENGINE
 129                               ONTOLOGY_NAME)
 130                            ], @_);
 131
 132     my $ip_h = Bio::OntologyIO::Handlers::InterProHandler->new(
 133                                                      -ontology_name => $name);
 134
 135     if(! $eng) {
 136         $eng_type = 'simple' unless $eng_type;
 137         if(lc($eng_type) eq 'simple') {
 138             $eng = Bio::Ontology::SimpleOntologyEngine->new();
 139         } else {
 140             $self->throw("ontology engine type '$eng_type' ".
 141                          "not implemented yet");
 142         }
 143     }
 144     if($eng->isa("Bio::Ontology::OntologyI")) {
 145         $ip_h->ontology($eng);
 146         $eng = $eng->engine() if $eng->can('engine');
 147     }
 148     $self->{_ontology_engine} = $eng;
 149     $ip_h->ontology_engine($eng);
 150
 151     $self->{_parser} = XML::Parser::PerlSAX->new( Handler => $ip_h );
 152     $self->{_interpro_handler} = $ip_h;
 153
 154     # default term object factory
 155     $self->term_factory(Bio::Ontology::TermFactory->new(
 156                                    -type => "Bio::Ontology::InterProTerm"))
 157         unless $self->term_factory();
 158     $ip_h->term_factory($self->term_factory());
 159
 160 }
 161
 162 =head2 parse
 163
 164  Title   : parse
 165  Usage   :
 166  Function: Performs the actual parsing.
 167  Example : $ipp->parse();
 168  Returns :
 169  Args    :
 170
 171 =cut
 172
 173 sub parse{
 174    my $self = shift;
 175
 176    my $ret;
 177    if ($self->file()) {
 178          $ret = $self->{_parser}->parse( Source => {
 179                         SystemId => $self->file() } );
 180    } elsif ($self->_fh()) {
 181         $ret = $self->{_parser}->parse( Source => {
 182                 ByteStream => $self->_fh() } );
 183    } else {
 184         $ret = undef;
 185         $self->throw("Only filenames and filehandles are understood here.\n");
 186    }
 187
 188    $self->_is_parsed(1);
 189    return $ret;
 190 }
 191
 192 =head2 next_ontology
 193
 194  Title   : next_ontology
 195  Usage   : $ipp->next_ontology()
 196  Function: Parses the input file and returns the next InterPro ontology
 197            available.
 198
 199            Usually there will be only one ontology returned from an
 200            InterPro XML input.
 201
 202  Example : $ipp->next_ontology();
 203  Returns : Returns the ontology as a Bio::Ontology::OntologyEngineI
 204            compliant object.
 205  Args    :
 206
 207 See L<Bio::Ontology::OntologyEngineI>.
 208
 209 =cut
 210
 211 sub next_ontology{
 212   my $self = shift;
 213
 214   $self->parse() unless $self->_is_parsed();
 215   # there is only one ontology in an InterPro source file
 216   if(exists($self->{'_ontology_engine'})) {
 217       my $ont = $self->{_interpro_handler}->ontology();
 218       delete $self->{_ontology_engine};
 219       return $ont;
 220   }
 221   return;
 222 }
 223
 224 =head2 _is_parsed
 225
 226  Title   : _is_parsed
 227  Usage   : $obj->_is_parsed($newval)
 228  Function:
 229  Example :
 230  Returns : value of _is_parsed (a scalar)
 231  Args    : on set, new value (a scalar or undef, optional)
 232
 233 =cut
 234
 235 sub _is_parsed{
 236     my $self = shift;
 237
 238     return $self->{'_is_parsed'} = shift if @_;
 239     return $self->{'_is_parsed'};
 240 }
 241
 242 =head2 secondary_accessions_map
 243
 244  Title   : secondary_accessions_map
 245  Usage   : $obj->secondary_accessions_map()
 246  Function: This method is merely for convenience, and one should
 247            normally use the InterProTerm secondary_ids method to
 248            access the secondary accessions.
 249  Example : $map = $interpro_parser->secondary_accessions_map;
 250  Returns : Reference to a hash that maps InterPro identifier to an
 251            array reference of secondary accessions following the
 252            InterPro xml schema.
 253  Args    : Empty hash reference
 254
 255 =cut
 256
 257 sub secondary_accessions_map{
 258   my ($self) = @_;
 259
 260   return $self->{_interpro_handler}->{secondary_accessions_map};
 261 }
 262
 263 1;