[Bio] / Sprout / KBIDUtils.pm Repository:
ViewVC logotype

Annotation of /Sprout/KBIDUtils.pm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.3 - (view) (download) (as text)

1 : parrello 1.1 package KBIDUtils;
2 :    
3 :     use strict;
4 :    
5 :     =head1 KBase ID Server Utilities
6 :    
7 :     This module defines an object that can be used to request and check
8 : parrello 1.2 IDs from the KBase ID server.
9 : parrello 1.1
10 :     The object has the following fields.
11 :    
12 :     =over 4
13 :    
14 :     =item server
15 :    
16 :     Handle to the KBase ID server.
17 :    
18 :     =back
19 :    
20 :     =head2 SPECIAL NOTE
21 :    
22 :     The Kbase ID server is not yet operational, so this method generates
23 :     temporary IDs.
24 :    
25 :     =head2 Special Methods
26 :    
27 :     =head3 new
28 :    
29 :     my $kbidObject = KBIDUtiles->new();
30 :    
31 :     Create a new KBase ID server utility object.
32 :    
33 :     =cut
34 :    
35 :     sub new {
36 :     # Get the class name.
37 :     my ($class) = @_;
38 :     # Create the object.
39 :     my $retVal = {
40 :     };
41 :     # Bless and return it.
42 :     bless $retVal, $class;
43 :     return $retVal;
44 :     }
45 :    
46 :     =head2 Public Methods
47 :    
48 : parrello 1.2 =head3 get_kbase_id
49 :    
50 :     my $newID = $kbidObject->get_kbase_id($source, $id);
51 :    
52 :     Return the KBase ID for a single foreign identifier from the
53 :     specified source database. If the ID does not exist, it will
54 :     be created.
55 :    
56 :     =over 4
57 :    
58 :     =item source
59 :    
60 :     Source (core) database from which the identifier is coming.
61 :    
62 :     =item id
63 :    
64 :     Foreign identifier whose KBase ID is desired.
65 :    
66 :     =item RETURN
67 :    
68 :     Returns the KBase identifier for the specified object.
69 :    
70 :     =back
71 :    
72 :     =cut
73 :    
74 :     sub get_kbase_id {
75 :     # Get the parameters.
76 :     my ($self, $source, $id) = @_;
77 :     # Get the KBase ID for the incoming foreign identifier.
78 :     my $idHash = $self->get_kbase_ids($source, [$id]);
79 :     # Return the result.
80 :     return $idHash->{$id};
81 :     }
82 :    
83 : parrello 1.1 =head3 get_kbase_ids
84 :    
85 : parrello 1.2 my $idHash = $kbidObject->get_kbase_ids($source, \@ids, $noCreate);
86 : parrello 1.1
87 :     Return the KBase ID for one or more foreign identifiers from the
88 : parrello 1.2 specified source database. Normally, if the IDs do not exist, they
89 :     will be created. This behavior can be suppressed, however, by
90 :     specifying the optional B<noCreate> parameter.
91 : parrello 1.1
92 :     =over 4
93 :    
94 :     =item source
95 :    
96 :     Source (core) database from which the identifiers are coming.
97 :    
98 :     =item ids
99 :    
100 :     Reference to a list of foreign identifiers whose KBase IDs are needed.
101 :    
102 : parrello 1.2 =item noCreate (optional)
103 :    
104 :     If TRUE, then no new IDs will be created. The default is FALSE.
105 :    
106 : parrello 1.1 =item RETURN
107 :    
108 :     Returns a reference to a hash mapping each incoming foreign identifier
109 :     to its KBase equivalent.
110 :    
111 :     =back
112 :    
113 :     =cut
114 :    
115 :     sub get_kbase_ids {
116 :     # Get the parameters.
117 : parrello 1.2 my ($self, $source, $ids, $noCreate) = @_;
118 :     # We make two passes through the data. One asks for IDs already
119 :     # registered, and the last registers new IDs. The results of each
120 :     # pass are put in here.
121 : parrello 1.1 my %retVal;
122 :     # Insure the incoming ID is a list.
123 :     if (ref $ids ne 'ARRAY') {
124 :     $ids = [$ids];
125 :     }
126 : parrello 1.2 # Ask for the IDs already registered.
127 :     my $oldHash = $self->_get_kb_identifiers($source, $ids);
128 :     # We'll put the IDs we still need to find in here.
129 :     my @needed;
130 :     # Loop through the ID list.
131 : parrello 1.1 for my $id (@$ids) {
132 : parrello 1.2 # Did we find a registered ID for this one?
133 :     my $oldId = $oldHash->{$id};
134 :     if (defined $oldId) {
135 :     # Yes. Save it.
136 :     $retVal{$id} = $oldId;
137 : parrello 1.1 } else {
138 : parrello 1.2 # No. We must register this ID.
139 :     push @needed, $id;
140 : parrello 1.1 }
141 :     }
142 : parrello 1.2 # Is there anything left to find?
143 :     if (@needed && ! $noCreate) {
144 :     # Yes, register the remaining IDs.
145 :     my $newHash = $self->create_kbase_ids($source, \@needed);
146 :     # Add them to the output hash.
147 :     for my $id (keys %$newHash) {
148 :     $retVal{$id} = $newHash->{$id};
149 : parrello 1.1 }
150 :     }
151 :     # Return the ID mapping.
152 :     return \%retVal;
153 :     }
154 :    
155 :     =head3 create_kbase_ids
156 :    
157 :     my $idHash = $kbidObject->get_kbase_ids($source, \@ids);
158 :    
159 :     Return the KBase ID for one or more foreign identifiers from the
160 :     specified source database. The IDs must not previously exist.
161 :    
162 :     =over 4
163 :    
164 :     =item source
165 :    
166 :     Source (core) database from which the identifiers are coming.
167 :    
168 :     =item ids
169 :    
170 :     Reference to a list of foreign identifiers whose KBase IDs are needed.
171 :    
172 :     =item RETURN
173 :    
174 :     Returns a reference to a hash mapping each incoming foreign identifier
175 :     to its new KBase equivalent.
176 :    
177 :     =back
178 :    
179 :     =cut
180 :    
181 :     sub create_kbase_ids {
182 :     # Get the parameters.
183 :     my ($self, $source, $ids) = @_;
184 :     # Ask the ID server for new IDs.
185 :     my $retVal = $self->_register_kb_identifiers($source, $ids);
186 :     # Return the result.
187 :     return $retVal;
188 :     }
189 :    
190 :     =head2 Internal Methods
191 :    
192 :     =head3 _get_kb_identifiers
193 :    
194 :     my $idHash = $kbidObject->_get_kb_identifiers($source, \@ids);
195 :    
196 :     Ask the KBase ID server to return the identifiers already registered
197 :     for the specified foreign identifiers from the specified database
198 :     source.
199 :    
200 :     =over 4
201 :    
202 :     =item source
203 :    
204 :     Source (core) database from which the identifiers are coming.
205 :    
206 :     =item ids
207 :    
208 :     Reference to a list of foreign identifiers whose KBase IDs are needed.
209 :    
210 :     =item RETURN
211 :    
212 :     Returns a reference to a hash mapping each incoming foreign identifier
213 :     to its KBase equivalent. If no KBase equivalent exists, the identifier
214 :     will not be present in the return hash.
215 :    
216 :     =back
217 :    
218 :     =cut
219 :    
220 :     sub _get_kb_identifiers {
221 :     # Get the parameters.
222 :     my ($self, $source, $ids) = @_;
223 :     # The stubbed version always returns an empty hash.
224 :     return {};
225 :     }
226 :    
227 :     =head3 _register_kb_identifiers
228 :    
229 :     my $idHash = $kbidObject->_register_kb_identifiers($source, \@ids);
230 :    
231 :     Ask the KBase ID server to create new KBase identifiers for the
232 :     specified foreign identifiers from the specified database
233 :     source.
234 :    
235 :     =over 4
236 :    
237 :     =item source
238 :    
239 :     Source (core) database from which the identifiers are coming.
240 :    
241 :     =item ids
242 :    
243 :     Reference to a list of foreign identifiers whose KBase IDs are needed.
244 :    
245 :     =item RETURN
246 :    
247 :     Returns a reference to a hash mapping each incoming foreign identifier
248 :     to its new KBase equivalent.
249 :    
250 :     =back
251 :    
252 :     =cut
253 :    
254 :     sub _register_kb_identifiers {
255 :     # Get the parameters.
256 :     my ($self, $source, $ids) = @_;
257 :     # The stubbed version simply prefixes "kb|" and the source name to the
258 :     # incoming ID.
259 :     my %retVal = map { $_ => "kb|$source|$_" } @$ids;
260 :     return \%retVal;
261 :     }
262 :    
263 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3