/**
 *   
 *   AgentAcademy - an open source Data Mining framework for
 *   training intelligent agents
 *
 *   Copyright (C)   2001-2003 AA Consortium.
 *
 *   This library is open source software; you can redistribute it 
 *   and/or modify it under the terms of the GNU Lesser General 
 *   Public License as published by the Free Software Foundation;   
 *   either version 2.0 of the License, or (at your option) any later 
 *   version.
 *
 *   This 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 Lesser General Public
 *   License along with this library; if not, write to the Free 
 *   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
 *   MA  02111-1307 USA
 * 
 */

package org.agentacademy.modules.dataminer.classifiers;

/**
 * <p>Title: The Data Miner prototype</p>
 * <p>Description: A prototype for the DataMiner (DM), the Agent Academy (AA) module responsible for performing data mining on the contents of the Agent Use Repository (AUR). The extracted knowledge is to be sent back to the AUR in the form of a PMML document.</p>
 * <p>Copyright: Copyright (c) 2002</p>
 * <p>Company: CERTH</p>
 * @author asymeon
 * @version 0.3
 */

import org.agentacademy.modules.dataminer.core.*;

/**
 * Class implementing a statistical routine needed by J48 to
 * compute its error estimate.
 *
 */
public class Stats {

  /**
   * Computes estimated extra error for given total number of instances
   * and error using normal approximation to binomial distribution
   * (and continuity correction).
   *
   * @param N number of instances
   * @param e observed error
   * @param CF confidence value
   */
  public static double addErrs(double N, double e, float CF){

    // Ignore stupid values for CF
    if (CF > 0.5) {
      System.err.println("WARNING: confidence value for pruning " +
			 " too high. Error estimate not modified.");
      return 0;
    }

    // Check for extreme cases at the low end because the
    // normal approximation won't work
    if (e < 1) {

      // Base case (i.e. e == 0) from documenta Geigy Scientific
      // Tables, 6th edition, page 185
      double base = N * (1 - Math.pow(CF, 1 / N));
      if (e == 0) {
	return base;
      }

      // Use linear interpolation between 0 and 1 like C4.5 does
      return base + e * (addErrs(N, 1, CF) - base);
    }

    // Use linear interpolation at the high end (i.e. between N - 0.5
    // and N) because of the continuity correction
    if (e + 0.5 >= N) {

      // Make sure that we never return anything smaller than zero
      return Math.max(N - e, 0);
    }

    // Get z-score corresponding to CF
    double z = Statistics.normalInverse(1 - CF);

    // Compute upper limit of confidence interval
    double  f = (e + 0.5) / N;
    double r = (f + (z * z) / (2 * N) +
		z * Math.sqrt((f / N) -
			      (f * f / N) +
			      (z * z / (4 * N * N)))) /
      (1 + (z * z) / N);

    return (r * N) - e;
  }
}