source: trunk/src/NNI.h @ 228

// $Id: NNI.h 228 2005-02-01 14:06:51Z peter $

#ifndef _theplu_cpptools_nni_
#define _theplu_cpptools_nni_ 

#include <iostream>
#include <utility>
#include <vector>

#include "matrix.h"

namespace theplu {
namespace cpptools {

  using namespace std;

  ///
  /// NNI is an abstract base class defining the interface for nearest
  /// neighbour imputation (NNI) algorithms.
  ///
  /// NNI algorithms implemented here is discussed in documents
  /// created in the WeNNI project. This document will be released for
  /// public access, and the necessary information for retrieving that
  /// document will be provided here.
  ///
  /// Short introduction to NNI is that one may want to improve
  /// (correct) uncertain data. Here, the data to be imputed is stored in a
  /// matrix where rows similar to each other are used to adjust
  /// uncertain data. The data matrix is accompanied by a weight
  /// (uncertainty) matrix defining what data is to be considered as
  /// 'certain' and what data is uncertain. The weight matrix can be
  /// binary with 1's indicating that the data does not need
  /// corrections, whereas a 0 means that the data should be replaced
  /// by an imputed value. Naturally, the weight matrix can also be
  /// continuous where values between 0 and 1 defines how certain a
  /// data element is.
  ///
  /// The imputation depends on how similarity of rows of data is
  /// defined and on the number of closest neighbours (here; rows) to
  /// use in the imputation can be set.
  ///
  /// Implementation issues
  ///
  /// The current implementation treats rows where all data are tagged
  /// are completely uncertain, i.e. all weights are zero, by
  /// ignoring these lines in nearest neighbourhood
  /// calculations. Importantly, this type of data are not changed
  /// (imputed) either since there is no close neighbourhood defined
  /// for this data.
  ///
  /// Rows that is completely identical in an imputation algorithm
  /// sense will give problems since the distance between will usually
  /// become zero. This is solved by setting zero distance to a small
  /// number. Identical rows in this context are basically a
  /// comparison between elements with non-zero uncertainty weights
  /// only, and all these elements are equal. Zero weight elements are
  /// not used in the comparison since these are considered as
  /// non/sense values.
  ///
  class NNI
  {
  public:

    ///
    /// Base constructor for the nearest neighbour imputation
    /// algorithms.
    ///
    NNI(const gslapi::matrix& matrix,const gslapi::matrix& weight,
        const u_int neighbours);

    virtual ~NNI(void) {};

    ///
    /// Function doing the imputation. @return number of rows not imputed
    ///
    virtual size_t estimate(void)=0;

    ///
    /// @return A const reference to the modified data.
    ///
    const gslapi::matrix& imputed_data(void) const { return imputed_data_; }

    ///
    /// @return indices of rows in data matrix not imputed
    ///
    inline vector<size_t> not_imputed(void) const { return not_imputed_; }

  protected:
    vector<pair<u_int,double> > calculate_distances(const u_int) const;
    vector<u_int> nearest_neighbours(const u_int,
                                     const vector<pair<u_int,double> >&) const;

    const gslapi::matrix& data_;
    gslapi::matrix imputed_data_;
    u_int neighbours_;
    vector<u_int> not_imputed_;
    const gslapi::matrix& weight_;
  };

}} // of namespace cpptools and namespace theplu

#endif