/*
 * File:                NullHypothesisEvaluator.java
 * Authors:             Kevin R. Dixon
 * Company:             Sandia National Laboratories
 * Project:             Cognitive Foundry
 *
 * Copyright August 15, 2007, Sandia Corporation.  Under the terms of Contract
 * DE-AC04-94AL85000, there is a non-exclusive license for use of this work by
 * or on behalf of the U.S. Government. Export of this program may require a
 * license from the United States Government. See CopyrightHistory.txt for
 * complete details.
 *
 */

package gov.sandia.cognition.statistics.method;

import gov.sandia.cognition.util.CloneableSerializable;

/**
 * Evaluates the probability that the null-hypothesis is correct.  The null
 * hypothesis is generally taken to be something like "two observed datasets
 * were generated by the same underlying distribution."  In this case,
 * rejecting the null hypothesis is equivalent to saying that two datasets were
 * NOT generated by the same distribution.  That is, with high confidence, we
 * can be sure that the two observed datasets a statistically significantly
 * different.  Social scientists usually reject the null hypothesis when
 * NullHypothesisProbability less than 0.05.
 *
 * @param  <DataType> The type of data to evaluate the null hypothesis for.
 * @author Kevin R. Dixon
 * @since  2.0
 */
public interface NullHypothesisEvaluator<DataType>
    extends CloneableSerializable
{

    /**
     * Computes the probability that two data were generated by
     * the same distribution.  NullHypothesisProbability=1 means that the
     * distributions are likely the same, NullHypothesisProbability=0 means they
     * are likely NOT the same, and NullHypothesisProbability less than 0.05
     * is the standard statistical significance test.  This is the "p-value"
     * that social scientists like to use.
     * 
     * @return Probability that the two data were generated by
     * the same source. A value of NullHypothesisProbability less than 0.05
     * is the standard point at which social scientists say two distributions 
     * were generated by different sources.
     * @param data1 
     * First dataset to consider
     * @param data2 
     * Second dataset to consider
     */    
    public ConfidenceStatistic evaluateNullHypothesis(
        DataType data1,
        DataType data2 );
        
}