00001 #ifndef FILTER_H 00002 #define FILTER_H 00003 00004 //-------------------------------------------------------------------- 00005 // 00006 // This file is part of PEACE. 00007 // 00008 // PEACE is free software: you can redistribute it and/or modify it 00009 // under the terms of the GNU General Public License as published by 00010 // the Free Software Foundation, either version 3 of the License, or 00011 // (at your option) any later version. 00012 // 00013 // PEACE is distributed in the hope that it will be useful, but 00014 // WITHOUT ANY WARRANTY; without even the implied warranty of 00015 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00016 // General Public License for more details. 00017 // 00018 // You should have received a copy of the GNU General Public License 00019 // along with PEACE. If not, see <http://www.gnu.org/licenses/>. 00020 // 00021 // Miami University makes no representations or warranties about the 00022 // suitability of the software, either express or implied, including 00023 // but not limited to the implied warranties of merchantability, 00024 // fitness for a particular purpose, or non-infringement. Miami 00025 // University shall not be liable for any damages suffered by licensee 00026 // as a result of using, result of using, modifying or distributing 00027 // this software or its derivatives. 00028 // 00029 // By using or copying this Software, Licensee agrees to abide by the 00030 // intellectual property laws, and all other applicable laws of the 00031 // U.S., and the terms of GNU General Public License (version 3). 00032 // 00033 // Authors: Dhananjai M. Rao raodm@muohio.edu 00034 // 00035 //--------------------------------------------------------------------- 00036 00037 #include "arg_parser.h" 00038 #include "HashMap.h" 00039 00040 #include <vector> 00041 00042 // Forward declarations to keep compiler fast and happy 00043 class ClusterMaker; 00044 00045 /** \def FilteredESTList 00046 00047 \brief Typedef for HashMap<int, std::vector<int> > FilteredESTList; 00048 00049 This typedef is a convenience definition to define a hash map 00050 tracks the set of entries that were filetered out by this 00051 filter. The key to the hash map is the cluster ID to which 00052 filtered ESTs were added. The value in the hash map is a vector 00053 that contains the index of the ESTs that were added to the 00054 cluster. 00055 */ 00056 typedef HashMap<int, std::vector<int> > FilteredESTList; 00057 00058 /** The base class of all filters. 00059 00060 <p>This class must be the base class of all filters in the 00061 system. This class provides some default functionality that can be 00062 readily used by the filters. This class enables the FilterChain to 00063 manage a list of filters and dispatch method calls to various 00064 filters.</p> 00065 00066 <p>A set of filters (stored in the FilterChain class) are run on 00067 all entries in a FASTA file prior to commencement of the core 00068 clustering operation. The filters perform various validation 00069 operations to ensure ESTs are good prior to clustering. Filtering 00070 ensures that the overall quality of clustering provided by PEACE 00071 is good.</p> 00072 00073 <p>Each filter object in the chain implements a specific type of 00074 filteration operation and ultimately returns an integer indicating 00075 the cluster to which an EST is to be assigned. If the cluster ID 00076 is -1, then that indicates that the EST must be subjected to 00077 regular clustering operations.</p> 00078 */ 00079 class Filter { 00080 public: 00081 /** Display valid command line arguments for this filter. 00082 00083 This method must be used to display all valid command line 00084 options that are supported by this filter. Note that derived 00085 classes may override this method to display additional command 00086 line options that are applicable to it. This method is 00087 typically used in the main() method when displaying usage 00088 information. 00089 00090 \note Derived filter classes <b>must</b> override this 00091 method to display help for their custom command line 00092 arguments. When this method is overridden don't forget to 00093 call the corresponding base class implementation to display 00094 common options. 00095 00096 \param[out] os The output stream to which the valid command 00097 line arguments must be written. 00098 */ 00099 virtual void showArguments(std::ostream& os) = 0; 00100 00101 /** Process command line arguments. 00102 00103 This method is used to process command line arguments specific 00104 to this filter. This method is typically used from the main 00105 method just after the filter has been instantiated. This 00106 method consumes all valid command line arguments. If the 00107 command line arguments were valid and successfully processed, 00108 then this method returns \c true. 00109 00110 \note Derived filter classes <b>must</b> override this method 00111 to process any command line arguments that are custom to their 00112 operation. When this method is overridden don't forget to 00113 call the corresponding base class implementation to display 00114 common options. 00115 00116 \param[in,out] argc The number of command line arguments to be 00117 processed. This value is updated when valid command line 00118 arguments are consumed by the filter. 00119 00120 \param[in,out] argv The array of command line arguments. The 00121 number of entries in this array are modified and updated when 00122 valid arguments are consumed by the filter. 00123 00124 \return This method returns \c true if the command line 00125 arguments were successfully processed. Otherwise this method 00126 returns \c false. 00127 */ 00128 virtual bool parseArguments(int& argc, char **argv) = 0; 00129 00130 /** Method to begin filter analysis (if any). 00131 00132 This method is invoked just before commencement of filtration. 00133 This method typically loads additional information that may be 00134 necessary for a given filter. In addition, it may perform any 00135 pre-processing as the case may be. 00136 00137 \note Derived classes must override this method. 00138 00139 \return If the initialization process was sucessful, then this 00140 method returns 0. Otherwise this method returns with a 00141 non-zero error code. 00142 */ 00143 virtual int initialize() = 0; 00144 00145 /** Method to indicate completion of filter analysis. 00146 00147 This method is invoked after all the filteration operations 00148 have been successfully completed. This method typically 00149 performs any clean up operations that may be necessary. 00150 00151 \note Derived classes must override this method. 00152 */ 00153 virtual void finalize() = 0; 00154 00155 /** Add cluster ID and indexes of ESTs filtered by this filter to 00156 a list. 00157 00158 This method is used to accumulate the set of ESTs that were 00159 filtered out by this filter into a single superList. The super 00160 list is then broadcasted to other processes for their 00161 reference. The data from this filter is to be added to the 00162 superList in the following format (to ease broadcasting to 00163 other processes): 00164 00165 <ol> 00166 00167 <li>First the clusterID to which the ESTs were added must be 00168 appended to the superList.</li> 00169 00170 <li>Next, the number of ESTs that were filtered out by this 00171 filter must be appended to the superList.</li> 00172 00173 <li>Finally, the indexes of the ESTs that were filtered out by 00174 this filter must be appended to the superList.</li> 00175 00176 </ol> 00177 00178 \param[out] superList The vector to which the filter data is 00179 to be added. 00180 */ 00181 void addFilterData(std::vector<int>& superList) const; 00182 00183 /** Helper method to process filter data from another process. 00184 00185 This is a helper method to process a given list of entries 00186 (that was built by the addFilterData() method) obtained from 00187 another process. This list can contain entries from multiple 00188 filters. This method method processes the list of entries and 00189 adds the indicated ESTs to corresponding clusters on local 00190 processes. This ensures that filters that were independently 00191 applied on different parallel processes are consistently 00192 reflected on all processes participating in the clustering 00193 process. 00194 00195 \note This method is present here so that the interface of 00196 this class is symmeetric in the sense that the list generated 00197 by the addFilterData method is also processed by this method. 00198 00199 \note The method is also static because it processes lists 00200 from multiple filters and not just one. This is more of 00201 "purity" of API and its significance rather than anything 00202 else. 00203 00204 \param[in] superList The super list to be processed by this 00205 method. 00206 00207 \param[in] clusterMaker The cluster maker object that is being 00208 used for analysis. 00209 */ 00210 static void processFilterData(const std::vector<int>& superList, 00211 ClusterMaker *clusterMaker); 00212 00213 /** Determine if the given EST passes this filter condition. 00214 00215 This method can be used to determine if a given EST passes 00216 this filter and if it must be subjected to the core clustering 00217 operations. 00218 00219 \param[in] otherEST The index (zero based) of the EST that 00220 must be subject to which the reference EST is to be compared. 00221 00222 \return This method returns -1 if the est must be subject to 00223 further filteration or core EST analyis and clustering. If 00224 the specified est is to be filtered out, then this method 00225 returns a non-zero integer value. This value is used to place 00226 the EST into an artifically created cluster to help users 00227 identify such clusters. 00228 */ 00229 int applyFilter(const int otherEST); 00230 00231 /** Obtain human-readable name for this filter. 00232 00233 This method must be used to obtain the human readable name set 00234 for this filter. This method essentially returns the value 00235 set when this filter class was instantiated. 00236 00237 \return A human readable name associated with this filter. 00238 */ 00239 const std::string& getName() const { return filterName; } 00240 00241 /** The destructor. 00242 00243 The destructor for the filter. 00244 */ 00245 virtual ~Filter(); 00246 00247 /** Method to display statistics regarding operation of this filter. 00248 00249 This method can be used to obtain a dump of the statistics 00250 gathered regarding the operation of this filter. The 00251 typical statistic generated by filters includes: 00252 00253 <ul> 00254 00255 <li>The number of times the filter was called. More 00256 specifically this value indicates the number of times the \c 00257 applyFilter() method was invoked.</li> 00258 00259 <li>The number of successful matches reported by this filter. 00260 This number indirectly indicates the number of times other 00261 filters were invoked.</li> 00262 00263 </ul> 00264 00265 \note Derived filter classes may override this method to 00266 display additional statistics. However, the additional 00267 information must be displayed after the base class method has 00268 completed its task. 00269 00270 \param[out] os The output stream to which the statistics 00271 regarding the filter is to be dumped. 00272 */ 00273 virtual void printStats(std::ostream& os) const; 00274 00275 /** Method to obtain the count of times this filter was run. 00276 00277 \return The number of times this filter was called. 00278 */ 00279 inline int getRunCount() { 00280 return runCount; 00281 } 00282 00283 /** Method to obtain the count of times this filter rejected (or 00284 filtered-out) an EST. 00285 00286 \return The number of times calls to this filter rejected (or 00287 filtered-out) an EST. 00288 */ 00289 inline int getFilterCount() { 00290 return filterCount; 00291 } 00292 00293 protected: 00294 /** The default constructor. 00295 00296 The constructor has been made protected to ensure that this 00297 class is never directly instantiated. Instead one of the 00298 derived Filter classes must be instantiated via the 00299 FilterFactory API methods. 00300 00301 \param[in] filterName The human readable name for this filter. 00302 This name is used when generating errors, warnings, and other 00303 output messages for this filter. 00304 00305 \param[in] clusterMaker The cluster maker class that is being 00306 used for analysis. This class can be used by this filter for 00307 performing specific operations. 00308 */ 00309 Filter(const std::string& filterName, ClusterMaker *clusterMaker); 00310 00311 /** Apply filter rules to determine if this EST should be filtered 00312 out. 00313 00314 This method is invoked from the applyFilter() method to 00315 perform the actual filtering. The filtering is performed 00316 on the given EST. 00317 00318 \note Derived filter classes must override this method and 00319 provide a proper implementation. 00320 00321 \param[in] estIndex The index (zero based) of the EST to which 00322 the filter rules are to be applied. 00323 00324 \return This method returns -1 if the est must be subject to 00325 further filteration or core EST analyis and clustering. If 00326 the specified est is to be filtered out, then this method 00327 returns a non-zero integer value. This value is used to place 00328 the EST into an artifically created cluster to help users 00329 identify such clusters. 00330 */ 00331 virtual int runFilter(const int estIndex) = 0; 00332 00333 /** The name of this filter. 00334 00335 This instance variable contains the human recognizable name 00336 for this filter. This value is set when the filter is 00337 instantiated (in the constructor) and is never changed during 00338 the life time of this filter. This information is used when 00339 generating errors, warnings, and other output messages. 00340 */ 00341 const std::string filterName; 00342 00343 /** The cluster maker set for this filter. 00344 00345 This instance variable is initialized to refer to the 00346 top-level cluster maker class to be used by this filter for 00347 any operations that may be necessary. Note that this pointer 00348 cannot be change after it is set in the constructor. 00349 */ 00350 ClusterMaker* const clusterMaker; 00351 00352 private: 00353 /** Variable to track the number of times this filter was run. 00354 00355 This instance variable is used to track the number of times 00356 this filter was run. This variable is initialized to zero in 00357 the constructor. It is incremented each time the 00358 applyFilter() method is invoked to run the the filter. 00359 */ 00360 int runCount; 00361 00362 /** Variable to track the number of times this filter filtered out 00363 an EST. 00364 00365 This instance vairable tracks the number of times the filter 00366 filtered out an EST. This value is incremented in the \c 00367 applyFilter() method each time the runFilter() method returns 00368 a \c non -1 value. 00369 */ 00370 int filterCount; 00371 00372 /** The list of ESTs filtered out by this filter. 00373 00374 This instance variable is used to track the set of ESTs that 00375 were filtered out by this filter. A single filter can filter 00376 out ESTs and add them to different dummy 00377 clusters. Consequently a hash map is used to track the 00378 information. The key to the hash map is the cluster ID to 00379 which filtered ESTs were added. The value in the hash map is a 00380 vector that contains the index of the ESTs that were added to 00381 the cluster. Entries to the hash map are added by the 00382 applyFilter method. 00383 */ 00384 FilteredESTList filteredESTList; 00385 00386 /** A dummy operator= 00387 00388 The operator=() is supressed for this class as it has constant 00389 members whose value is set when the object is created. These 00390 values cannot be changed during the lifetime of this object. 00391 00392 \param[in] src The source object from where data is to be 00393 copied. Currently this value is ignored. 00394 00395 \return Reference to this. 00396 */ 00397 Filter& operator=(const Filter& src); 00398 }; 00399 00400 #endif
1.6.1