com.aliasi.classify

## Class 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

Constructors
Constructor and Description
```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

All Methods
Modifier and Type Method and Description
`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.