source: trunk/yat/normalizer/qQuantileNormalizer.h @ 1718

#ifndef _theplu_yat_normalizer_qquantile_normalizer_
#define _theplu_yat_normalizer_qquantile_normalizer_

/*
  Copyright (C) 2009 Jari Häkkinen

  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 3 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 yat. If not, see <http://www.gnu.org/licenses/>.
*/

#include "yat/utility/Vector.h"

namespace theplu {
namespace yat {
namespace utility {
  class Matrix;
  class VectorBase;
}
namespace normalizer {

  /**
     \brief Perform Q-quantile normalization

     After a Q-quantile normalization each column has approximately
     the same distribution of data (the Q-quantiles are the
     same). Also, within each column the rank of an element is not
     changed.

     There is currently no weighted version of qQuantileNormalizer

     The normalization goes like this
     - Data is not assumed to be sorted.
     - Partition the target data in N parts. N must be 3 larger
       because of requirements from the underlying cspline fit
     - Calculate the arithmetic mean for each part, the mean is
       assigned to the mid point of each part.
     - Do the same for the data to be tranformed (called source
       here).
     - For each part, calculate the difference between the target and
       the source. Now we have N differences d_i with associated rank
       (midpoint of each part).
     - Create a cubic spline fit to this difference vector d. The
       resulting curve is used to recalculate all column values.
       - Use the cubic spline fit for values within the cubic spline
         fit range [midpoint 1st part, midpoint last part].
       - For data outside the cubic spline fit use linear
         extrapolation, i.e., a constant shift. d_first for points
         below fit range, and d_last for points above fit range.

     \since New in yat 0.5
   */
  class qQuantileNormalizer
  {
  public:
    /**
       \brief Documentation please.

       \a Q is the number of parts and must be within \f$ [3,N] \f$
       where \f$ N \f$ is the total number of data points in the
       target. However, if \f$ N \f$ is larger than the number of points
       in the data to be normalized the behaviour of the code is
       undefined. Keep \f$ N \f$ equal to or less than the smallest
       number of data points in the target or each data set to be
       normalized against a ginven target. The lower bound of three is
       due to restrictions in the cspline fit utilized in the
       normalization.
    */
    qQuantileNormalizer(const utility::VectorBase& target, unsigned int Q);

    /**
       \brief perform the Q-quantile normalization.

       It is possible to normalize "in place"; it is permissible for
       \a matrix and \a result to reference the same Matrix.

       \note dimensions of \a matrix and \a result must match.
     */
    void operator()(const utility::Matrix& matrix,
                    utility::Matrix& result) const;

  private:

  /**
     \brief Partition a vector of data into equal sizes.

     The class also calculates the average of each part and assigns
     the average to the mid point of each part. The midpoint is a
     double, i.e., it is not forced to be an integer index.
  */
  class Partitioner
  {
  public:
    /**
       \brief Create the partition and perform required calculations.
    */
    Partitioner(const utility::VectorBase& vec, unsigned int N);

    /**
       \brief Return the averages for each part.

       \return The average vector.
    */
    const utility::Vector& averages(void) const;

    /**
       \brief Return the mid point for each partition.

       \return The index vector.
    */
    const utility::Vector& index(void) const;

    /**
       \return The number of parts.
    */
    size_t size(void) const;

  private:
    utility::Vector average_;
    utility::Vector index_;
  };


    Partitioner target_;
  };

}}} // end of namespace normalizer, yat and thep

#endif