source: branches/peters_vector/lib/statistics/Fisher.h @ 469

// $Id: Fisher.h 469 2005-12-19 14:58:29Z peter $

#ifndef _theplu_statistics_fisher_
#define _theplu_statistics_fisher_ 

#include <c++_tools/statistics/Score.h>
#include <c++_tools/gslapi/vector.h>

#include <cmath>

namespace theplu {
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=positive_label (a,c)
    /// \f$ value > \f$ value_cutoff() a,b \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 classifier::VectorAbstract& 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::VectorAbstract& value,
                 const classifier::VectorAbstract& 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 and namespace theplu

#endif