FilterChain.h

Go to the documentation of this file.

#ifndef FILTER_CHAIN_H
#define FILTER_CHAIN_H

//--------------------------------------------------------------------
//
// This file is part of PEACE.
// 
// PEACE is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// PEACE is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with PEACE.  If not, see <http://www.gnu.org/licenses/>.
// 
// Miami University makes no representations or warranties about the
// suitability of the software, either express or implied, including
// but not limited to the implied warranties of merchantability,
// fitness for a particular purpose, or non-infringement.  Miami
// University shall not be liable for any damages suffered by licensee
// as a result of using, result of using, modifying or distributing
// this software or its derivatives.
//
// By using or copying this Software, Licensee agrees to abide by the
// intellectual property laws, and all other applicable laws of the
// U.S., and the terms of GNU General Public License (version 3).
//
// Authors:   Dhananjai M. Rao          raodm@muohio.edu
//
//---------------------------------------------------------------------

#include <vector>
#include "Filter.h"
#include "HashMap.h"

/** Class that manages a list of filters.

    <p>This class represents a list of filters that are used to try
    and elimintate entries that could potentially deteriorate the
    quality of clustering generated by PEACE.  The filters are run
    prior to commencement of the core clustering operation.  For
    convenient post-processing analysis the filtered ESTs are gathered
    in suitable "dummy" clusters to be ignored.</p>

    <p>Each filter object in the chain implements a specific type of
    filteration operation and returns an integer indicating the
    cluster to which an EST is to be assigned. If the cluster ID is
    -1, then that indicates that the EST must be subjected to regular
    clustering operations.</p>

    <p>Note that filter processing proceeds in a given order. The
    first filter in the chain is invoked. If that filter returns a
    positive cluster ID then rest of the filters are not invoked. On
    the other hand, if a filter returns -1, then the next filter in
    the chain is invoked. The process continues until all the filters
    have been exhausted.</p>
*/
class FilterChain {
public:
    /** Create the filters in the chain.

        This method must be used to establish the chain of filters.
        This method is typically invoked from the \c main method.
        This method parses the names of the filter specified in the
        parameter \c filterStr and instantiates suitable filters
        via the FilterFactory.

        \param[in] filterStr A string containing the list of
        filters to be created in this chain. This string is
        typically specified by the user as a command line parameter.
        If this parameter is \c NULL, then this method performs no
        specific action.

        \param[in] clusterMaker The top-level cluster maker that has
        been specified by the user. The cluster maker encapsulates the
        EST analyzer object specified by the user. The filters can use
        the clusterMaker to perform any special processing they may
        need.
    */
    static FilterChain*
    setupChain(const char* filterStr, ClusterMaker *clusterMaker);

    /** Main helper method that applies all filters in a distributed
        manner.

        This method is a convinence method that has been introduced
        here to facilitate the process of applying all filters in a
        distributed manner. This method operates as follows:

        <ol>

        <li>First it initializes all the filters. If initialization
        fails then this method immediately exits with an non-zero
        error code.</li>
        
        <li>Next it computes the sub-set of ESTs that this filter is
        expected to operate on and applies the filters to all the ESTs
        within the range it owns.</li>

        <li>It participates in interative broadcast in which it
        receives filter data from other processes (if any) and
        broadcasts its data to others. This process ensures that all
        processes have a consistent view of the entries that have been
        filtered out on other processes.</li>

        <li>Then it finalizes all the filters.</li>
        
        <li>If all the operations were successfully completed, then
        this method returns 0 (zero).</li>
        
        </ol>

        \param[in] clusterMaker The cluster maker to be used for
        merging the filter data received from other processes.
        
        \return This method returns 0 (zero) on success. On errors it
        returns a non-zero error code.
    */
    static int applyFilters(ClusterMaker *clusterMaker);
    
    /** Get a pointer to the instance of the filter chain.
        
        Since this class is a singleton, the constructor is private
        and the only way to obtain an instance of the class is through
        this method.  The filter chain is available only after the
        \c setupChain method (that is invoked from main right after
        command line arguments are validated) has successfully
        completed its operation.  Until such time this method simply
        returns \c NULL.

        \return The process-wide unique pointer to the filter chain.
    */
    static inline FilterChain* getFilterChain() {
        return ptrInstance;
    }
    
    /** Display valid command line arguments for filters in the
        chain.

        This method simply calls the showArguments method on each
        filter in the chain.
        
        \param[out] os The output stream to which the valid command
        line arguments must be written.
    */
    virtual void showArguments(std::ostream& os);

    /** Permits filters in the chain to process command line
        arguments.
        
        This method iterates over the filters that have been added to
        this chain and invokes parseArguments() method on each one of
        them.  This permits each filter in the chain to receive and
        process command line parameters targeted for the filters.
        
        \param[in,out] argc The number of command line arguments
        currently present in argv (the parameter list). This parameter
        is updated when parameters are consumed.
        
        \param[in,out] argv The list of command line arguments to be
        consumed by various filters, if they find parameters intended
        for their use. This parameter is updated when command line
        arguments are consumed by one of the filters.

        \return This method returns \c true if all the filters in the
        chain successfully processed command line arguments.  If an
        incorrect command line argument is received by any one of the
        filters then this method returns \c false to flag an error.
    */
    virtual bool parseArguments(int& argc, char **argv);
    
    /** Initializes all the filters in the chain.
        
        This method iterates over all the filters that have been
        added ot this chain and calls initialize() on each one of
        them.  If any one of the filters are unable to initialize
        correctly, then this method immediately returns an non-zero
        error code.

        \return This method returns zero on success. On errors this
        method returns a non-zero value.
    */
    virtual int initialize();

    /** Finalizes all the filters in the chain.
        
        This method iterates over all the filters that have been added
        ot this chain and calls Filter::finalize() method on each one
        of them. The finalize operation permits the filters to wrap up
        their operation and perform any cleanups.
    */
    virtual void finalize();
    
    /** Add the given filter to the filter chain.
        
        This method permits the filter chain to takes ownership of a
        given filter object by added it to its internal chain.
        
        \note The filter chain takes ownership of the object therefore
        that the filter pointer passed to this method must not be
        deleted by the caller.
        
        \param[in] filter The instance of class Filter that should be
        added to the filter chain.
        
        \return This method returns \c true if the filter was
        successfully added. On errors this method returns \c false.
    */
    virtual bool addFilter(Filter* filter);

    /** Determine whether a given EST passes the filter criterion the
        analyzer should perform core (computationally intensive)
        analysis, according to this filter chain.
        
        This method can be used to compare a given EST with the
        reference EST (set via the call to the setReferenceEST())
        method.
        
        \param[in] estIdx The index (zero based) of the EST with which
        the reference EST is to be compared.
        
        \return This method returns the logical cluster to which the
        given EST must be added since one of the filters flagged it as
        being an EST to be ignored from the main clustering. If the
        EST is to be processed as part of the regular clustering
        process then this method returns -1.
    */
    inline int applyFilters(const int estIdx) {
        int clusterID = -1;
        for (size_t i = 0; (i < chain.size()); i++) {
            if ((clusterID = chain[i]->applyFilter(estIdx)) != -1) {
                // Immediately stop when EST fails a filter clause
                break;
            }
        }
        // Return the logical/dummy cluster to which ESTs must be
        // added.
        return clusterID;
    }

    /** Method to display statistics regarding operation of all the
        filters in this chain

        This method can be used to obtain a dump of the statistics
        gathered regarding the operation of all the filters in this
        chain.  The typical statistic generated by filters
        includes:

        <ul>

        <li>The number of times the filter was called.  More
        specifically this value indicates the number of times the \c
        applyFilter() method was invoked on a given filter.</li>

        <li>The number of ESTs that were permitted to pass through the
        filter.</li>
        
        </ul>

        \param[out] os The output stream to which the statistics
        regarding the filters is to be dumped.

        \param[in] rank The rank of the process for which the
        statistics is being displayed. This value is used to make the
        outputs a bit more informative.
    */
    void printStats(std::ostream& os, const int rank) const;
    
    /** Method to obtain pointer to a given filter object.
        
        This method can be used to obtain a pointer to a specific
        filter class present in this chain.  If the filter does not
        exist then this method returns NULL.

        \note The caller must \b not delete the returned pointer.

        \param[in] name The name associated with a given filter.
    
        \return If the filter was found then this method returns a
        valid (non-NULL) pointer to the filter object. If the filter
        was not found, then this method returns NULL.
    */
    Filter* getFilter(const std::string& name) const;
    
    /** The destructor.

        The destructor frees up all the filters added to this
        filter chain.
    */
    virtual ~FilterChain();
    
protected:
    /** The vector containing a list of filters in the chain.
        
        This vector contains the list of hueristics assocaited with
        this chain.  Filters are added to the list via the
        addFilter() method.  The filters are used by the
        shouldAnalyze() method.
    */
    std::vector<Filter*> chain;
    
private:
    /** The constructor.
        
        This is made private because the filter chain is a singleton,
        and should only be instantiated from the
        FilterChain::getFilterChain() static method.
    */
    FilterChain();
    
    /** The pointer to the singleton instance of this class.
        
        Again, this is made private so that only methods of this class
        can access it. The getFilterChain() method in this class
        must be used to obtain an instance of this class.
    */
    static FilterChain* ptrInstance;

    /** Helper method to compute the start and ending indexes of the
        EST that this process owns.

        This method was introduced to keep the math and logic clutter
        involved in computing the list of owned ESTs out of the
        methods that use the information.  This method returns the
        range, such that: \c startIndex <= \em ownedESTidx < \c
        endIndex.
        
        \note This method must be invoked only after MPI::Intialize()
        has beeen called and the ESTs to be processed have be loaded
        (so that EST::getESTList() returns a valid list of ESTs).

        \param[out] startIndex The starting (zero-based) index value
        of the contiguous range of ESTs that this process owns.

        \param[out] endIndex The ending (zero-based) index value of
        the contiguous range ESTs that this process owns.  The value
        returned in this parameter is \b not included in the range of
        values.

        \note Currently, this method has exact implementation as in
        MSTClusterMaker::getOwnedESTidx. This method has been
        copy-pasted so that filters can operate on their own different
        sub-set of ESTs if they choose. Maybe the method can be
        combined together.
    */
    static void getOwnedESTidx(int& startIndex, int& endIndex);

    /** Helper method to perform all-to-all broadcast operation.

        This method is invoked from the applyFilters() (static method)
        to broadcast the results from filtering out data to all other
        processes.  In addition, this method also receives broadcasts
        from other processes and applies their filtered results to the
        local copy. This process ensures that all the processes in the
        system have a consistent snapshot of the filtered out ESTs.

        \note Possibly this method (which has a loop) can be replaced
        by a single MPI all-to-all broadcast call but at expense of
        increased memory footprint.

        \param[in] clusterMaker The cluster maker to be used for
        merging the filter data received from other processes.
    */
    static void allToAllBroadcast(ClusterMaker *clusterMaker);
    
};

#endif

---