com.aliasi.classify
Class ConditionalClassification

java.lang.Object
  extended by com.aliasi.classify.Classification
      extended by com.aliasi.classify.RankedClassification
          extended by com.aliasi.classify.ScoredClassification
              extended by 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, 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.