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

Annotation of /Sprout/TargetCriterion.pm

Parent Directory Parent Directory | Revision Log Revision Log


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

1 : parrello 1.1 #!/usr/bin/perl -w
2 :    
3 :     #
4 :     # Copyright (c) 2003-2006 University of Chicago and Fellowship
5 :     # for Interpretations of Genomes. All Rights Reserved.
6 :     #
7 :     # This file is part of the SEED Toolkit.
8 :     #
9 :     # The SEED Toolkit is free software. You can redistribute
10 :     # it and/or modify it under the terms of the SEED Toolkit
11 :     # Public License.
12 :     #
13 :     # You should have received a copy of the SEED Toolkit Public License
14 :     # along with this program; if not write to the University of Chicago
15 :     # at info@ci.uchicago.edu or the Fellowship for Interpretation of
16 :     # Genomes at veronika@thefig.info or download a copy from
17 :     # http://www.theseed.org/LICENSE.TXT.
18 :     #
19 :    
20 :     package TargetCriterion;
21 :    
22 :     use strict;
23 :     use Tracer;
24 :     use CGI qw(-nosticky);
25 :     use Sprout;
26 :    
27 :    
28 :     =head1 Target Search Criterion Object
29 :    
30 :     =head2 Introduction
31 :    
32 :     This object is the base class for all a target search criteria. For a specific
33 :     type of criterion, it provides methods that tell [[SHTargetSearchPm]] how to
34 :     configure the form, how to generate a query filter, how to check a returned
35 :     object to see if it qualifies, and which extra fields should be displayed in the
36 :     results. It is also used by [[RHFeaturePm]] to provide additional column support.
37 :    
38 :     It's important to realize that an instance of this object represents a desire to
39 :     make a criterion available, not a specific crterion that can be applied to
40 :     determine the results of a search. The criterion objects are generated in the
41 :     constructor for the target search; the actual cirteria are specified in the form
42 :     fields filled out be the user. Thus, there would be a criterion object for
43 :     specifying the GC content range, but the criterion object won't know the minimum
44 :     and maximum values for the range, just how to deal with those values when the
45 :     user enters them.
46 :    
47 :     A criterion in the target search form is implemented as a table row. The first
48 :     column of the table contains buttons for adding and deleting rows. The second
49 :     column contains the type dropdown. Selecting an entry in the type dropdown tells
50 :     the target search which criterion object applies to it. The last column contains
51 :     configurable form fields, including a selection control, an min/max control, a
52 :     text input control, and a hint control.
53 :    
54 :     This object contains a cache that tracks the value of the current feature as
55 :     it relates to the criterion. The user may specify the same criterion more than
56 :     once with different filter values, but both will involve the same data about a
57 :     feature. For example, a query could ask for features that occur in both the
58 :     cytoplasm and the cell wall. This will generate two filter elements
59 :     (CellLocation = Cytoplasm AND CellLocation = CellWall) but both will use the
60 :     same criterion object. When the first filter element is checked, all of the
61 :     cell locations will be read into the cell-location criterion object's cache,
62 :     and the cached value is reused when the second filter element is checked.
63 :    
64 :     The fields in this object are as follows.
65 :    
66 :     =over 4
67 :    
68 :     =item rhelp
69 :    
70 :     [[SHTargetSearchPm]] object for the current search
71 :    
72 :     =item hint
73 :    
74 :     Tooltip string for the hint control when the user selects this criterion in the
75 :     type dropdown.
76 :    
77 :     =item selectionData
78 :    
79 :     Reference to a hash mapping selection values to labels. The hash is used to
80 :     generate the javascript for configuring the selection control. To indicate
81 :     a pre-selected value, prefix it with an asterisk. If this field is undefined,
82 :     then the selection control is hidden.
83 :    
84 :     =item minMax
85 :    
86 :     TRUE if the min/max control is to be displayed, else FALSE
87 :    
88 :     =item text
89 :    
90 :     TRUE if the text control is to be displayed, else FALSE
91 :    
92 :     =item label
93 :    
94 :     Label for this criterion type in the criterion type dropdown.
95 :    
96 :     =item message
97 :    
98 :     Error message from the most recent validation error.
99 :    
100 :     =item cache
101 :    
102 :     A cache containing the data value for the current feature relevant to this criterion.
103 :     This is frequently a list reference. The cache is automatically cleared each time
104 :     a new feature is processed by the search helper.
105 :    
106 :     =item name
107 :    
108 :     Name of this criterion.
109 :    
110 :     =back
111 :    
112 :     =cut
113 :    
114 :     =head3 new
115 :    
116 :     my $tc = TargetCriterion->new($rhelp, %options);
117 :    
118 :     Construct a new TargetCriterion object. The following parameters are expected.
119 :    
120 :     =over 4
121 :    
122 :     =item rhelp
123 :    
124 :     [[ResultHelperPm]] object for the active search.
125 :    
126 :     =item options
127 :    
128 :     Hash of constructor options.
129 :    
130 :     =back
131 :    
132 :     The following options are supported.
133 :    
134 :     =over 4
135 :    
136 :     =item minMax
137 :    
138 :     TRUE if the criterion uses the min/max control.
139 :    
140 :     =item text
141 :    
142 :     TRUE if the criterion uses the text control.
143 :    
144 :     =item selectionData
145 :    
146 :     Reference to the I<selectionData> hash, or undefined if the selection control is
147 :     not used
148 :    
149 :     =item hint
150 :    
151 :     Tooltip string for the hint control.
152 :    
153 :     =item label
154 :    
155 :     Label to give to this type in the criterion type dropdown.
156 :    
157 :     =item name
158 :    
159 :     Identifying name for this criterion.
160 :    
161 :     =back
162 :    
163 :     =cut
164 :    
165 :     sub new {
166 :     # Get the parameters.
167 :     my ($class, $rhelp, %options) = @_;
168 :     # Get the options.
169 :     my $minMax = $options{minMax} || 0;
170 :     my $text = $options{text} || 0;
171 :     my $selectionData = $options{selectionData};
172 :     my $hint = $options{hint} || 'click for help';
173 :     my $label = $options{label};
174 :     my $name = $options{name};
175 :     # Create the TargetCriterion object.
176 :     my $retVal = {
177 :     rhelp => $rhelp,
178 :     hint => $hint,
179 :     selectionData => $selectionData,
180 :     minMax => $minMax,
181 :     text => $text,
182 :     label => $label,
183 :     message => '',
184 :     name => $name,
185 :     cache => undef,
186 :     };
187 :     # Bless and return it.
188 :     bless $retVal, $class;
189 :     return $retVal;
190 :     }
191 :    
192 :     =head2 Public Methods
193 :    
194 :     =head3 message
195 :    
196 :     my $message = $tc->message();
197 :    
198 :     Get the error message computed by this object's most recent L</Validate> call.
199 :    
200 :     =cut
201 :    
202 :     sub message {
203 :     my ($self) = @_;
204 :     return $self->{message};
205 :     }
206 :    
207 :     =head3 name
208 :    
209 :     my $name = $tc->name();
210 :    
211 :     Get the identifying name of this criterion.
212 :    
213 :     =cut
214 :    
215 :     sub name {
216 :     my ($self) = @_;
217 :     return $self->{name};
218 :     }
219 :    
220 :     =head3 SetMessage
221 :    
222 :     $tc->SetMessage($newValue);
223 :    
224 :     Store a new error message in this object.
225 :    
226 :     =over 4
227 :    
228 :     =item newValue
229 :    
230 :     New error message to be stored in this object.
231 :    
232 :     =back
233 :    
234 :     =cut
235 :    
236 :     sub SetMessage {
237 :     my ($self, $newValue) = @_;
238 :     $self->{message} = $newValue;
239 :     }
240 :    
241 :     =head3 GetMinMax
242 :    
243 :     my ($min, $max) = $self->GetMinMax($criterion);
244 :    
245 :     Return the minimum and maximum values for the specified criterion.
246 :    
247 :     =over 4
248 :    
249 :     =item criterion
250 :    
251 :     A Criterion Parameter Object containing the minimum and maximum values as parameters.
252 :    
253 :     =item RETURN
254 :    
255 :     Returns a 2-tuple containing the minimum value followed by the maximum value. If
256 :     either value is non-numeric, it will be converted to C<undef>.
257 :    
258 :     =back
259 :    
260 :     =cut
261 :    
262 :     sub GetMinMax {
263 :     # Get the parameters.
264 :     my ($self, $criterion) = @_;
265 :     # Declare the return variables.
266 :     my ($min, $max) = map { Tracer::Numeric($criterion->{$_}) } qw(minValue maxValue);
267 :     # Return the results.
268 :     return ($min, $max);
269 :     }
270 :    
271 :     =head3 EqualCheck
272 :    
273 :     my $match = $tc->EqualCheck($feature, $value);
274 :    
275 :     Return TRUE if the specified feature has the specified value for this
276 :     criterion's field, else FALSE.
277 :    
278 :     =over 4
279 :    
280 :     =item suffix
281 :    
282 :     The ID number for the criterion.
283 :    
284 :     =item feature
285 :    
286 :     An [[ERDBObjectPm]] containing the relevant Feature record along with its parent
287 :     Genome.
288 :    
289 :     =item RETURN
290 :    
291 :     Returns TRUE if the relevant field value for the specified feature matches the
292 :     specified value, else FALSE. If there is more than one value for the field.
293 :    
294 :     =back
295 :    
296 :     =cut
297 :    
298 :     sub EqualCheck {
299 :     # Get the parameters.
300 :     my ($self, $suffix, $feature, $value) = @_;
301 :     # Get the relevant field values.
302 :     my $values = $self->GetValue($feature);
303 :     # Compute the number of matching values. If it's one or more, we have a match.
304 :     my $retVal = scalar grep { $_ eq $value } @$values;
305 :     # Return the result.
306 :     return $retVal;
307 :     }
308 :    
309 :     =head2 Internal Methods
310 :    
311 :     =head3 Reset
312 :    
313 :     $tc->Reset();
314 :    
315 :     Denote that a new feature is being processed. This clears the data cache.
316 :    
317 :     =cut
318 :    
319 :     sub Reset {
320 :     # Get the parameters.
321 :     my ($self) = @_;
322 :     # Delete the cache.
323 :     $self->{cache} = undef;
324 :     }
325 :    
326 :     =head3 PutExtras
327 :    
328 :     $tc->PutExtras($rhelp, $feature);
329 :    
330 :     Add any required extra columns for this criterion to the result helper. Note
331 :     that this method will only be called if the subclass has overridden
332 :     L</AddExtraColumns>.
333 :    
334 :     =over 4
335 :    
336 :     =item rhelp
337 :    
338 :     Result helper to which the extra columns are to be added.
339 :    
340 :     =item feature
341 :    
342 :     [[ERDBObjectPm]] object for the current feature.
343 :    
344 :     =back
345 :    
346 :     =cut
347 :    
348 :     sub PutExtras {
349 :     # Get the parameters.
350 :     my ($self, $rhelp, $feature) = @_;
351 :     # Get the value data object from the cache.
352 :     my $valueData = $self->GetValue($feature);
353 :     # Ask the subclass to add the extra columns.
354 :     $self->PutExtraColumns($rhelp, $valueData);
355 :     }
356 :    
357 :     =head3 Check
358 :    
359 :     my $match = $tc->Check($criterion, $feature);
360 :    
361 :     Return TRUE if the specified feature matches the specified criterion
362 :     parameters, else FALSE.
363 :    
364 :     =over 4
365 :    
366 :     =item criterion
367 :    
368 :     A Criterion Parameter Object containing the specific parameter values to check.
369 :    
370 :     =item feature
371 :    
372 :     An [[ERDBObjectPm]] containing the relevant Feature record along with its parent
373 :     Genome.
374 :    
375 :     =item RETURN
376 :    
377 :     Returns TRUE if the specified criterion parameters match the specified feature with
378 :     respect to this criterion, else FALSE.
379 :    
380 :     =back
381 :    
382 :     =cut
383 :    
384 :     sub Check {
385 :     # Get the parameters.
386 :     my ($self, $criterion, $feature) = @_;
387 :     # Get the cache data for this criterion.
388 :     my $valueData = $self->GetValue($feature);
389 :     # Ask the subclass if we match.
390 :     my $retVal = $self->CheckValue($criterion, $valueData);
391 :     # Return the result.
392 :     return $retVal;
393 :     }
394 :    
395 :     =head3 GetValue
396 :    
397 :     my $value = $tc->GetValue($feature);
398 :    
399 :     Return the value data from the specified feature that is relevant to this
400 :     criterion. This method is called when value is needed to call
401 :     L</PutExtraColumns> or L</CheckValue>. If the value is not in the cache,
402 :     it will call a virtual method to retrieve it from the subclass.
403 :    
404 :     =over 4
405 :    
406 :     =item feature
407 :    
408 :     AN [[ERDBObject]] describing the current feature under consideration.
409 :    
410 :     =item RETURN
411 :    
412 :     A scalar value or reference describing the relevant data for the specified feature.
413 :    
414 :     =back
415 :    
416 :     =cut
417 :    
418 :     sub GetValue {
419 :     # Get the parameters.
420 :     my ($self, $feature) = @_;
421 :     # Check the cache.
422 :     my $retVal = $self->{cache};
423 :     # If it wasn't found, ask for it.
424 :     if (! defined $retVal) {
425 :     $retVal = $self->GetValueData($feature);
426 :     # Cache it for next time.
427 :     $self->{cache} = $retVal;
428 :     }
429 :     # Return the result.
430 :     return $retVal;
431 :     }
432 :    
433 :     =head3 label
434 :    
435 :     my $label = $tc->label();
436 :    
437 :     Return the label for this criterion, for use in the criterion type
438 :     dropdown.
439 :    
440 :     =cut
441 :    
442 :     sub label {
443 :     # Get the parameters.
444 :     my ($self) = @_;
445 :     # Declare the return variable.
446 :     my $retVal = $self->{label};
447 :     # Insure we have a label.
448 :     if (! defined $retVal) {
449 :     Confess("No label specified for search criterion.");
450 :     }
451 :     # Return the result.
452 :     return $retVal;
453 :     }
454 :    
455 :     =head3 hint
456 :    
457 :     my $hint = $tc->hint();
458 :    
459 :     Return the tooltip hint for this criterion, for use in the hint control.
460 :    
461 :     =cut
462 :    
463 :     sub hint {
464 :     # Get the parameters.
465 :     my ($self) = @_;
466 :     # Return the hint.
467 :     return $self->{hint};
468 :     }
469 :    
470 :     =head3 minMax
471 :    
472 :     my $flag = $tc->minMax();
473 :    
474 :     Return C<true> if the min/max control should be shown for this criterion, else C<false>.
475 :     It is worth noting that we're returning the strings C<true> and C<false>, not a PERL
476 :     boolean. That is because this function is used in generating javascript.
477 :    
478 :     =cut
479 :    
480 :     sub minMax {
481 :     # Get the parameters.
482 :     my ($self) = @_;
483 :     # Return the hint.
484 :     return ($self->{minMax} ? 'true' : 'false');
485 :     }
486 :    
487 :     =head3 text
488 :    
489 :     my $flag = $tc->text();
490 :    
491 :     Return C<true> if the text control should be shown for this criterion, else C<false>.
492 :     It is worth noting that we're returning the strings C<true> and C<false>, not a PERL
493 :     boolean. That is because this function is used in generating javascript.
494 :    
495 :     =cut
496 :    
497 :     sub text {
498 :     # Get the parameters.
499 :     my ($self) = @_;
500 :     # Return the hint.
501 :     return ($self->{text} ? 'true' : 'false');
502 :     }
503 :    
504 :     =head3 selectionData
505 :    
506 :     my $hash = $tc->selectionData();
507 :    
508 :     Return the selection data hash for this criterion, or an undefined value if this
509 :     criterion doesn't use the selection control.
510 :    
511 :     =cut
512 :    
513 :     sub selectionData {
514 :     # Get the parameters.
515 :     my ($self) = @_;
516 :     # Return the selection hash.
517 :     return $self->{selectionData};
518 :     }
519 :    
520 :    
521 :     =head3 DB
522 :    
523 :     my $sprout = $tc->DB();
524 :    
525 :     Return the ERDB database object for the relevant database.
526 :    
527 :     =cut
528 :    
529 :     sub DB {
530 :     my ($self) = @_;
531 :     return $self->{rhelp}->DB();
532 :     }
533 :    
534 :     =head2 Virtual Methods
535 :    
536 :     =head3 Validate
537 :    
538 :     my $okFlag = $tc->Validate($parms);
539 :    
540 :     Return TRUE if the specified parameters are valid for a search criterion of this type
541 :     and FALSE otherwise. If an error is detected, the error message can be retrieved using
542 :     the L</message> method.
543 :    
544 :     =over 4
545 :    
546 :     =item parms
547 :    
548 :     A Criterion Parameter Object whose fields are to be validated.
549 :    
550 :     =item RETURN
551 :    
552 :     Returns TRUE if the parameters are valid, else FALSE.
553 :    
554 :     =back
555 :    
556 :     =cut
557 :    
558 :     sub Validate {
559 :     Confess("Pure virtual Validate method called.");
560 :     }
561 :    
562 :     =head3 Sane
563 :    
564 :     my $flag = $tc->Sane($parms);
565 :    
566 :     Return TRUE if this is a sane criterion, else FALSE. Every search must have at least one
567 :     sane criterion in order to be valid.
568 :    
569 :     =over 4
570 :    
571 :     =item parms (optional)
572 :    
573 :     A Criterion Parameter Object for the current query.
574 :    
575 :     =item RETURN
576 :    
577 :     Returns TRUE if this query returns a relatively limited result set and uses SQL,
578 :     else FALSE. If you do not override this method, it returns FALSE.
579 :    
580 :     =back
581 :    
582 :     =cut
583 :    
584 :     sub Sane {
585 :     return 0;
586 :     }
587 :    
588 :     =head3 ComputeQuery
589 :    
590 :     my ($joins, $filterString, $parms) = $tc->ComputeQuery($criterion);
591 :    
592 :     Compute the SQL filter, join list, and parameter list for this
593 :     criterion. If the criterion cannot be processed by SQL, then nothing is
594 :     returned, and the criterion must be handled during post-processing.
595 :    
596 :     The join list and the parameter list should both be list references. The
597 :     filter string is a true string.
598 :    
599 :     If the filter string only uses the B<Genome> and B<Feature> tables, then the
600 :     join list can be left empty. Otherwise, the join list should start with the
601 :     particular starting point (B<Genome> or B<Feature>) and list the path through
602 :     the other relevant entities and relationships. Each criterion will have its
603 :     own separate join path.
604 :    
605 :     =over 4
606 :    
607 :     =item criterion
608 :    
609 :     Reference to a Criterion Parameter Object.
610 :    
611 :     =item RETURN
612 :    
613 :     Returns a 3-tuple consisting of the join list, the relevant filter string,
614 :     and the matching parameters. If the criterion cannot be processed using
615 :     SQL, then the return list contains three undefined values. (This is what happens if
616 :     you don't override this method.)
617 :    
618 :     =back
619 :    
620 :     =cut
621 :    
622 :     sub ComputeQuery {
623 :     # Get the parameters.
624 :     my ($self, $criterion) = @_;
625 :     # Declare the return variables.
626 :     my ($joins, $filterString, $parms);
627 :     # Return the results.
628 :     return ($joins, $filterString, $parms);
629 :     }
630 :    
631 :     =head3 GetValueData
632 :    
633 :     my $value = $tc->GetValueData($feature);
634 :    
635 :     Return the value data from the specified feature that is relevant to this
636 :     criterion. This method is called when the object cache is empty and the
637 :     value is needed in order to call L</PutExtraColumns> or L</CheckValue>.
638 :    
639 :     =over 4
640 :    
641 :     =item feature
642 :    
643 :     An [[ERDBObjectPm]] describing the current feature.
644 :    
645 :     =item RETURN
646 :    
647 :     Returns a scalar containing the value used to determine whether or not the specified
648 :     feature will match a criterion of this type. The object can be a list reference, a hash
649 :     reference, or a blessed object, so long as the virtual L</PutExtraColumns> and
650 :     L</CheckValue> methods understand it.
651 :    
652 :     =back
653 :    
654 :     =cut
655 :    
656 :     sub GetValueData {
657 :     # Get the parameters.
658 :     my ($self, $feature) = @_;
659 :     # Throw an error.
660 :     Confess("Pure virtual method GetValueData called.");
661 :     }
662 :    
663 :     =head3 CheckValue
664 :    
665 :     my $match = $tc->CheckValue($criterion, $valueData);
666 :    
667 :     Return TRUE if the current feature matches this criterion, else FALSE.
668 :    
669 :     =over 4
670 :    
671 :     =item criterion
672 :    
673 :     Criterion Parameter object describing this criterion's parameters.
674 :    
675 :     =item valueData
676 :    
677 :     Value computed for the current feature by the L</GetValueData> method.
678 :    
679 :     =item RETURN
680 :    
681 :     Returns TRUE if the current feature matches the criterion, else FALSE.
682 :    
683 :     =back
684 :    
685 :     =cut
686 :    
687 :     sub CheckValue {
688 :     # Get the parameters.
689 :     my ($self, $criterion, $valueData) = @_;
690 :     # Declare the return variable.
691 :     my $retVal;
692 :     Confess("Pure virtual method CheckValue called.");
693 :     # Return the result.
694 :     return $retVal;
695 :     }
696 :    
697 :     =head3 colName
698 :    
699 :     my $name = $tc->colName();
700 :    
701 :     Return the column name for this criterion. Normally, the column name is
702 :     the same as the label. In some cases, however, we have criterion types
703 :     that involve built-in columns. For these, this method should be
704 :     overridden so that it returns the built-in column's name.
705 :    
706 :     =cut
707 :    
708 :     sub colName {
709 :     # Get the parameters.
710 :     my ($self) = @_;
711 :     # Return the result.
712 :     return $self->label();
713 :     }
714 :    
715 :     =head3 DownloadType
716 :    
717 :     my $dlType = $tc->DownloadType();
718 :    
719 :     Return the download type of this criterion's data column. This will
720 :     usually be C<list>, C<num>, or C<text>.
721 :    
722 :     =cut
723 :    
724 :     sub DownloadType {
725 :     # Get the parameters.
726 :     my ($self) = @_;
727 :     # Declare the return variable.
728 :     my $retVal;
729 :     Confess("Pure virtual DownloadType called.");
730 :     # Return the result.
731 :     return $retVal;
732 :     }
733 :    
734 :     =head3 CacheValue
735 :    
736 :     my $value = $tc->CacheValue($feature);
737 :    
738 :     Return the cache value for this criterion with respect to the specified
739 :     feature. Normally, this will be an HTML displayable version of the
740 :     appropriate value. If the value is immediately available, it should be
741 :     returned; however, if the value is not available at the current time, a
742 :     runtime-value request should be returned in its place.
743 :    
744 :     =over 4
745 :    
746 :     =item feature
747 :    
748 :     [[ERDBObjectPm]] object containing the data for the current feature.
749 :    
750 :     =item RETURN
751 :    
752 :     Returns the value that should be put in the search result cache file for
753 :     this column.
754 :    
755 :     =back
756 :    
757 :     =cut
758 :    
759 :     sub CacheValue {
760 :     # Get the parameters.
761 :     my ($self, $feature) = @_;
762 :     # Declare the return variable.
763 :     my $retVal;
764 :     Confess("Pure virtual method CacheValue called.");
765 :     # Return the result.
766 :     return $retVal;
767 :     }
768 :    
769 :     =head3 RunTimeValue
770 :    
771 :     my $runTimeValue = $tc->RunTimeValue($runTimeKey);
772 :    
773 :     Return the run-time value for this column using the specified key.
774 :    
775 :     =over 4
776 :    
777 :     =item runTimeKey
778 :    
779 :     Key value placed in the search result cache when the need for the desired
780 :     value was determined during search processing.
781 :    
782 :     =item RETURN
783 :    
784 :     Returns the actual value to be used for the specified column.
785 :    
786 :     =back
787 :    
788 :     =cut
789 :    
790 :     sub RunTimeValue {
791 :     # Get the parameters.
792 :     my ($self, $runTimeKey) = @_;
793 :     # Declare the return variable.
794 :     my $retVal;
795 :     Confess("Pure virtual method RunTimeValue called.");
796 :     # Return the result.
797 :     return $retVal;
798 :     }
799 :    
800 :    
801 :     1;

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3