Cognitive Foundry 3.3.0.

Author: jbasilico

ChangeLog.txt

@@ -2,6 +2,50 @@ This file contains the change log for the Cognitive Foundry.
 
 Changes since last release:
 
+Release 3.3.0 (2011-06-22):
+  * Common Core:
+    * Added LogMath and LogNumber as utilities for computation involving numbers
+      represented in log-space.
+    * Added MutableInteger and MutableLong, which are like Integer and Long but
+      with a mutable value, similar to MutableDouble.
+    * UnivariateSummaryStatistics added.
+    * Added DefaultIndentifiedValue.
+  * Learning Core:
+    * VectorNaiveBayesCategorizer: evaluateWithDiscriminant now properly
+      normalizes the discriminant, which improves results for things like AUC.
+    * PartitionalClusterer: Fixed corner-case bug.
+    * Added confidence-weighted online learners based on variance, standard
+      deviation, and AROW. They produce ConfidenceWeightedBinaryCategorizer
+      objects with either diagonal or full covariance matrices.
+    * Added balanced versions of bagging and IVoting in
+      CategoryBalancedBaggingLearner and CategoryBalancedIVotingLearner.
+    * Added online learners based on ROMMA, AROMMA, Ballseptron, Ramp-loss 
+      Passive Aggressive Perceptron, Shifting Perceptron, Forgetron,
+      Projectron, Randomized Budget Perceptron, and Stoptron.
+    * Added KernelizableBinaryCategorizerOnlineLearner interface for an online
+      linear binary categorizer that can also be used with a kernel. Also
+      provided abstract class AbstractKernelizableBinaryCategorizerOnlineLearner
+      and AbstractLinearCombinationOnlineLearner for common functionality.
+    * Moved KernelPerceptron and KernelAdatron to the new
+      learning.perceptron.kernel package.
+    * Added KernelUtil utility class for dealing with kernels and kernel
+      binary categorizers.
+    * Refactored statistics to remove getMean() from Distribution due to
+      some distributions not having a meaningful mean and confusion for what
+      the mean meant in some classes.
+    * Classes and interfaces interfaces named *Scalar* renamed to *Univariate*
+      for clarity.
+    * Added getTestStatistic() method to ConfidenceStatistic interface and
+      implemented in existing classes.
+    * Added support for multiple comparisons tests, including Bonferroni,
+      Holm, Nemenyi, Shaffer, Sidak, and Tukey-Kramer and updated
+      AnalysisOfVarianceOneWay (ANOVA) and FriedmanConfidence.
+    * Added multiple-comparisons experiment classes BlockExperimentComparison
+      and MultipleComparisonExperiment
+   * Text Core:
+     * Renamed ProbabilisticLatentSemanticAnalysis.Transform to
+       ProbabilisticLatentSemanticAnalysis.Result for consistency.
+
 Release 3.2.0 (2011-05-19):
  * Upgraded to mtj-9.9.14 and added the netlib-java-0.9.3 library, which MTJ
    now depends on.

Components/CommonCore/Source/gov/sandia/cognition/math/LogMath.java

@@ -0,0 +1,192 @@
+/*
+ * File:                LogMath.java
+ * Authors:             Justin Basilico
+ * Company:             Sandia National Laboratories
+ * Project:             Cognitive Foundry
+ * 
+ * Copyright June 13, 2011, 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.math;
+
+/**
+ * A utility class for doing math with numbers represented as logarithms. Thus,
+ * the number x is instead represented as log(x). This can be useful when
+ * doing computation involving many products, such as with probabilities.
+ * 
+ * @author  Justin Basilico
+ * @since   3.3.0
+ */
+public class LogMath
+{
+
+    /** The natural logarithm of 0 (log(0)), which is negative infinity. */
+    public static final double LOG_0 = Double.NEGATIVE_INFINITY;
+
+    /** The natural logarithm of 1 (log(1)), which is 0. */
+    public static final double LOG_1 = 0.0;
+
+    /** The natural logarithm of 2 (log(2)). */
+    public static final double LOG_2 = Math.log(2.0);
+
+    /** The natural logarithm of 10 (log(10)). */
+    public static final double LOG_10 = Math.log(10.0);
+
+    /**
+     * Converts a number to its log-domain representation (log(x)). Negative
+     * values will result in NaN.
+     *
+     * @param   x
+     *      The number. Should not be negative.
+     * @return
+     *      The logarithm of x (log(x)).
+     */
+    public static double toLog(
+        final double x)
+    {
+        return Math.log(x);
+    }
+
+    /**
+     * Converts a number from log-domain representation (x = exp(logX)).
+     *
+     * @param   logX
+     *      The log-domain representation of the number x (log(x)).
+     * @return
+     *      The value of x, which is exp(logX) = exp(log(x)).
+     */
+    public static double fromLog(
+        final double logX)
+    {
+        return Math.exp(logX);
+    }
+    
+    /**
+     * Adds two log-domain values. It uses a trick to prevent numerical
+     * overflow and underflow.
+     *
+     * @param   logX
+     *      The first log-domain value (log(x)).
+     *      Must be the same basis as logY.
+     * @param   logY
+     *      The second log-domain value (log(y)).
+     *      Must be the same basis as logX.
+     * @return
+     *      The log of x plus y (log(x + y)).
+     */
+    public static double add(
+        final double logX,
+        final double logY)
+    {
+        if (logX > logY)
+        {
+            return Math.log(1.0 + Math.exp(logY - logX)) + logX;
+        }
+        else if (logY > logX)
+        {
+            return Math.log(1.0 + Math.exp(logX - logY)) + logY;
+        }
+        else
+        {
+            // Since x == y, we have log(x + y) = log(x * 2) = log(x) + log(2).
+            return logX + LOG_2;
+        }
+    }
+
+    /**
+     * Subtracts two log-domain values. It uses a trick to prevent numerical
+     * overflow and underflow.
+     *
+     * @param   logX
+     *      The first log-domain value (log(x)).
+     *      Must be the same basis as logY.
+     * @param   logY
+     *      The second log-domain value (log(y)).
+     *      Must be the same basis as logX.
+     * @return
+     *      The log of x minus y (log(x - y)).
+     */
+    public static double subtract(
+        final double logX,
+        final double logY)
+    {
+        if (logX > logY)
+        {
+            return Math.log(1.0 - Math.exp(logY - logX)) + logX;
+        }
+        else if (logY > logX)
+        {
+            // Since y > x, we will have a log of a negative number, which
+            // does not exist.
+            return Double.NaN;
+        }
+        else
+        {
+            // Since x == y, we have log(x - y) = log(0), which is negative
+            // infinity.
+            return LOG_0;
+        }
+    }
+
+    /**
+     * Multiplies two log-domain values. It uses the identity:
+     *     log(x * y) = log(x) + log(y)
+     *
+     * @param   logX
+     *      The first log-domain value (log(x)).
+     *      Must be the same basis as logY.
+     * @param   logY
+     *      The second log-domain value (log(y)).
+     *      Must be the same basis as logX.
+     * @return
+     *      The log of x divided by y (log(x * y)).
+     */
+    public static double multiply(
+        final double logX,
+        final double logY)
+    {
+        return logX + logY;
+    }
+
+    /**
+     * Divides two log-domain values. It uses the identity:
+     *     log(x / y) = log(x) - log(y)
+     *
+     * @param   logX
+     *      The first log-domain value (log(x)) used in the numerator.
+     *      Must be the same basis as logY.
+     * @param   logY
+     *      The second log-domain value (log(y)) used in the denominator.
+     *      Must be the same basis as logX.
+     * @return
+     *      The log of x times y (log(x / y)).
+     */
+    public static double divide(
+        final double logX,
+        final double logY)
+    {
+        return logX - logY;
+    }
+
+    /**
+     * Takes the inverse of a log-domain value. Using the same identity as
+     * the division one and that log(1) = 0 to be:
+     *    log(x^-1) = log(1 / x) = log(1) - log(x) = -log(x)
+     *
+     * @param   logX
+     *      The log-domain value (log(x)) to invert.
+     * @return
+     *      The log of x^-1 = 1 / x (log(1/x)).
+     */
+    public static double inverse(
+        final double logX)
+    {
+        return -logX;
+    }
+    
+}