2 # BioPerl module for Bio::Ontology::OntologyStore
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
8 # Copyright Hilmar Lapp
10 # You may distribute this module under the same terms as perl itself
12 # POD documentation - main docs before the code
16 Bio::Ontology::OntologyStore - A repository of ontologies
24 #make an ontology object manually. via OntologyIO
25 my $io = Bio::OntologyIO->new(
26 #params to fetch Cell Ontology here
28 my $cell_ontology = $io->next_ontology;
30 #this is a singleton that caches the fact that you've created
31 #a 'Cell Ontology' intance...
32 my $store = Bio::Ontology::OntologyStore->get_instance();
34 #...and it can hand you back a copy of it at any time.
35 my $cell_ontology_copy = $store->get_ontology('Cell Ontology');
42 my $store = Bio::Ontology::OntologyStore->get_instance();
43 #this use case allows the construction of an ontology on
44 #demand just by supplying the name.
45 my $ontology = $store->get_ontology('Sequence Ontology');
50 The primary purpose of this module is that of a singleton repository
51 of L<Bio::Ontology::OntologyI> instances from which an Ontology
52 instance can be retrieved by name or identifier. This enables TermI
53 implementations to return their corresponding OntologyI through using
54 this singleton store instead of storing a direct reference to the
55 Ontology object. The latter would almost inevitably lead to memory
56 cycles, and would therefore potentially blow up an application.
62 User feedback is an integral part of the evolution of this and other
63 Bioperl modules. Send your comments and suggestions preferably to
64 the Bioperl mailing list. Your participation is much appreciated.
66 bioperl-l@bioperl.org - General discussion
67 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
71 Please direct usage questions or support issues to the mailing list:
73 I<bioperl-l@bioperl.org>
75 rather than to the module maintainer directly. Many experienced and
76 reponsive experts will be able look at the problem and quickly
77 address it. Please include a thorough description of the problem
78 with code and data examples if at all possible.
82 Report bugs to the Bioperl bug tracking system to help us keep track
83 of the bugs and their resolution. Bug reports can be submitted via
86 https://github.com/bioperl/bioperl-live/issues
88 =head1 AUTHOR - Hilmar Lapp
90 Hilmar Lapp E<lt>hlapp@gmx.netE<gt>
91 Allen Day E<lt>allenday@ucla.eduE<gt>
95 The rest of the documentation details each of the object methods.
96 Internal methods are usually preceded with a _
101 # Let the code begin...
104 package Bio
::Ontology
::OntologyStore
;
107 # Object preamble - inherits from Bio::Root::Root
109 use Bio
::Ontology
::DocumentRegistry
;
112 use File
::Spec
::Functions
;
115 use base
qw(Bio::Root::Root);
117 # these are the static ontology stores by name and by identifier - there is
118 # only one of each in any application
119 my %ont_store_by_name = ();
120 my %ont_store_by_id = ();
122 'Gene Ontology' => 'Gene_Ontology'
124 # also, this is really meant as a singleton object, so we try to enforce it
125 my $instance = undef;
130 Usage : my $obj = Bio::Ontology::OntologyStore->new();
131 Function: Returns the Bio::Ontology::OntologyStore object.
133 Unlike usual implementations of new, this implementation
134 will try to return a previously instantiated store, if
135 there is any. It is just a synonym for get_instance. In
136 order to avoid ambiguities in your code, you may rather
137 want to call rather get_instance explicitly, which also
138 usually is better associated with this kind of behaviour.
140 Returns : an instance of Bio::Ontology::OntologyStore
146 return shift->get_instance(@_);
153 Function: Get an instance of this class for perusal.
155 Since by design this class is meant to be used as a
156 singleton, the implementation will return a previously
157 instantianted store if there is one, and instantiate a new
158 one otherwise. In order to use this class by means of an
159 instance, call this method for added code clarity, not
163 Returns : an instance of this class
164 Args : named parameters, if any (currently, there are no
165 class-specific parameters other than those accepted by
168 See L<Bio::Root::Root>.
173 my ($self,@args) = @_;
176 $instance = $self->SUPER::new
(@args);
185 Function: Get a previously instantiated and registered instance of
186 this class by name or by identifier.
188 One of the main purposes of this class is to enable TermI
189 implementations to return their respective ontology without
190 keeping a strong reference to the respective ontology
191 object. Only objects previously registered objects can be
194 This is a class method, hence you can call it on the class
195 name, without dereferencing an object.
198 Returns : a Bio::Ontology::OntologyI implementing object, or undef
199 if the query could not be satisfied
200 Args : Named parameters specifying the query. The following parameters
202 -name query the store for an ontology with the given name
203 -id query for an ontology with the given identifier
204 If both are specified, an implicit AND logical operator is
207 See L<Bio::Ontology::OntologyI>.
212 my ($self,@args) = @_;
215 my ($name,$id) = $self->_rearrange([qw(NAME ID)], @args);
217 $ont = $ont_store_by_id{$id};
218 return unless $ont; # no AND can be satisfied in this case
222 my $o = $ont_store_by_name{$name};
225 my $doc_registry = Bio
::Ontology
::DocumentRegistry
->get_instance();
226 my($url,$def,$fmt) = $doc_registry->documents($name);
228 if(ref($url) eq 'ARRAY'){
229 my $io = Bio
::OntologyIO
->new(-url
=> $url,
234 $o = $io->next_ontology();
235 $ont_store_by_name{$name} = $o;
237 my $io = Bio
::OntologyIO
->new(-url
=> $url,
241 $o = $io->next_ontology;
242 $ont_store_by_name{$name} = $o;
246 if((! $ont) || ($ont->identifier() eq $o->identifier())) {
256 =head2 register_ontology
258 Title : register_ontology
260 Function: Registers the given Ontology object for later retrieval
261 by name and identifier.
264 Returns : TRUE on success and FALSE otherwise
265 Args : the Bio::Ontology::OntologyI object(s) to register
267 See L<Bio::Ontology::OntologyI>.
271 sub register_ontology
{
272 my ($self,@args) = @_;
274 foreach my $ont (@args) {
275 if(ref($ont) && $ont->isa('Bio::Ontology::OntologyI')){
276 $ont_store_by_name{$ont->name()} = $ont if $ont->name;
280 if(! (ref($ont) && $ont->isa("Bio::Ontology::OntologyI"))) {
281 $self->throw((ref($ont) ?
ref($ont) : $ont)." does not implement ".
282 "Bio::Ontology::OntologyI or is not an object");
284 if($self->get_ontology(-name
=> $ont->name())) {
285 $self->warn("ontology with name \"".$ont->name().
286 "\" already exists in the store, ignoring new one");
290 if($self->get_ontology(-id
=> $ont->identifier())) {
291 $self->warn("ontology with id \"".$ont->identifier().
292 "\" already exists in the store, ignoring new one");
296 $ont_store_by_name{$ont->name()} = $ont;
297 $ont_store_by_id{$ont->identifier()} = $ont;
302 =head2 remove_ontology
304 Title : remove_ontology
306 Function: Remove the specified ontology from the store.
308 Returns : TRUE on success and FALSE otherwise
309 Args : the Bio::Ontology::OntologyI implementing object(s)
310 to be removed from the store
312 See L<Bio::Ontology::OntologyI>.
320 foreach my $ont (@_) {
321 $self->throw(ref($ont)." does not implement Bio::Ontology::OntologyI")
322 unless $ont && ref($ont) && $ont->isa("Bio::Ontology::OntologyI");
323 # remove it from both the id hash and the name hash
324 delete $ont_store_by_id{$ont->identifier()};
325 delete $ont_store_by_name{$ont->name()} if $ont->name();
330 =head2 guess_ontology()
332 Usage : my $ontology =
333 Bio::Ontology::OntologyStore->guess_ontology('GO:0000001');
334 Function: tries to guess which ontology a term identifier comes from,
335 loads it as necessary,
336 and returns it as a Bio::Ontology::Ontology object.
338 Returns : a Bio::Ontology::Ontology object, or warns and returns undef
339 Args : an ontology term identifier in XXXX:DDDDDDD format.
340 Guessing is based on the XXXX string before the colon.
347 my($prefix) = $id =~ /^(.+?):.+$/;
350 SO
=> 'Sequence Ontology',
351 SOFA
=> 'Sequence Ontology Feature Annotation',
352 GO
=> 'Gene Ontology',
355 return $prefix{$prefix} || undef;