← Back to branch summary

~ubuntu-branches/ubuntu/hoary/bioperl/hoary

« back to all changes in this revision

Viewing changes to Bio/IdentifiableI.pm

  • Committer: Bazaar Package Importer
  • Author(s): Matt Hope
  • Date: 2004-04-18 14:24:11 UTC
  • mfrom: (1.2.1 upstream) (2.1.1 warty)
  • Revision ID: james.westby@ubuntu.com-20040418142411-gr92uexquw4w8liq
Tags: 1.4-1
* New upstream release
* Examples and working code are installed by default to usr/bin,
  this has been moved to usr/share/doc/bioperl/bin

Show diffs side-by-side

added added

removed removed

Lines of Context:
Bio/IdentifiableI.pm
 
1
# $Id: IdentifiableI.pm,v 1.6 2002/10/23 18:07:49 lapp Exp $
 
2
 
 
3
#
 
4
# This module is licensed under the same terms as Perl itself. You use,
 
5
# modify, and redistribute it under the terms of the Perl Artistic License.
 
6
#
 
7
 
 
8
=head1 NAME
 
9
 
 
10
Bio::IdentifiableI - interface for objects with identifiers
 
11
 
 
12
=head1 SYNOPSIS
 
13
 
 
14
 
 
15
    # to test this is an identifiable object
 
16
 
 
17
    $obj->isa("Bio::IdentifiableI") || 
 
18
      $obj->throw("$obj does not implement the Bio::IdentifiableI interface");
 
19
 
 
20
    # accessors
 
21
 
 
22
    $object_id = $obj->object_id();
 
23
    $namespace = $obj->namespace();
 
24
    $authority = $obj->authority();
 
25
    $version   = $obj->version();
 
26
 
 
27
    # utility function
 
28
 
 
29
    $lsid        = $obj->lsid_string();      # gives authority:namespace:object_id
 
30
    $ns_string   = $obj->namespace_string(); # gives namespace:object_id.version
 
31
 
 
32
 
 
33
=head1 DESCRIPTION
 
34
 
 
35
This interface describes methods expected on identifiable objects, ie
 
36
ones which have identifiers expected to make sense across a number of
 
37
instances and/or domains. This interface is modeled after pretty much
 
38
ubiquitous ideas for names in bioinformatics being 
 
39
 
 
40
 databasename:object_id.version
 
41
 
 
42
examples being
 
43
 
 
44
 swissprot:P012334.2
 
45
 
 
46
or
 
47
 
 
48
 GO:0007048
 
49
 
 
50
We also work well with LSID proposals which adds in the concept of an
 
51
authority, being the DNS name of the organisation assigning the namespace.
 
52
Helper functions are provided to make useful strings being
 
53
 
 
54
 
 
55
  lsid_string - string complying to the LSID standard
 
56
  namespace_string - string complying to the usual convention of 
 
57
     namespace:object_id.version
 
58
 
 
59
=head1 FEEDBACK
 
60
 
 
61
=head2 Mailing Lists
 
62
 
 
63
User feedback is an integral part of the evolution of this and other
 
64
Bioperl modules. Send your comments and suggestions preferably to one
 
65
of the Bioperl mailing lists.  Your participation is much appreciated.
 
66
 
 
67
  bioperl-l@bioperl.org                       - General discussion
 
68
  http://bio.perl.org/MailList.html           - About the mailing lists
 
69
 
 
70
=head2 Reporting Bugs
 
71
 
 
72
Report bugs to the Bioperl bug tracking system to help us keep track
 
73
the bugs and their resolution.  Bug reports can be submitted via email
 
74
or the web:
 
75
 
 
76
  bioperl-bugs@bio.perl.org
 
77
  http://bugzilla.bioperl.org/
 
78
 
 
79
=head1 AUTHOR - Ewan Birney
 
80
 
 
81
Email birney@sanger.ac.uk
 
82
 
 
83
=cut
 
84
 
 
85
package Bio::IdentifiableI;
 
86
use vars qw(@ISA );
 
87
use strict;
 
88
use Bio::Root::RootI;
 
89
 
 
90
 
 
91
@ISA = qw(Bio::Root::RootI);
 
92
 
 
93
=head1 Implementation Specific Functions
 
94
 
 
95
These functions are the ones that a specific implementation must
 
96
define.
 
97
 
 
98
=head2 object_id
 
99
 
 
100
 Title   : object_id
 
101
 Usage   : $string    = $obj->object_id()
 
102
 Function: a string which represents the stable primary identifier
 
103
           in this namespace of this object. For DNA sequences this
 
104
           is its accession_number, similarly for protein sequences
 
105
 
 
106
 Returns : A scalar
 
107
 Status  : Virtual
 
108
 
 
109
=cut
 
110
 
 
111
sub object_id {
 
112
   my ($self) = @_;
 
113
   $self->throw_not_implemented();
 
114
}
 
115
 
 
116
=head2 version
 
117
 
 
118
 Title   : version
 
119
 Usage   : $version    = $obj->version()
 
120
 Function: a number which differentiates between versions of
 
121
           the same object. Higher numbers are considered to be
 
122
           later and more relevant, but a single object described
 
123
           the same identifier should represent the same concept
 
124
 
 
125
 Returns : A number
 
126
 Status  : Virtual
 
127
 
 
128
=cut
 
129
 
 
130
sub version {
 
131
   my ($self) = @_;
 
132
   $self->throw_not_implemented();
 
133
}
 
134
 
 
135
 
 
136
=head2 authority
 
137
 
 
138
 Title   : authority
 
139
 Usage   : $authority    = $obj->authority()
 
140
 Function: a string which represents the organisation which
 
141
           granted the namespace, written as the DNS name for  
 
142
           organisation (eg, wormbase.org)
 
143
 
 
144
 Returns : A scalar
 
145
 Status  : Virtual
 
146
 
 
147
=cut
 
148
 
 
149
sub authority {
 
150
   my ($self) = @_;
 
151
   $self->throw_not_implemented();
 
152
}
 
153
 
 
154
 
 
155
=head2 namespace
 
156
 
 
157
 Title   : namespace
 
158
 Usage   : $string    = $obj->namespace()
 
159
 Function: A string representing the name space this identifier
 
160
           is valid in, often the database name or the name
 
161
           describing the collection 
 
162
 
 
163
 Returns : A scalar
 
164
 Status  : Virtual
 
165
 
 
166
=cut
 
167
 
 
168
sub namespace {
 
169
   my ($self) = @_;
 
170
   $self->throw_not_implemented();
 
171
}
 
172
 
 
173
 
 
174
 
 
175
=head1 Implementation optional functions
 
176
 
 
177
These functions are helper functions that are provided by
 
178
the interface but can be overridden if so wished
 
179
 
 
180
=head2 lsid_string
 
181
 
 
182
 Title   : lsid_string
 
183
 Usage   : $string   = $obj->lsid_string()
 
184
 Function: a string which gives the LSID standard
 
185
           notation for the identifier of interest
 
186
 
 
187
 
 
188
 Returns : A scalar
 
189
 
 
190
=cut
 
191
 
 
192
sub lsid_string {
 
193
  my ($self) = @_;
 
194
 
 
195
  return $self->authority.":".$self->namespace.":".$self->object_id;
 
196
}
 
197
 
 
198
 
 
199
 
 
200
=head2 namespace_string
 
201
 
 
202
 Title   : namespace_string
 
203
 Usage   : $string   = $obj->namespace_string()
 
204
 Function: a string which gives the common notation of
 
205
           namespace:object_id.version
 
206
 
 
207
 Returns : A scalar
 
208
 
 
209
=cut
 
210
 
 
211
sub namespace_string {
 
212
  my ($self) = @_;
 
213
 
 
214
  return $self->namespace.":".$self->object_id .
 
215
      (defined($self->version()) ? ".".$self->version : '');
 
216
}
 
217
 
 
218
1;