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

Annotation of /FigKernelPackages/TransactionProcessor.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 : olson 1.5 #
3 :     # Copyright (c) 2003-2006 University of Chicago and Fellowship
4 :     # for Interpretations of Genomes. All Rights Reserved.
5 :     #
6 :     # This file is part of the SEED Toolkit.
7 : parrello 1.6 #
8 : olson 1.5 # The SEED Toolkit is free software. You can redistribute
9 :     # it and/or modify it under the terms of the SEED Toolkit
10 : parrello 1.6 # Public License.
11 : olson 1.5 #
12 :     # You should have received a copy of the SEED Toolkit Public License
13 :     # along with this program; if not write to the University of Chicago
14 :     # at info@ci.uchicago.edu or the Fellowship for Interpretation of
15 :     # Genomes at veronika@thefig.info or download a copy from
16 :     # http://www.theseed.org/LICENSE.TXT.
17 :     #
18 :    
19 : parrello 1.1
20 :     package TransactionProcessor;
21 :    
22 :     use strict;
23 :     use Tracer;
24 :     use PageBuilder;
25 :     use FIG;
26 :     use Stats;
27 :    
28 :     =head1 Transaction Processor
29 :    
30 :     =head2 Introduction
31 :    
32 :     This is the base class for a transaction processor. Transaction processors are
33 :     used by the B<TransactFeatures> script to process transactions found in feature
34 :     transaction files. The script reads through files containing add, delete, and
35 :     change transactions for features, and then calls this object's methods to
36 :     effect the transactions. A different subclass of this object is used for
37 :     each of the possible commands that can be input to B<TransactFeatures>.
38 :    
39 :     The transaction processor subclass must provide five methods.
40 :    
41 :     =over 4
42 :    
43 :     =item Add
44 :    
45 :     Add a new feature.
46 :    
47 :     =item Delete
48 :    
49 :     Delete a feature
50 :    
51 :     =item Change
52 :    
53 :     Replace a feature.
54 :    
55 :     =item Setup
56 :    
57 :     Initialize for processing.
58 :    
59 :     =item SetupGenome
60 :    
61 :     Initialize for processing a genome.
62 :    
63 :     =item TeardownGenome
64 :    
65 :     Terminate processing for a genome.
66 :    
67 :     =item Teardown
68 :    
69 :     Terminate processing.
70 :    
71 :     =back
72 :    
73 :     =cut
74 :    
75 :     #: Constructor TransactionProcessor->new();
76 :    
77 :     =head2 Public Methods
78 :    
79 :     =head3 new
80 :    
81 : parrello 1.6 my $xprc = TransactionProcessor->new(\%options, $command, $idFile);
82 : parrello 1.1
83 :     Construct a new Transaction Processor object.
84 :    
85 :     =over 4
86 :    
87 :     =item options
88 :    
89 :     Reference to a hash table containing the command-line options.
90 :    
91 :     =item command
92 :    
93 :     Command specified on the B<TransactFeatures> command line. This command determines
94 :     which TransactionProcessor subclass is active.
95 :    
96 :     =item directory
97 :    
98 :     Directory containing the transaction files.
99 :    
100 :     =item idFile
101 :    
102 :     Name of the ID file (if needed).
103 :    
104 :     =back
105 :    
106 :     =cut
107 :    
108 :     sub new {
109 :     # Get the parameters.
110 :     my ($class, $options, $command, $directory, $idFile) = @_;
111 :     # Set up tracing.
112 :     my $traceLevel = $options->{trace};
113 :     TSetup("$traceLevel $class Tracer FIG TransactionProcessor", "TEXT");
114 :     # Create the xprc object.
115 :     my $retVal = {
116 :     fig => FIG->new(),
117 :     idHash => {},
118 :     options => $options,
119 :     command => $command,
120 :     stats => Stats->new("genomes", "add", "change", "delete"),
121 :     idFileName => $idFile,
122 :     directory => $directory,
123 :     fileName => undef,
124 :     genomeID => undef,
125 :     orgStats => undef
126 :     };
127 :     # Bless and return it.
128 :     bless $retVal, $class;
129 :     return $retVal;
130 :     }
131 :    
132 :     =head3 FIG
133 :    
134 : parrello 1.6 my $fig = $xprc->FIG;
135 : parrello 1.1
136 :     Return the FIG object used to access and manipulate the data store.
137 :    
138 :     =cut
139 :     #: Return Type $%;
140 :     sub FIG {
141 :     # Get the parameters.
142 :     my ($self) = @_;
143 :     # Return the result.
144 :     return $self->{fig};
145 :     }
146 :    
147 :     =head3 GenomeID
148 :    
149 : parrello 1.6 my $genomeID = $xprc->GenomeID;
150 : parrello 1.1
151 :     Return the ID of the current genome. The current genome is specified by the
152 :     L</StartGenome> method.
153 :    
154 :     =cut
155 :     #: Return Type $;
156 :     sub GenomeID {
157 :     # Get the parameters.
158 :     my ($self) = @_;
159 :     # Return the genome ID.
160 :     return $self->{genomeID};
161 :     }
162 :    
163 :     =head3 CurrentFileName
164 :    
165 : parrello 1.6 my $name = $xprc->CurrentFileName;
166 : parrello 1.1
167 :     Return the name of the transaction file currently being read. There is a
168 :     difference file for each genome being processed.
169 :    
170 :     =cut
171 :     #: Return Type $;
172 :     sub CurrentFileName {
173 :     # Get the parameters.
174 :     my ($self) = @_;
175 :     # Return the result.
176 :     return $self->{fileName};
177 :     }
178 :    
179 :     =head3 IncrementStat
180 :    
181 : parrello 1.6 $xprc->IncrementStat($name);
182 : parrello 1.1
183 :     Increment the named statistics in the organism statistics object.
184 :    
185 :     =over 4
186 :    
187 :     =item name
188 :    
189 :     Name of the statistic to increment.
190 :    
191 :     =back
192 :    
193 :     =cut
194 :     #: Return Type ;
195 :     sub IncrementStat {
196 :     # Get the parameters.
197 :     my ($self, $name) = @_;
198 :     # Increment the statistic.
199 :     $self->{orgStats}->Add($name, 1);
200 :     }
201 :    
202 : parrello 1.4 =head3 AddStats
203 :    
204 : parrello 1.6 $xprc->AddStats($name1, $name2, ... $nameN);
205 : parrello 1.4
206 :     Insure statistics with the specified names exist in the organism statistics
207 :     object.
208 :    
209 :     =over 4
210 :    
211 :     =item name1, name2, ..., nameN
212 :    
213 :     Names of the statistics to create.
214 :    
215 :     =back
216 :    
217 :     =cut
218 :     #: Return Type ;
219 :     sub AddStats {
220 :     # Get the parameters.
221 :     my ($self, @names) = @_;
222 :     # Create the statistics.
223 :     map { $self->{orgStats}->Add($_, 0) } @names;
224 :     }
225 :    
226 : parrello 1.1 =head3 AddMessage
227 :    
228 : parrello 1.6 $xprc->AddMessage($message);
229 : parrello 1.1
230 :     Add the specified message to the organism statistics object.
231 :    
232 :     =over 4
233 :    
234 :     =item message
235 :    
236 :     Message to put in the statistical object's message queue.
237 :    
238 :     =back
239 :    
240 :     =cut
241 :     #: Return Type ;
242 :     sub AddMessage {
243 :     # Get the parameters.
244 :     my ($self, $message) = @_;
245 :     # Add the message to the statistics object.
246 :     $self->{orgStats}->AddMessage($message);
247 :     }
248 :    
249 :     =head3 StartGenome
250 :    
251 : parrello 1.6 my = $xprc->StartGenome($genomeID, $orgFileName);
252 : parrello 1.1
253 :     Start processing a particular genome.
254 :    
255 :     =over 4
256 :    
257 :     =item genomeID
258 :    
259 :     ID of the genome for which processing is to begin.
260 :    
261 :     =item
262 :    
263 :     Name of the input file.
264 :    
265 :     =back
266 :    
267 :     =cut
268 :     #: Return Type ;
269 :     sub StartGenome {
270 :     # Get the parameters.
271 :     my ($self, $genomeID, $orgFileName) = @_;
272 :     # Save the genome ID.
273 :     $self->{genomeID} = $genomeID;
274 :     # Create the statistics object for this organism.
275 :     $self->{orgStats} = Stats->new();
276 :     # Save the file name.
277 :     $self->{fileName} = $orgFileName;
278 :     # Do the subclass setup.
279 :     $self->SetupGenome();
280 :     }
281 :    
282 :     =head3 EndGenome
283 :    
284 : parrello 1.6 my $orgStats = $xprc->EndGenome();
285 : parrello 1.1
286 :     Terminate processing for the current genome and return its statistics object.
287 :    
288 :     =cut
289 :     #: Return Type $%;
290 :     sub EndGenome {
291 :     # Get the parameters.
292 :     my ($self) = @_;
293 :     # Do the subclass teardown.
294 :     $self->TeardownGenome();
295 :     # Get the statistics object.
296 :     my $retVal = $self->{orgStats};
297 :     # Roll it up into the global statistics object.
298 :     $self->{stats}->Accumulate($retVal);
299 :     # Count this genome.
300 : parrello 1.3 $self->{stats}->Add("genomes", 1);
301 : parrello 1.1 # Return the genome statistics.
302 :     return $retVal;
303 :     }
304 :    
305 :     =head3 Option
306 :    
307 : parrello 1.6 my $value = $xprc->Option($optionName);
308 : parrello 1.1
309 :     Return the value of the specified command-line option.
310 :    
311 :     =over 4
312 :    
313 :     =item optionName
314 :    
315 :     Name of the command-line option whose value is desired.
316 :    
317 :     =item RETURN
318 :    
319 :     Value of the desired command-line option, or C<undef> if the option does
320 :     not exist.
321 :    
322 :     =back
323 :    
324 :     =cut
325 :     #: Return Type $;
326 :     sub Option {
327 :     # Get the parameters.
328 :     my ($self, $optionName) = @_;
329 :     # Return the option value.
330 :     return $self->{options}->{$optionName};
331 :     }
332 :    
333 :     =head3 GetRealID
334 :    
335 : parrello 1.6 my $realID = $xprc->GetRealID($ftype, $ordinal, $key);
336 : parrello 1.1
337 :     Compute the real ID of a new feature. This involves interrogating the ID hash and
338 :     formatting a full-blown ID out of little bits of information.
339 :    
340 :     =over 4
341 :    
342 :     =item controlBlock
343 :    
344 :     Reference to a hash containing data used to manage the transaction process.
345 :    
346 :     =item ordinal
347 :    
348 :     Zero-based ordinal number of this feature. The ordinal number is added to the value
349 :     stored in the ID hash to compute the real feature number.
350 :    
351 :     =item key
352 :    
353 :     Key in the ID hash relevant to this feature. The key is composed of the genome ID
354 :     followed by the feature type, separated by a period.
355 :    
356 :     =item RETURN
357 :    
358 :     Returns a fully-formatted FIG ID for the new feature.
359 :    
360 :     =back
361 :    
362 :     =cut
363 :    
364 :     sub GetRealID {
365 :     # Get the parameters.
366 :     my ($self, $ordinal, $key) = @_;
367 :     #Declare the return value.
368 :     my $retVal;
369 :     # Get the base value for the feature ID number.
370 :     my $base = $self->{idHash}->{$key};
371 :     # If it didn't exist, we have an error.
372 :     if (! defined $base) {
373 :     Confess("No ID range found for genome ID and feature type $key.");
374 :     } else {
375 :     # Now we have enough data to format the ID.
376 :     my $num = $base + $ordinal;
377 :     $retVal = "fig|$key.$num";
378 :     }
379 :     # Return the result.
380 :     return $retVal;
381 :     }
382 :    
383 :     =head3 ParseNewID
384 :    
385 : parrello 1.6 my ($ftype, $ordinal, $key) = $xprc->ParseNewID($newID);
386 : parrello 1.1
387 :     Extract the feature type and ordinal number from an incoming new ID.
388 :    
389 :     =over 4
390 :    
391 :     =item newID
392 :    
393 :     New ID specification taken from a transaction input record. This contains the
394 :     feature type followed by a period and then the ordinal number of the ID.
395 :    
396 :     =item RETURN
397 :    
398 :     Returna a three-element list. If successful, the list will contain the feature
399 :     type followed by the ordinal number and the key to use in the ID hash to find
400 :     the feature's true ID number. If the incoming ID is invalid, the list
401 :     will contain three C<undef>s.
402 :    
403 :     =back
404 :    
405 :     =cut
406 :    
407 :     sub ParseNewID {
408 :     # Get the parameters.
409 :     my ($self, $newID) = @_;
410 :     # Declare the return variables.
411 :     my ($ftype, $ordinal, $key);
412 :     # Parse the ID.
413 :     if ($newID =~ /^([a-z]+)\.(\d+)$/) {
414 :     # Here we have a valid ID.
415 :     ($ftype, $ordinal) = ($1, $2);
416 :     $key = $self->GenomeID . ".$ftype";
417 :     # Update the feature type count in the statistics.
418 :     $self->{orgStats}->Add($ftype, 1);
419 :     } else {
420 :     # Here we have an invalid ID.
421 :     $self->{orgStats}->AddMessage("Invalid ID $newID found in line " .
422 :     $self->{line} . " for genome " .
423 :     $self->GenomeID . ".");
424 :     }
425 :     # Return the result.
426 :     return ($ftype, $ordinal, $key);
427 :     }
428 :    
429 :     =head3 CheckTranslation
430 :    
431 : parrello 1.6 my $actualTranslation = $xprc->CheckTranslation($ftype, $locations, $translation);
432 : parrello 1.1
433 :     If we are processing a PEG, insure we have a translation for the peg's locations.
434 :    
435 :     This method checks the feature type and the incoming translation string. If the
436 :     translation string is empty and the feature type is C<peg>, it will generate
437 :     a translation string using the specified locations for the genome currently
438 :     being processed.
439 :    
440 :     =over 4
441 :    
442 :     =item ftype
443 :    
444 :     Feature type (C<peg>, C<rna>, etc.)
445 :    
446 :     =item locations
447 :    
448 :     Comma-delimited list of location strings for the feature in question.
449 :    
450 :     =item translation (optional)
451 :    
452 :     If specified, will be returned to the caller as the result.
453 :    
454 :     =item RETURN
455 :    
456 :     Returns the protein translation string for the specified locations, or C<undef>
457 :     if no translation is warranted.
458 :    
459 :     =back
460 :    
461 :     =cut
462 :    
463 :     sub CheckTranslation {
464 :     # Get the parameters.
465 :     my ($self, $ftype, $locations, $translation) = @_;
466 :     my $fig = $self->FIG;
467 :     # Declare the return variable.
468 :     my $retVal;
469 :     if ($ftype eq 'peg') {
470 :     # Here we have a protein encoding gene. Check to see if we already have
471 :     # a translation.
472 :     if (defined $translation) {
473 :     # Pass it back unmodified.
474 :     $retVal = $translation;
475 :     } else {
476 :     # Here we need to compute the translation.
477 :     my $dna = $fig->dna_seq($self->GenomeID, $locations);
478 :     $retVal = FIG::translate($dna);
479 :     }
480 :     }
481 :     # Return the result.
482 :     return $retVal;
483 :     }
484 :    
485 :     =head3 ReadIDHash
486 :    
487 : parrello 1.6 $xprc->ReadIDHash();
488 : parrello 1.1
489 :     Read the ID hash data from the ID file.
490 :    
491 :     =cut
492 :     #: Return Type ;
493 :     sub ReadIDHash {
494 :     # Get the parameters.
495 :     my ($self) = @_;
496 :     # Create a counter.
497 :     my $inCount = 0;
498 :     # Open the ID file.
499 :     my $idFileName = $self->{idFileName};
500 :     Open(\*IDFILE, "<$idFileName");
501 :     # Loop through the records in the file.
502 :     while (my $idRecord = <IDFILE>) {
503 :     # Extract the three fields from the record.
504 :     chomp $idRecord;
505 :     my ($orgID, $ftype, $firstNumber) = split /\t/, $idRecord;
506 :     # Add it to the ID hash.
507 :     $self->{idHash}->{"$orgID.$ftype"} = $firstNumber;
508 :     # Count the record.
509 :     $inCount++;
510 :     }
511 :     Trace("$inCount ID ranges read in from $idFileName.") if T(2);
512 :     }
513 :    
514 :     =head3 Directory
515 :    
516 : parrello 1.6 my $dirName = $xprc->Directory;
517 : parrello 1.1
518 :     Name of the directory containing the transaction files.
519 :    
520 :     =cut
521 :     #: Return Type $;
522 :     sub Directory {
523 :     # Get the parameters.
524 :     my ($self) = @_;
525 :     # Return the directory name.
526 : parrello 1.2 return $self->{directory};
527 : parrello 1.1 }
528 :    
529 :     =head3 IDHash
530 :    
531 : parrello 1.6 my $idHash = $xprc->IDHash;
532 : parrello 1.1
533 :     Return a reference to the ID hash. The ID hash is used to extract the base
534 :     value for new IDs when processing and to count the IDs needed when counting.
535 :    
536 :     =cut
537 :     #: Return Type $%;
538 :     sub IDHash {
539 :     # Get the parameters.
540 :     my ($self) = @_;
541 :     # Return the hash.
542 :     return $self->{idHash};
543 :     }
544 :    
545 :     =head3 IncrementID
546 :    
547 : parrello 1.6 $xprc->IncrementID($ftype);
548 : parrello 1.1
549 :     Increment the ID hash counter for the specified feature type and the current genome.
550 :    
551 :     =over 4
552 :    
553 :     =item ftype
554 :    
555 :     Feature type whose ID counter is to be incremented.
556 :    
557 :     =back
558 :    
559 :     =cut
560 :     #: Return Type ;
561 :     sub IncrementID {
562 :     # Get the parameters.
563 :     my ($self, $ftype) = @_;
564 :     # Create the key.
565 :     my $key = $self->GenomeID . ".$ftype";
566 :     # Increment the counter for the specified key.
567 :     if (exists $self->{idHash}->{$key}) {
568 :     $self->{idHash}->{$key}++;
569 :     } else {
570 :     $self->{idHash}->{$key} = 1;
571 :     }
572 :     }
573 :    
574 :     =head3 IDFileName
575 :    
576 : parrello 1.6 my $idFileName = $xprc->IDFileName;
577 : parrello 1.1
578 :     Return the name of the ID file.
579 :    
580 :     =cut
581 :     #: Return Type $;
582 :     sub IDFileName {
583 :     # Get the parameters.
584 :     my ($self) = @_;
585 :     # Return the ID file name.
586 :     return $self->{idFileName};
587 :     }
588 :    
589 :     =head3 Show
590 :    
591 : parrello 1.6 my $printout = $xprc->Show();
592 : parrello 1.1
593 :     Return a display of the global statistics object. The display will be in printable
594 :     form with embedded new-lines.
595 :    
596 :     =cut
597 :     #: Return Type $;
598 :     sub Show {
599 :     # Get the parameters.
600 :     my ($self) = @_;
601 :     # Return the statistical trace.
602 :     return $self->{stats}->Show();
603 :     }
604 :    
605 :     #### STUBS
606 :     #
607 :     # These essentially do nothing, and are only called if no override is present
608 :     # in the subclass.
609 :     #
610 :    
611 :     sub Add {
612 :     Trace("Add stub called.") if T(4);
613 :     }
614 :    
615 :     sub Change {
616 :     Trace("Change stub called.") if T(4);
617 :     }
618 :    
619 :     sub Delete {
620 :     Trace("Delete stub called.") if T(4);
621 :     }
622 :    
623 :     sub Setup {
624 :     Trace("Setup stub called.") if T(4);
625 :     }
626 :    
627 :     sub Teardown {
628 :     Trace("Teardown stub called.") if T(4);
629 :     }
630 :    
631 :     sub SetupGenome {
632 :     Trace("SetupGenome stub called.") if T(4);
633 :     }
634 :    
635 :     sub TeardownGenome {
636 :     Trace("TeardownGenome stub called.") if T(4);
637 :     }
638 :    
639 :     1;
640 :    

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3