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

#ifndef _theplu_yat_statistics_fisher_
#define _theplu_yat_statistics_fisher_

// $Id: Fisher.h 3561 2017-01-04 00:55:10Z peter $

/*
  Copyright (C) 2004, 2005 Peter Johansson
  Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
  Copyright (C) 2009, 2011, 2013, 2014, 2015 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 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/deprecate.h>

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 setup. See
     e.g. Barnard's test for alternative.
  */

  class Fisher
  {

  public:
    ///
    /// Default Constructor.
    ///
    /// \param yates if true Yates's correction is used for
    /// chi-squared calculation
    ///
    /// \since Constructor with argument was introduced in yat 0.13
    ///
    Fisher(bool yates=false);

    ///
    /// Destructor
    ///
    virtual ~Fisher(void);


    /**
       The Chi2 score is calculated as \f$ \sum
       \frac{(O_i-E_i)^2}{E_i}\f$ where \a E is expected value and \a
       O is observed value.

       If indicated in constructor, Yates's correction is used, i.e.,
       Chi2 is calculated as \f$ \frac{(|O_i-E_i|-0.5)^2}{E_i} \f$


       \see expected(double&, double&, double&, double&)

       \return Chi2 score
    */
    double Chi2(void) const;

    /**
       Calculates the expected values under the null hypothesis.
       \f$ a' = \frac{(a+c)(a+b)}{a+b+c+d} \f$,
       \f$ b' = \frac{(a+b)(b+d)}{a+b+c+d} \f$,
       \f$ c' = \frac{(a+c)(c+d)}{a+b+c+d} \f$,
       \f$ d' = \frac{(b+d)(c+d)}{a+b+c+d} \f$,
    */
    void expected(double& a, double& b, double& c, double& d) const;

    ///
    /// If all elements in table is at least minimum_size(), a Chi2
    /// approximation is used for p-value calculation.
    ///
    /// @return reference to minimum_size
    ///
    unsigned int& minimum_size(void);

    ///
    /// If all elements in table is at least minimum_size(), a Chi2
    /// approximation is used for p-value calculation.
    ///
    /// @return const reference to minimum_size
    ///
    const unsigned int& minimum_size(void) const;

    /**
       Calculates probability to get oddsratio (or smaller).

       If all elements in table is at least minimum_size(), a Chi2
       approximation is used.

       \since New in yat 0.11
     */
    double p_left(void) const;

    /**
       Calculates probability to get oddsratio (or greater).

       If all elements in table is at least minimum_size(), a Chi2
       approximation is used.

       \since New in yat 0.11
     */
    double p_right(void) const;

    /**
       If all elements in table is at least minimum_size(), a Chi2
       approximation is used.

       Otherwise a two-sided p-value is calculated using the
       hypergeometric distribution
       \f$ \sum_k P(k) \f$ where summation runs over \a k such that
       \f$ P(k) \le P(a) \f$.

       \return two-sided p-value
    */
    double p_value(void) const;

    ///
    /// One-sided p-value is probability to get larger (or equal) oddsratio.
    ///
    /// If all elements in table is at least minimum_size(), a Chi2
    /// approximation is used.
    ///
    /// @return One-sided p-value
    ///
    /// \deprecated Provided for backward compatibility with the 0.10
    /// API. Use p_right() instead.
    ///
    double p_value_one_sided() const YAT_DEPRECATE;

    /**
       Function calculating odds ratio from 2x2 table
       \f[ \begin{tabular}{|c|c|}
       \hline a&b \tabularnewline \hline c&d \tabularnewline \hline
       \end{tabular} \f] as \f$ \frac{ad}{bc} \f$

       Object will remember the values of \a a, \a b, \a c, and \a d.

       @return odds ratio.

       @throw If table is invalid a runtime_error is thrown. A table
       is invalid if a row or column sum is zero.
    */
    double oddsratio(const unsigned int a, const unsigned int b,
                     const unsigned int c, const unsigned int d);

    /**
       \return oddsratio loaded via oddsratio(4)

       \since New in yat 0.8
     */
    double oddsratio(void) const;

  private:
    bool calculate_p_exact(void) const;

    // two-sided
    double p_value_approximative(void) const;
    // two-sided
    double p_value_exact(void) const;
    // calculate two-sided p-value to get k (or fewer) wins when
    // drawing t samples out of of a population of n1 wins and n2 losses
    double p_value_exact(unsigned int k, unsigned int n1, unsigned int n2,
                         unsigned int t) const;

    double lower_tail(unsigned int k, unsigned int n1, unsigned int n2,
                      unsigned int t) const;

    // return P(X=k+1) / P(X=k)
    double hypergeometric_ratio(unsigned int k, unsigned int n1,
                                unsigned int n2, unsigned int t) const;
    double choose_ratio(unsigned int n, unsigned int k) const;

    double p_left_exact(void) const;
    double p_right_exact(void) const;

    double yates(unsigned int o, double e) const;

    unsigned int a_;
    unsigned int b_;
    unsigned int c_;
    unsigned int d_;
    unsigned int minimum_size_;
    double oddsratio_;
    bool yates_;
  };

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

#endif