precisionrecallevaluation.java

一个自然语言处理的Java开源工具包。LingPipe目前已有很丰富的功能

 * <P>The accuracy deviation is the deviation of the average number of
 * positive cases in a binomial distribution with accuracy equal to
 * the classification accuracy and number of trials equal to the total
 * number of cases.
 * 
 * <blockquote><code>
 * <b>accuracyDeviation</b>()
 * = (accuracy() * (1 - accuracy()) / total())<sup><sup>(1/2)</sup></sup>
 * </code></blockquote>
 *
 * This number can be used to provide error intervals around the 
 * accuracy results.
 *
 * <P>Using the following three tables as examples:
 *
 * <blockquote>
 * <table border='0' cellpadding='5'>
 * <tr>

 * <td>
 * <table border='1' cellpadding='3'>
 * <tr><td colspan='4'><b>Cab-vs-All</b></td></tr>
 * <tr><td colspan='2' rowspan='2' bordercolor='white'>&nbsp;</td>
 *     <td colspan='3' align='center'><b><i>Response</i></b></td></tr>
 * <tr>
 *     <td><i>Cab</i></td>
 *     <td><i>Other</i></td></tr>
 * <tr><td rowspan='3'><i><b>Refer<br>-ence</b></i></td><td><i>Cab</i></td>
 *     <td bgcolor='#CCCCFF'>9</td><td>3</td></tr>
 * <tr><td><i>Other</i></td>
 *     <td>4</td><td bgcolor='#CCCCFF'>11</td></tr>
 * </table>
 * </td>
 *
 * <td>
 * <table border='1' cellpadding='3'>
 * <tr><td colspan='4'><b>Syrah-vs-All</b></td></tr>
 * <tr><td colspan='2' rowspan='2' bordercolor='white'>&nbsp;</td>
 *     <td colspan='3' align='center'><b><i>Response</i></b></td></tr>
 * <tr>
 *     <td><i>Syrah</i></td>
 *     <td><i>Other</i></td></tr>
 * <tr><td rowspan='3'><i><b>Refer<br>-ence</b></i></td><td><i>Syrah</i></td>
 *     <td bgcolor='#CCCCFF'>5</td><td>4</td></tr>
 * <tr><td><i>Other</i></td>
 *     <td>4</td><td bgcolor='#CCCCFF'>14</td></tr>
 * </table>
 * </td>
 *
 * <td>
 * <table border='1' cellpadding='3'>
 * <tr><td colspan='4'><b>Pinot-vs-All</b></td></tr>
 * <tr><td colspan='2' rowspan='2' bordercolor='white'>&nbsp;</td>
 *     <td colspan='3' align='center'><b><i>Response</i></b></td></tr>
 * <tr>
 *     <td><i>Pinot</i></td>
 *     <td><i>Other</i></td></tr>
 * <tr><td rowspan='3'><i><b>Refer<br>-ence</b></i></td><td><i>Pinot</i></td>
 *     <td bgcolor='#CCCCFF'>4</td><td>2</td></tr>
 * <tr><td><i>Other</i></td>
 *     <td>1</td><td bgcolor='#CCCCFF'>20</td></tr>
 * </table>
 * </td>
 *
 * </tr>
 * </table>
 *
 * </blockquote>
 *
 * The various statistics evaluate to the following values:
 *
 * <blockquote>
 * <table border='1' cellpadding='5'>
 * <tr><td><i>Method</i></td>
 *     <td><i>Cabernet</i></td>
 *     <td><i>Syrah</i></td>
 *     <td><i>Pinot</i></td></tr>
 * <tr><td>{@link #positiveReference()}</td>
 *     <td>12</td><td>9</td><td>6</td></tr>
 * <tr><td>{@link #negativeReference()}</td>
 *     <td>15</td><td>18</td><td>21</td></tr>
 * <tr><td>{@link #positiveResponse()}</td>
 *     <td>13</td><td>9</td><td>5</td></tr>
 * <tr><td>{@link #negativeResponse()}</td>
 *     <td>14</td><td>18</td><td>22</td></tr>
 * <tr><td>{@link #correctResponse()}</td>
 *     <td>20</td><td>19</td><td>24</td></tr>
 * <tr><td>{@link #total()}</td>
 *     <td>27</td><td>27</td><td>27</td></tr>
 * <tr><td>{@link #accuracy()}</td>
 *     <td>0.7407</td><td>0.7037</td><td>0.8889</td></tr>
 * <tr><td>{@link #recall()}</td>
 *     <td>0.7500</td><td>0.5555</td><td>0.6666</td></tr>
 * <tr><td>{@link #precision()}</td>
 *     <td>0.6923</td><td>0.5555</td><td>0.8000</td></tr>
 * <tr><td>{@link #rejectionRecall()}</td>
 *     <td>0.7333</td><td>0.7778</td><td>0.9524</td></tr>
 * <tr><td>{@link #rejectionPrecision()}</td>
 *     <td>0.7858</td><td>0.7778</td><td>0.9091</td></tr>
 * <tr><td>{@link #fMeasure()}</td>
 *     <td>0.7200</td><td>0.5555</td><td>0.7272</td></tr>
 * <tr><td>{@link #fowlkesMallows()}</td>
 *     <td>12.49</td><td>9.00</td><td>5.48</td></tr>
 * <tr><td>{@link #jaccardCoefficient()}</td>
 *     <td>0.5625</td><td>0.3846</td><td>0.5714</td></tr>
 * <tr><td>{@link #yulesQ()}</td>
 *     <td>0.7838</td><td>0.6279</td><td>0.9512</td></tr>
 * <tr><td>{@link #yulesY()}</td>
 *     <td>0.4835</td><td>0.3531</td><td>0.7269</td></tr>
 * <tr><td>{@link #referenceLikelihood()}</td>
 *     <td>0.4444</td><td>0.3333</td><td>0.2222</td></tr>
 * <tr><td>{@link #responseLikelihood()}</td>
 *     <td>0.4815</td><td>0.3333</td><td>0.1852</td></tr>
 * <tr><td>{@link #randomAccuracy()}</td>
 *     <td>0.5021</td><td>0.5556</td><td>0.6749</td></tr>
 * <tr><td>{@link #kappa()}</td>
 *     <td>0.4792</td><td>0.3333</td><td>0.6583</td></tr>
 * <tr><td>{@link #randomAccuracyUnbiased()}</td>
 *     <td>0.5027</td><td>0.5556</td><td>0.6756</td></tr>
 * <tr><td>{@link #kappaUnbiased()}</td>
 *     <td>0.4789</td><td>0.3333</td><td>0.6575</td></tr>
 * <tr><td>{@link #kappaNoPrevalence()}</td>
 *     <td>0.4814</td><td>0.4074</td><td>0.7778</td></tr>
 * <tr><td>{@link #chiSquared()}</td>
 *     <td>6.2382</td><td>3.0000</td><td>11.8519</td></tr>
 * <tr><td>{@link #phiSquared()}</td>
 *     <td>0.2310</td><td>0.1111</td><td>0.4390</td></tr>
 * <tr><td>{@link #accuracyDeviation()}</td>
 *     <td>0.0843</td><td>0.0879</td><td>0.0605</td></tr>
 * </table>
 * </blockquote>
 *
 * @author Bob Carpenter
 * @version 2.1
 * @since   LingPipe2.1
 */
public class PrecisionRecallEvaluation {

    private long mTP;
    private long mFP;
    private long mTN;
    private long mFN;

    /**
     * Construct a precision-recall evaluation with all counts set to
     * zero.
     */
    public PrecisionRecallEvaluation() { 
        this(0,0,0,0);
    }

    /**
     * Construction a precision-recall evaluation initialized with the
     * specified counts.
     *
     * @param tp True positive count.
     * @param fn False negative count.
     * @param fp False positive count.
     * @param tn True negative count.
     * @throws IllegalArgumentException If any of the counts are
     * negative.
     */
    public PrecisionRecallEvaluation(long tp, long fn, long fp, long tn) {
        validateCount("tp",tp);
        validateCount("fp",fp);
        validateCount("tn",tn);
        validateCount("fn",fn);
        mTP = tp;
        mFP = fp;
        mTN = tn;
        mFN = fn;
    }

    /**
     * Adds a case with the specified reference and response
     * classifications.
     *
     * @param reference Reference classification.
     * @param response Response classification.
     */
    public void addCase(boolean reference, boolean response) {
        if (reference && response) ++mTP;
        else if (reference && (!response)) ++mFN;
        else if ((!reference) && response) ++mFP;
        else ++mTN;
    }

    void addCase(boolean reference, boolean response, int count) {
        if (reference && response) mTP += count;
        else if (reference && (!response)) mFN += count;
        else if ((!reference) && response) mFP += count;
        else mTN += count;
    }

    /**
     * Returns the number of true positive cases.  A true positive
     * is where both the reference and response are true.
     *
     * @return The number of true positives.
     */
    public long truePositive() {
        return mTP;
    }

    /**
     * Returns the number of false positive cases.  A false positive
     * is where the reference is false and response is true.
     *
     * @return The number of false positives.
     */
    public long falsePositive() {
        return mFP;
    }

    /**
     * Returns the number of true negative cases.  A true negative
     * is where both the reference and response are false. 
     *
     * @return The number of true negatives.
     */
    public long trueNegative() {
        return mTN;
    }

    /**
     * Returns the number of false negative cases.  A false negative
     * is where the reference is true and response is false.
     *
     * @return The number of false negatives.
     */
    public long falseNegative() {
        return mFN;
    }

    /**
     * Returns the number of positive reference cases.  A positive
     * reference case is one where the reference is true.
     *
     * @return The number of positive references.
     */
    public long positiveReference() {
        return truePositive() + falseNegative();
    }
    
    /**
     * Returns the number of negative reference cases.  A negative
     * reference case is one where the reference is false.
     *
     * @return The number of negative references.
     */
    public long negativeReference() {
        return trueNegative() + falsePositive();
    }

    /**
     * Returns the sample reference likelihood, which is the number of
     * positive references divided by the total number of cases.
     *
     * @return The sample reference likelihood.
     */
    public double referenceLikelihood() {
        return div(positiveReference(), total());
    }

    /**
     * Returns the number of positive response cases.  A positive
     * response case is one where the response is true.
     * 
     * @return The number of positive responses.
     */
    public long positiveResponse() {
        return truePositive() + falsePositive();
    }

    /**
     * Returns the number of negative response cases.  A negative
     * response case is one where the response is false.
     * 
     * @return The number of negative responses.
     */
    public long negativeResponse() {
        return trueNegative() + falseNegative();
    }

    /**
     * Returns the sample response likelihood, which is the number of
     * positive responses divided by the total number of cases.
     *
     * @return The sample response likelihood.
     */
    public double responseLikelihood() {
        return div(positiveResponse(), total());
    }

    /**
     * Returns the number of cases where the response is correct.  A
     * correct response is one where the reference and response are
     * the same.
     *
     * @return The number of correct responses.
     */
    public long correctResponse() {
        return truePositive() + trueNegative();
    }

    /**
     * Returns the number of cases where the response is incorrect.
     * An incorrect response is one where the reference and response
     * are different.
     *