This object manages the filtering of features for a single genome. The client passes in a SearchHelper object and a genome ID, and the constructor returns a new object of this type. The Fetch method can then be used to extract the features one at a time.
The static FilterRows method generates the form fields for the filter as table rows.
A form can only have one feature filter! If this proves to be a problem, it can be repaired, but it will require a few days of work.
This object uses the following fields.
Name of the subsystem to filter on. If subsystem filtering is off, contains a null string.
Currently-active database query.
Reference to a hash that contains data about the current query algorithm.
Reference to a hash that remembers the IDs of features that have already been processed.
Including a feature filter in a form adds the following form fields to a search.
The name of a subsystem or (all). If a subsystem name is specified, then only
features having a role in that subsystem are included.
Search expression. This is essentially a space-delimited list of words with the following optional operators applied.
+: A leading plus sign indicates that this word must be present in every row returned.
-: A leading minus sign indicates that this word must not be present in any row returned.
Note that if every search term has a leading minus sign, nothing will match. This is an
artifact of the search algorithm.
(no operator): A + is assumed for words with no other leading operator.
> <: These two operators are used to change a word's contribution to the relevance value
that is assigned to a row. The > operator increases the contribution and the <
operator decreases it. Using either of these operators makes the word optional.
~: A leading tilde acts as a negation operator, causing the word's contribution to the row
relevance to be negative. It's useful for marking noise words. A row that contains such a
word is rated lower than others, but is not excluded altogether, as it would be with the -
operator.
*: An asterisk is the truncation operator. Unlike the other operators, it should be appended to the word.
" A phrase that is enclosed within double quote characters matches only rows that contain the phrase
literally, as it was typed.
In addition to the search filtering parameters, there are also the following special options for modifying the display of the search results. If only these options are desired, call the SpecialOptions method instead of FilterRows.
If specified, the aliases of each feature are displayed.
If specified, the subsystems in which each feature participates is displayed.
If specified, the results are sorted by functional rolw.
The feature filter attempts to find features in the most optimal way possible. If a subsystem is specified, then we will start from the HasRoleInSubsystem relationship, taking advantage of the fact that all features for a given genome are clustered together in the index. If no subsystem is specified, then we will start from HasFeature, filtering by genome. If no subsystem or genome is specified, we start from Feature. At some future point we may need to be even more sophisticated than that.
my $fquery = FeatureQuery->new($shelp, $genomeID);
Construct a FeatureQuery object for processing the features in a particular genome relevant to a search.
Search helper object containing the parameter values for the search.
Genome whose features are to be found and filtered. If omitted, then the features for all genomes will be returned.
my $featureData = $fquery->Fetch();
Return the data for the next feature. The object returned will be a ERDBObject for
the desired feature plus any useful ancillary data. If there are no more features
it will return undef.
my @rows = FeatureQuery::FilterRows($shelp, @subset);
Generate the HTML table rows for filtering features on a genome-by-genome basis.
Search helper object that is generating the search form.
List of the rows to be included: words for the keyword search box,
subsys for the subsystem selector, and options for the option
row.
Returns a list of fully-formatted HTML table rows. These table rows can be put into the main table of the search form.
my @htmlLines = FeatureQuery::SpecialOptions($shelp);
Display the special options rows for a feature search. This method includes check boxes useful for any feature search regardless of whether or not it includes full-blown feature filtering. Included are options for sorting the results and for displaying additional information.
For the special options to work, the search helper will need to call the static AdditionalColumns and SortKey methods while setting up the searches. If you are using the default search helper methods, this will happen automatically.
Search helper object for the current search. This is used to find the CGI object.
Returns a list of HTML table rows containing the check boxes to control the display of the search results.
my @cols = FeatureQuery::AdditionalColumns($shelp);
Return any additional columns that should be included in the feature display. The columns returned will be standard columns, not extra columns particular to the search. The idea is that if the we want to give the user options for displaying more columns, the options will be communicated through the feature query section of the form, and the column names will be returned here.
Search helper object for the current search.
Returns a list of feature column names. The columns will appear to the left of any extra columns.
my $key = $fquery->SortKey($shelp, $group);
Return the sort key for the current feature. The sort key is normally a thing created from the group name, but it can be overridden by options on the form generated by the feature query. For example, if a keyword search is being used, the search relevance takes precedence over everything but whether or not the feature is an NMPDR feature. If the user asked to sort the features by functional assignment, that would take precedence as well.
Current search helper object.
Name of the NMPDR group containing this feature.
Returns a string that can be used to sort the specified feature into the correct position.
my $flag = FeatureQuery::Valid($shelp);
Validate the filtering parameters for the current search request. Note that in this version, no validation is necessary, but that may not always be the case.
Search helper object containing the form data.
Returns TRUE if the filtering parameters are valid, and FALSE if they're invalid. In the latter case, SetMessage will have been called on the search helper object to communicate the error message.
my $flag = $fquery->CheckSubsystem($featureData);
Determine whether or not the specified feature is in the correct subsystem. This method will return TRUE if we pass the test, else FALSE.
ERDBObject for the feature to check.
Returns TRUE if the feature is in the correct subsystem, else FALSE.
my $okFlag = $fquery->CheckFeature($feature);
Determine whether or not the specified feature fulfills all the requirements of this filter.
Feature to examine. May be a ERDBObject for the feature, a feature ID, or omitted. If omitted, then the current feature is used.
Returns TRUE if the feature satisfies all our conditions, else FALSE.
my $query = _GetNextQuery($qData);
Get the next query for retrieving features. This method should only be used internally.
Currently, we have a single query. This may not always be the case, in which instance this method will need to return multiple queries in sequence.
Current query data object.
Returns a DBQuery object for the current feature query, or undef if there are no
more queries to make.