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

Annotation of /FigKernelPackages/CO.pm

Parent Directory Parent Directory | Revision Log Revision Log


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

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3