com.aliasi.classify
Class ConditionalClassification

java.lang.Object
  com.aliasi.classify.Classification
      com.aliasi.classify.RankedClassification
          com.aliasi.classify.ScoredClassification
              com.aliasi.classify.ConditionalClassification

Direct Known Subclasses:

JointClassification

public class ConditionalClassification
extends ScoredClassification

A ConditionalClassification is a scored classification which estimates conditional probabilities of categories given an input. By default, the scores are the conditional probabilities; if the scores are different than the conditional probabilities, they must be in the same order. Both score and conditional probability are tracked independently by the evaluators. The method conditionalProbability(int) returns the conditional probability based on rank while the superclass method ScoredClassification.score(int) returns the score by rank.

The conditional probabilities must sum to one over the set of categories:

Σrank<size() score(rank) = 1.0

The constructors check that this criterion is satisfied to within a specified arithmetic tolerance. The convenience method Statistics.normalize(double[]) may be used to normalize an array of probability ratios so that they will be an acceptable input to this constructor, but note the warning in that method's documentation concerning arithmetic precision.

Since:

LingPipe2.0

Version:

3.9

Author:

Bob Carpenter

Constructor Summary

ConditionalClassification(String[] categories, double[] conditionalProbs)
Construct a conditional classification with the specified categories and conditional probabilities which sum to one within the default tolerance of 0.01.

ConditionalClassification(String[] categories, double[] conditionalProbs, double tolerance)
Construct a conditional classification with the specified categories and conditional probabilities whose probabilities sum to one within the specified tolerance.

ConditionalClassification(String[] categories, double[] scores, double[] conditionalProbs)
Construct a conditional classification with the specified categories, scores and conditional probabilities which sum to one within the default tolerance of 0.01.

ConditionalClassification(String[] categories, double[] scores, double[] conditionalProbs, double tolerance)
Construct a conditional classification with the specified categories and conditional probabilities whose probabilities sum to one within the specified tolerance.

Method Summary

double	conditionalProbability(int rank) Returns the conditional probability estimate for the category at the specified rank.
double	conditionalProbability(String category) Returns the conditional probability estimate for the specified category.
static ConditionalClassification	createLogProbs(String[] categories, double[] logProbabilities) Return a conditional classification given the categories and log probabilities.
static ConditionalClassification	createProbs(String[] categories, double[] probabilityRatios) Static factory method for conditional classifications based on the specified categories and linear probability ratios.
String	toString() Returns a string-based representation of this conditional probability ranked classification.

Methods inherited from class com.aliasi.classify.ScoredClassification

create, create, score

Methods inherited from class com.aliasi.classify.RankedClassification

category, size

Methods inherited from class com.aliasi.classify.Classification

bestCategory

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ConditionalClassification

public ConditionalClassification(String[] categories,
                                 double[] conditionalProbs)

Construct a conditional classification with the specified categories and conditional probabilities which sum to one within the default tolerance of 0.01. The conditional probabilities are used as the scores.

Parameters:

categories - Categories assigned by classification.

conditionalProbs - Conditional probabilities of the categories.

Throws:

IllegalArgumentException - If the category and probability arrays are of different lengths, if the probabilities or scores are not in descending order, if any probability is less than zero or greater than one, or if their sum is not 1.0 plus or minus 0.01.

ConditionalClassification

public ConditionalClassification(String[] categories,
                                 double[] scores,
                                 double[] conditionalProbs)

Construct a conditional classification with the specified categories, scores and conditional probabilities which sum to one within the default tolerance of 0.01. The scores and conditional probs must be of the same length as the categories and in descending numerical order.

Parameters:

categories - Categories assigned by classification.

scores - Scores of the categories.

conditionalProbs - Conditional probabilities of the categories.

Throws:

IllegalArgumentException - If the category and probability arrays are of different lengths, if the probabilities or scores are not in descending order, if any probability is less than zero or greater than one, or if their sum is not 1.0 plus or minus 0.01.

ConditionalClassification

public ConditionalClassification(String[] categories,
                                 double[] conditionalProbs,
                                 double tolerance)

Construct a conditional classification with the specified categories and conditional probabilities whose probabilities sum to one within the specified tolerance. By setting the tolerance to Double.POSITIVE_INFINITY, there is effectively no consistency requirement placed on the conditional probabilities.

Parameters:

categories - Categories assigned by classification.

conditionalProbs - Conditional probabilities of the categories.

tolerance - Tolerance within which the conditional probabilities must sum to one.

Throws:

IllegalArgumentException - If the category and probability arrays are of different lengths, if the probabilities are not in descending order, if any probability is less than zero or greater than one, or if their sum is not 1.0 plus or minus the tolerance, or if the tolerance is not a positive number.

ConditionalClassification

public ConditionalClassification(String[] categories,
                                 double[] scores,
                                 double[] conditionalProbs,
                                 double tolerance)

Construct a conditional classification with the specified categories and conditional probabilities whose probabilities sum to one within the specified tolerance. By setting the tolerance to Double.POSITIVE_INFINITY, there is effectively no consistency requirement placed on the conditional probabilities.

Parameters:

categories - Categories assigned by classification.

scores - Scores of the categories.

conditionalProbs - Conditional probabilities of the categories.

tolerance - Tolerance within which the conditional probabilities must sum to one.

Throws:

IllegalArgumentException - If the category and probability or score arrays are of different lengths, if the probabilities or scores are not in descending order, if any probability is less than zero or greater than one, or if their sum is not 1.0 plus or minus the tolerance, or if the tolerance is not a positive number.

Method Detail

conditionalProbability

public double conditionalProbability(int rank)

Returns the conditional probability estimate for the category at the specified rank. Note that this method returns the same result as ScoredClassification.score(int) if this classification was initialized without explicit score values.

Parameters:

rank - Rank of category.

Returns:

The conditional probability of the category at the specified rank.

Throws:

IllegalArgumentException - If the rank is out of range.

conditionalProbability

public double conditionalProbability(String category)

Returns the conditional probability estimate for the specified category.

Parameters:

category - category to look for

Returns:

The conditional probability of the specified category

Throws:

IllegalArgumentException - If there is no such category.

toString

public String toString()

Returns a string-based representation of this conditional probability ranked classification.

Overrides:

toString in class ScoredClassification

Returns:

A string-based representation of this classification.

createLogProbs

public static ConditionalClassification createLogProbs(String[] categories,
                                                       double[] logProbabilities)

Return a conditional classification given the categories and log probabilities. The log probabilities do not need to sum to 1; e.g. they could come from joint estimates. This method will normalize them and convert to linear probabilities, attempting to prevent underflow. The log probabilities do not need to be sorted into descending order of probability.

Parameters:

categories - Array of categories.

logProbabilities - Parallel array of log probabilities.

Returns:

Conditional classification corresponding to categories and probabilities.

Throws:

IllegalArgumentException - If any of the log probabilities is infinite, not a number, or positive, or if the arrays are not of the same length.

createProbs

public static ConditionalClassification createProbs(String[] categories,
                                                    double[] probabilityRatios)

Static factory method for conditional classifications based on the specified categories and linear probability ratios. The probabilities do not need to be normalized as they will be renormalized by this method. The probability ratios do not need to be sorted.

If all probability ratios are zero, the result will be a uniform distribution of the same probability for each entry.

Parameters:

categories - Categories for classification.

probabilityRatios - Parallel array of linear probability ratios for the specified categories.

Returns:

The corresponding conditional classification.

Throws:

IllegalArgumentException - If any of the probability ratios are not non-negative and finite numbers.