source: trunk/c++_tools/classifier/ConsensusInputRanker.h @ 675

#ifndef _theplu_classifier_consensusinputranker_ 
#define _theplu_classifier_consensusinputranker_ 

// $Id$

/*
  Copyright (C) The authors contributing to this file.

  This file is part of the yat library, http://lev.thep.lu.se/trac/yat

  The yat library 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 2 of the
  License, or (at your option) any later version.

  The yat library 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 this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
  02111-1307, USA.
*/

#include "yat/classifier/InputRanker.h"!

namespace theplu {

  class statistics::Score;

namespace classifier {  

  class IRRetrieve;
  class MatrixLookup;
  class MatrixLookupWeighted;
  class Sampler;

  ///
  /// @brief Robust algorithm to rank rows in a data matrix versus a
  /// target vector. 
  ///
  /// The idea is to create several (different) ranked lists. The list
  /// could be different because they are based upon different
  /// sub-sets of the data, or the different lists could be different
  /// because they have are generated using different criteria. Having
  /// \f$ N \f$ lists means each row in the data matrix has \f$ N \f$
  /// ranks (each corresponding to one list) and a consensus ranked
  /// list is created by sorting the data rows with respect to their
  /// median rank.
  ///
  /// For the time being there are two ways to build a
  /// ConsensusInputRanker. 1) Sending a Sampler and a MatrixLookup to
  /// the constructor will create one ranked list for each of the
  /// partitions defined in the Sampler. 2) You can generate
  /// your ranked list outside, using your favourite method, and
  /// adding it into the ConsensusInputRanker object. This allows
  /// combining different scores and different sub-sets in a more
  /// general way.
  /// 
  class ConsensusInputRanker
  {
  
  public:

    ///
    /// @brief Default constructor
    ///
    /// Truly does nothing but creates a few empty member vectors.
    /// 
    ConsensusInputRanker(const IRRetrieve&);
    
    ///
    /// Iterating through @a sampler creating subsets of @a data, and
    /// for each subset is an InputRanker is created using the @a
    /// score. After creation the data rows are sorted with respect to
    /// the median rank (i.e. update() is called).
    /// 
    ConsensusInputRanker(const Sampler& sampler, const MatrixLookup&, 
                         statistics::Score& s, const IRRetrieve&);
    
    ///
    /// Iterating through @a sampler creating subsets of @a data, and
    /// for each subset is an InputRanker is created using the @a
    /// score. After creation the data rows are sorted with respect to
    /// the median rank (i.e. update() is called).
    /// 
    ConsensusInputRanker(const Sampler& sampler, 
                         const MatrixLookupWeighted& data, 
                         statistics::Score& score, const IRRetrieve&);
    
    ///
    /// @brief add an InputRanker
    ///
    /// @note update() must be called to make the added InputRanker to
    /// influence consensus ids and ranks. If a sequence of
    /// InputRankers are added, update() need to be called only after
    /// the last InputRanker is added.
    ///
    inline void add(const InputRanker& ir) { input_rankers_.push_back(ir); }
    
    ///
    /// Row with lowest rank (highest score) is ranked as number zero
    /// @return index of row ranked as number \a i
    ///
    inline size_t id(const size_t i) const { return id_[i]; }
    
    ///
    /// Row with lowest rank (highest score) is ranked as number zero
    /// @return rank for row \a i
    ///
    inline size_t rank(const size_t i) const { return rank_[i]; }
    
    ///
    /// update ids and ranks
    ///
    void update(void);


  private:

    std::vector<size_t> id_;
    std::vector<InputRanker> input_rankers_;
    std::vector<size_t> rank_;
    const IRRetrieve& retriever_;

  };

}} // of namespace classifier and namespace theplu

#endif