source: branches/0.4-stable/yat/classifier/ConsensusInputRanker.h @ 1392

#ifndef _theplu_yat_classifier_consensusinputranker_ 
#define _theplu_yat_classifier_consensusinputranker_ 

// $Id$

/*
  Copyright (C) 2004, 2005 Peter Johansson
  Copyright (C) 2006 Jari Häkkinen, Peter Johansson, Markus Ringnér
  Copyright (C) 2007 Jari Häkkinen, Peter Johansson

  This file is part of the yat library, http://dev.thep.lu.se/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 "InputRanker.h"

#include <vector>

namespace theplu {
namespace yat {
namespace statistics {
  class Score;
  class VectorFunction;
}
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 been 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). A
  /// statistics::VectorFunction is used to boil down these ranks to
  /// one consensus rank, and a ranked list is created by sorting the
  /// data rows with respect to this consensus rank.
  ///
  /// For the time being there are two ways to build a
  /// ConsensusInputRanker. 1) Sending a Sampler and a MatrixLookup to
  /// the add function 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&, const statistics::VectorFunction&);
    
    ///
    /// 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).
    /// 
    void add(const Sampler& sampler, const MatrixLookup&, 
             const statistics::Score& s);
    
    ///
    /// @brief Add a set of InputRankers
    ///
    /// 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).
    /// 
    void add(const Sampler& sampler, const MatrixLookupWeighted& data, 
             const statistics::Score& score);
    
    ///
    /// @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.
    ///
    void add(const InputRanker& ir);
    
    ///
    /// Row with lowest rank (highest score) is ranked as number zero
    /// @return index of row ranked as number \a i
    ///
    size_t id(size_t i) const;
    
    /**
       @return ith InputRanker
    */
    const InputRanker& input_ranker(size_t i) const;

    ///
    /// Row with lowest rank (highest score) is ranked as number zero
    /// @return rank for row \a i
    ///
    size_t rank(size_t i) const;
    
    /**
       \brief \brief reserve memory for internal vector of InputRankers 

       This function is recommended before adding using add(const
       InputRanker&) to avoid re-allocations.
    */
    void reserve(size_t n);


    ///
    /// 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_;
    const statistics::VectorFunction& vec_func_;
  };

}}} // of namespace classifier, yat, and theplu

#endif