[Bio] / FigKernelPackages / CO.pm Repository:
ViewVC logotype

Annotation of /FigKernelPackages/CO.pm

Parent Directory Parent Directory | Revision Log Revision Log


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

1 : parrello 1.1 #!/usr/bin/perl -w
2 :     use strict;
3 :    
4 :     #
5 :     # Copyright (c) 2003-2006 University of Chicago and Fellowship
6 :     # for Interpretations of Genomes. All Rights Reserved.
7 :     #
8 :     # This file is part of the SEED Toolkit.
9 :     #
10 :     # The SEED Toolkit is free software. You can redistribute
11 :     # it and/or modify it under the terms of the SEED Toolkit
12 :     # Public License.
13 :     #
14 :     # You should have received a copy of the SEED Toolkit Public License
15 :     # along with this program; if not write to the University of Chicago
16 :     # at info@ci.uchicago.edu or the Fellowship for Interpretation of
17 :     # Genomes at veronika@thefig.info or download a copy from
18 :     # http://www.theseed.org/LICENSE.TXT.
19 :     #
20 :     package CO;
21 :    
22 :     use strict;
23 :     use ERDB;
24 :     use Tracer;
25 :     use SeedUtils;
26 :     use ServerThing;
27 :     use FC;
28 :    
29 :     =head1 Co-Occurrence Server Function Object
30 :    
31 :     This file contains the functions and utilities used by the Co-Occurrence Server
32 : parrello 1.2 (B<co_occurs_server.cgi>). The L</Primary Methods> represent function
33 : parrello 1.1 calls direct to the server. These all have a signature similar to the following.
34 :    
35 :     my $document = $coObject->function_name($args);
36 :    
37 : parrello 1.2 where C<$coObject> is an object created by this module, C<$args> is a parameter
38 :     structure, and C<function_name> is the Co-Occurrence Server function name. The
39 :     output is a structure, generally a hash reference, but sometimes a string or a
40 :     list reference.
41 : parrello 1.1
42 :     =head2 Special Methods
43 :    
44 :     =head3 new
45 :    
46 : disz 1.6 my $coObject = COserver->new();
47 : parrello 1.1
48 :     Create a new co-occurrence server function object. The server function object
49 : parrello 1.2 contains a pointer to a L<Sapling> object, and is used to invoke the
50 : parrello 1.1 server functions.
51 :    
52 :     =cut
53 :    
54 : disz 1.6 #
55 :     # Actually, if you are using CO.pm, you should do CO->new(), not COserver->new()
56 :     # That comment above is for the benefit of the pod doc stuff on how to use COserver
57 :     # that is generated from this file.
58 :     #
59 :    
60 : parrello 1.1 sub new {
61 :     my ($class) = @_;
62 :     # Create the sapling object.
63 :     my $sap = ERDB::GetDatabase('Sapling');
64 :     # Create the server object.
65 :     my $retVal = { db => $sap };
66 :     # Bless and return it.
67 :     bless $retVal, $class;
68 :     return $retVal;
69 :     }
70 :    
71 :    
72 :     =head2 Primary Methods
73 :    
74 : parrello 1.5 =head3 methods
75 :    
76 :     my $document = $coObject->methods();
77 :    
78 :     Return a list of the methods allowed on this object.
79 :    
80 :     =cut
81 :    
82 :     use constant METHODS => [qw(conserved_in_neighborhood
83 :     pairsets
84 :     clusters_containing
85 :     related_clusters
86 :     co_occurrence_evidence
87 :     related_figfams
88 :     )];
89 :    
90 :     sub methods {
91 :     # Get the parameters.
92 :     my ($self) = @_;
93 :     # Return the result.
94 :     return METHODS;
95 :     }
96 :    
97 : parrello 1.1 =head3 conserved_in_neighborhood
98 :    
99 :     my $document = $coObject->conserved_in_neighborhood($args);
100 :    
101 :     This method takes a list of feature IDs. For each feature ID, it will
102 :     return the set of other features to which it is functionally coupled,
103 :     along with the appropriate score.
104 :    
105 :     =over 4
106 :    
107 :     =item args
108 :    
109 :     Either (1) a reference to a hash mapping the key C<-ids> to a list of FIG
110 : parrello 1.3 feature IDs, or (2) a reference to a list of FIG feature IDs. In case (1),
111 :     the additional parameter C<-hash> can be provided. If it has a value of
112 :     TRUE, then the output will be a hash of lists instead of a list of lists.
113 : parrello 1.1
114 :     =item RETURN
115 :    
116 : parrello 1.3 Returns a reference to a hash or list of sub-lists. Each sub-list corresponds to
117 :     a feature in the input list. The sub-list itself is consists 4-tuples, one per
118 :     feature functionally coupled to the input feature. Each tuple contains the
119 :     coupling score, the FIG ID of the coupled feature, the coupled feature's current
120 :     functional assignment, and the ID of the pair set to which the coupling belongs.
121 :     If the output is a hash, it maps each incoming feature ID to that feature's
122 :     sub-list.
123 : parrello 1.1
124 :     =back
125 :    
126 :     =cut
127 :    
128 :     sub conserved_in_neighborhood {
129 :     # Get the parameters.
130 :     my ($self, $args) = @_;
131 :     # Get the sapling database.
132 :     my $sapling = $self->{db};
133 : parrello 1.3 # Determine the output format.
134 :     my $hashFormat = $args->{-hash} || 0;
135 : parrello 1.1 # Declare the return variable.
136 : parrello 1.3 my $retVal = ($hashFormat ? {} : []);
137 : parrello 1.1 # Convert a list to a hash.
138 :     if (ref $args ne 'HASH') {
139 :     $args = { -ids => $args };
140 :     }
141 :     # Get the list of feature IDs.
142 :     my $ids = ServerThing::GetIdList(-ids => $args);
143 :     # Loop through the features.
144 :     for my $id (@$ids) {
145 :     # Create a sub-list for this feature.
146 :     my $group = [];
147 :     # Ask for the functional coupling information.
148 :     my @co_occurs = &FC::co_occurs($sapling, $id);
149 :     # Loop through the coupling data found.
150 :     for my $tuple (@co_occurs) {
151 :     # Get the coupled feature's data.
152 :     my($sc, $fid, $pairset) = @$tuple;
153 :     # Add it to the group of tuples for this feature's couplings.
154 :     push(@$group, [$sc, $fid, $sapling->Assignment($fid), $pairset]);
155 :     }
156 : parrello 1.3 # Add this feature's couplings to the return value.
157 :     if ($hashFormat) {
158 :     $retVal->{$id} = $group;
159 :     } else {
160 :     push(@$retVal, $group);
161 :     }
162 : parrello 1.1 }
163 :     # Return the result.
164 :     return $retVal;
165 :     }
166 :    
167 :     =head3 pairsets
168 :    
169 :     my $document = $coObject->pairsets($args);
170 :    
171 :     This method takes as input a list of functional-coupling pair set IDs.
172 :     For each pair set, it returns the set's score (number of significant
173 :     couplings) and a list of the coupled pairs in the set.
174 :    
175 :     =over 4
176 :    
177 :     =item args
178 :    
179 :     Either (1) a reference to a list of functional-coupling pair set IDs, or (2) a reference
180 :     to a hash mapping the key C<-ids> to a list of functional-coupling pair set IDs.
181 :    
182 :     =item RETURN
183 :    
184 :     Returns a reference to a list of 2-tuples. Each 2-tuple corresponds to an ID
185 :     from the input list. The 2-tuples themselves each contain the pair set's ID
186 :     followed by another 2-tuple consisting of the score and a reference to a
187 :     list of the pairs in the set. The pairs are represented themselves by
188 :     2-tuples. Because the pairings all belong to the same set, all of the first
189 :     pegs in the pairings are similar to each other, and all of the second pegs
190 :     in the pairings are similar to each other.
191 :    
192 :     =back
193 :    
194 :     =cut
195 :    
196 :     sub pairsets {
197 :     # Get the parameters.
198 :     my ($self, $args) = @_;
199 :     # Get the sapling database.
200 :     my $sapling = $self->{db};
201 :     # Declare the return variable.
202 :     my $retVal = [];
203 :     # Convert a list to a hash.
204 :     if (ref $args ne 'HASH') {
205 :     $args = { -ids => $args };
206 :     }
207 :     # Get the list of pairset IDs.
208 :     my $ids = ServerThing::GetIdList(-ids => $args);
209 :     # Loop through the pairsets.
210 :     for my $id (@$ids) {
211 :     push(@$retVal, [$id, [&FC::co_occurrence_set($sapling, $id)]]);
212 :     }
213 :     # Return the result.
214 :     return $retVal;
215 :     }
216 :    
217 :     =head3 clusters_containing
218 :    
219 :     my $document = $coObject->clusters_containing($args);
220 :    
221 :     This method takes as input a list of feature IDs. For each feature, it
222 :     returns the IDs and functions of other features in the same cluster.
223 :    
224 :     =over 4
225 :    
226 :     =item args
227 :    
228 :     Either (1) a reference to a list of feature IDs, or (2) a reference to a hash
229 :     mapping the key C<-ids> to a list of feature IDs.
230 :    
231 :     =item RETURN
232 :    
233 :     Returns a reference to a list. For each incoming feature, there is a list
234 :     entry containing the feature ID, the feature's functional assignment, and
235 :     a sub-list of 2-tuples. Each 2-tuple contains the ID of another feature in
236 :     the same cluster and its functional assignment.
237 :    
238 :     =back
239 :    
240 :     =cut
241 :    
242 :     sub clusters_containing {
243 :     # Get the parameters.
244 :     my ($self, $args) = @_;
245 :     # Get the sapling database.
246 :     my $sapling = $self->{db};
247 :     # Declare the return variable.
248 :     my $retVal = [];
249 :     # Convert a list to a hash.
250 :     if (ref $args ne 'HASH') {
251 :     $args = { -ids => $args };
252 :     }
253 :     # Get the list of feature IDs.
254 :     my $ids = ServerThing::GetIdList(-ids => $args);
255 :     # Loop through the features.
256 :     for my $id (@$ids) {
257 :     # Get this feature's cluster data.
258 :     my $cluster = &FC::in_co_occurrence_cluster($sapling, $id);
259 :     # If we found something, put it into the output list.
260 :     if ($cluster) {
261 :     my $func = scalar $sapling->Assignment($id);
262 :     push @$retVal, [$id, $func, [map { [$_, $sapling->Assignment($_)] } @$cluster]];
263 :     }
264 :     }
265 :     # Return the result.
266 :     return $retVal;
267 :     }
268 :    
269 :     =head3 related_clusters
270 :    
271 :     my $document = $coObject->related_clusters($args);
272 :    
273 : parrello 1.4 This method returns the functional-coupling clusters related to the specified
274 :     input features. Each cluster contains features on a single genome that are
275 :     related by functional coupling.
276 : parrello 1.1
277 :     =over 4
278 :    
279 :     =item args
280 :    
281 :     Either (1) a reference to a list of FIG feature IDs, or (2) a reference to a hash
282 :     mapping the key C<-ids> to a list of FIG feature IDs.
283 :    
284 :     =item RETURN
285 :    
286 :     Returns a reference to a list. For each incoming feature ID, the output list
287 :     contains a sub-list of clusters. Each cluster in the sub-list is a 3-tuple
288 :     consisting of the ID of a feature similar to the incoming feature, the
289 :     similarity P-score, and a reference to a list of 2-tuples for clustered features.
290 :     Each feature 2-tuple contains the feature ID followed by the functional
291 :     assignment.
292 :    
293 :     =back
294 :    
295 :     =cut
296 :    
297 :     sub related_clusters {
298 :     # Get the parameters.
299 :     my ($self, $args) = @_;
300 :     # Get the sapling database.
301 :     my $sapling = $self->{db};
302 :     # Declare the return variable.
303 :     my $retVal = [];
304 :     # Convert a list to a hash.
305 :     if (ref $args ne 'HASH') {
306 :     $args = { -ids => $args };
307 :     }
308 :     # Get the list of feature IDs.
309 :     my $ids = ServerThing::GetIdList(-ids => $args);
310 :     # Loop through the features.
311 :     for my $id (@$ids) {
312 :     # Create the output list for this feature.
313 :     my $output = [];
314 :     # Loop through the related clusters.
315 :     for my $cluster (FC::largest_co_occurrence_clusters($sapling, $id)) {
316 :     # Get this cluster's data.
317 :     my ($fid, $sc, $other_fids) = @$cluster;
318 :     # Extract the functional roles of the other features in the cluster.
319 :     my $other_tuples = [ map { [$_, $sapling->Assignment($_)] } @$other_fids ];
320 :     # Assemble the result into the output list.
321 :     push @$output, [$fid, $sc, $other_tuples];
322 :     }
323 :     # Push this list of clusters into the master return list.
324 :     push @$retVal, $output;
325 :     }
326 :     # Return the result.
327 :     return $retVal;
328 :     }
329 :    
330 : parrello 1.4 =head3 co_occurrence_evidence
331 :    
332 :     my $document = $coObject->co_occurrence_evidence($args);
333 :    
334 :     For each specified pair of genes, this method returns the evidence that
335 :     the genes are functionally coupled (if any); that is, it returns a list
336 :     of the physically close homologs for the pair.
337 :    
338 :     =over 4
339 :    
340 :     =item args
341 :    
342 :     Reference to a hash containing the parameters.
343 :    
344 :     =item RETURN
345 :    
346 :     Returns a hash mapping each incoming gene pair to a list of 2-tuples. Each 2-tuple
347 :     contains a pair of physically close genes, the first of which is similar to the first
348 :     gene in the input pair, and the second of which is similar to the second gene in the
349 :     input pair. The hash keys will consist of the two gene IDs separated by a colon (e.g.
350 :     C<fig|273035.4.peg.1016:fig|273035.4.peg.1018>).
351 :    
352 :     =back
353 :    
354 :     =head4 Parameter Hash Fields
355 :    
356 :     =over 4
357 :    
358 :     =item -pairs
359 :    
360 :     Reference to a list of functionally-coupled pairs. Each pair is represented by two
361 :     FIG gene IDs, either in the form of a 2-tuple or as a string with the two gene IDs
362 :     separated by a colon.
363 :    
364 :     =back
365 :    
366 :     =cut
367 :    
368 :     sub co_occurrence_evidence {
369 :     # Get the parameters.
370 :     my ($self, $args) = @_;
371 :     # Declare the return variable.
372 :     my $retVal = {};
373 :     # Get the Sapling database.
374 :     my $sap = $self->{db};
375 :     # Get the list of pairs.
376 :     my $pairs = ServerThing::GetIdList(-pairs => $args);
377 :     # Loop through the pairs.
378 :     for my $pair (@$pairs) {
379 :     # Determine the IDs in this pair.
380 :     my ($peg1, $peg2);
381 :     if (ref $pair) {
382 :     ($peg1, $peg2) = @$pair;
383 :     } else {
384 :     ($peg1, $peg2) = split /:/, $pair;
385 :     }
386 :     # Get the evidence and store it in the return hash.
387 :     $retVal->{"$peg1:$peg2"} = FC::co_occurrence_evidence($sap, $peg1, $peg2);
388 :     }
389 :     # Return the result.
390 :     return $retVal;
391 :     }
392 :    
393 :    
394 : parrello 1.1
395 :     =head3 related_figfams
396 :    
397 :     my $document = $coObject->related_figfams($args);
398 :    
399 :     This method takes a list of FIGfam IDs. For each FIGfam, it returns a
400 :     list of FIGfams related to it by functional coupling.
401 :    
402 :     =over 4
403 :    
404 :     =item args
405 :    
406 :     Either (1) a reference to a list of FIGfam IDs, or (2) a reference to a hash
407 :     mapping the key C<-ids> to a list of FIGfam IDs.
408 :    
409 :     =item RETURN
410 :    
411 :     Returns a reference to a list of 2-tuples. Each 2-tuple contains an incoming
412 :     FIGfam ID followed by a sub-list of 2-tuples for other FIGfams. The 2-tuples
413 :     in the sub-list each consist of a related FIGfam's ID followed by a 2-tuple
414 :     containing a coupling score and the related FIGfam's function.
415 :    
416 :     =back
417 :    
418 :     =cut
419 :    
420 :     sub related_figfams {
421 :     # Get the parameters.
422 :     my ($self, $args) = @_;
423 :     # Get the sapling database.
424 :     my $sapling = $self->{db};
425 :     # Declare the return variable.
426 :     my $retVal = [];
427 :     # Convert a list to a hash.
428 :     if (ref $args ne 'HASH') {
429 :     $args = { -ids => $args };
430 :     }
431 :     # Get the list of FIGfam IDs.
432 :     my $ids = ServerThing::GetIdList(-ids => $args);
433 :     # Loop through the FIGfams.
434 :     for my $id (@$ids) {
435 :     push(@$retVal, [$id, [&FC::co_occurring_FIGfams($sapling, $id)]]);
436 :     }
437 :     # Return the result.
438 :     return $retVal;
439 :     }
440 :    
441 :    
442 :    
443 :    
444 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3