source: trunk/yat/statistics/Fisher.h @ 683

#ifndef _theplu_yat_statistics_fisher_
#define _theplu_yat_statistics_fisher_ 

// $Id: Fisher.h 683 2006-10-11 22:20:36Z jari $

/*
  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 "Score.h"
#include "yat/utility/vector.h"

#include <cmath>

namespace theplu {
namespace yat {
namespace statistics {  
  /**
     @brief Fisher's exact test.   

     Fisher's Exact test is a procedure that you can use for data
     in a two by two contingency table: \f[ \begin{tabular}{|c|c|}
     \hline a&b \tabularnewline \hline c&d \tabularnewline \hline
     \end{tabular} \f] Fisher's Exact Test is based on exact
     probabilities from a specific distribution (the hypergeometric
     distribution). There's really no lower bound on the amount of
     data that is needed for Fisher's Exact Test. You do have to
     have at least one data value in each row and one data value in
     each column. If an entire row or column is zero, then you
     don't really have a 2 by 2 table. But you can use Fisher's
     Exact Test when one of the cells in your table has a zero in
     it. Fisher's Exact Test is also very useful for highly
     imbalanced tables. If one or two of the cells in a two by two
     table have numbers in the thousands and one or two of the
     other cells has numbers less than 5, you can still use
     Fisher's Exact Test. For very large tables (where all four
     entries in the two by two table are large), your computer may
     take too much time to compute Fisher's Exact Test. In these
     situations, though, you might as well use the Chi-square test
     because a large sample approximation (that the Chi-square test
     relies on) is very reasonable. If all elements are larger than
     10 a Chi-square test is reasonable to use. 
     
     @note The statistica assumes that each column and row sum,
     respectively, are fixed. Just because you have a 2x2 table, this
     assumtion does not necessarily match you experimental upset. See
     e.g. Barnard's test for alternative.
  */
  
  class Fisher : public Score
  {
  
  public:
    ///
    /// Default Constructor.
    ///
    Fisher(bool absolute=true);

    ///
    /// Destructor 
    ///
    virtual ~Fisher(void) {};
         
    
    ///
    /// @return Chi2 score
    ///
    double Chi2(void) const;

    ///
    /// Cutoff sets the limit whether a value should go into the left
    /// or the right row. @see score
    ///
    /// @return reference to cutoff for row
    /// 
    inline double& value_cutoff(void) { return value_cutoff_; }

    ///
    /// Calculates the expected values under the null hypothesis.
    /// a' = (a+c)(a+b)/(a+b+c+d)
    ///
    void expected(double& a, double& b, double& c, double& d) const;

    ///
    /// minimum_size is the threshold for when the p-value calculation
    /// is performed using a Chi2 approximation.
    ///
    /// @return reference to minimum_size
    ///
    inline u_int& minimum_size(void){ return minimum_size_; }  

    ///
    /// If absolute, the p-value is the two-sided p-value. If all
    /// elements in table is at least minimum_size, a Chi2
    /// approximation is used.
    ///
    /// @return p-value
    ///
    /// @note in weighted case, approximation Chi2 is always used.
    ///
    double p_value() const;
    
    ///
    /// Function calculating score from 2x2 table for which the
    /// elements are calculated as follows \n
    /// target.binary(i) sample i in group a or c otherwise in b or d
    /// \f$ value(i) > \f$ value_cutoff() sample i in group a or b
    /// otherwise c or d\n
    ///
    /// @return odds ratio. If absolute_ is true and odds ratio is
    /// less than unity 1 divided by odds ratio is returned
    ///
    double score(const classifier::Target& target, 
                 const utility::vector& value);

    ///
    /// Weighted version of score. Each element in 2x2 table is
    /// calculated as \f$ \sum w_i \f$, so when each weight is
    /// unitary the same table is created as in the unweighted version
    ///
    /// @return odds ratio
    ///
    /// @see score
    ///
    double score(const classifier::Target& target, 
                 const classifier::DataLookupWeighted1D& value);


    ///
    /// Weighted version of score. Each element in 2x2 table is
    /// calculated as \f$ \sum w_i \f$, so when each weight is
    /// unitary the same table is created as in the unweighted version
    ///
    /// @return odds ratio
    ///
    /// @see score
    ///
    double score(const classifier::Target& target, 
                 const utility::vector& value,
                 const utility::vector& weight); 

    ///
    /// \f$ \frac{ad}{bc} \f$
    ///
    /// @return odds ratio. If absolute_ is true and odds ratio is
    /// less than unity, 1 divided by odds ratio is returned
    ///
    double score(const u_int a, const u_int b, 
                 const u_int c, const u_int d); 

         
  private:
    double oddsratio(const double a, const double b, 
                     const double c, const double d);

    // two-sided
    double p_value_approximative(void) const;
    //two-sided
    double p_value_exact(void) const;

    double a_;
    double b_;
    double c_;
    double d_;
    u_int minimum_size_;
    double oddsratio_;
    double value_cutoff_;
  };

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

#endif