Package com.tibco.patterns.learn.api.project

## Class RecPair

- java.lang.Object
- - com.tibco.patterns.learn.api.project.RecPair

-     public final class RecPair
      extends java.lang.Object

  Stores information about one record pair, including field values, feature scores and label. Objects of RecPair are passed to/from Learn API.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `RecPair.ConfScoreComparator` | Provides ordering by a combination (weighted sum) of the prediction confidence (ascending) and the distance of the model score from the 0.5 threshold (ascending).
    `static class` | `RecPair.Label` | Defines a label that can be assigned to a record pair: True, False or Unsure.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.util.Comparator<RecPair>` | `CONFIDENCE_ORDER` | Provides ascending order by prediction confidence.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RecPair​(java.lang.String key0, java.lang.String key1, java.util.List<java.lang.String> values0, java.util.List<java.lang.String> values1)` | Creates a new record pair with required data to be passed to Learn API.
    `RecPair​(java.lang.String key0, java.lang.String key1, java.util.List<java.lang.String> values0, java.util.List<java.lang.String> values1, RecPair.Label label)` | Creates a labeled record pair to be passed to Learn API.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `double` | `calcAndScore​(RecPairScorer scorer)` | Calculates the symmetric match score of using all feature querylets (that compute symmetric querylet scores) combined with an AND score combiner.
    `void` | `calcFeatureScores​(RecPairScorer scorer)` | Calculates and saves symmetric feature scores in this object.
    `double` | `calcQltScore​(java.lang.String featureName, int qltIndex, RecPairScorer scorer)` | Calculates score of a single querylet of the given feature.
    `boolean` | `correctPrediction()` |
    `boolean` | `equals​(java.lang.Object obj)` |
    `boolean` | `featureValuesSimilar​(RecPair other, double maxDiff)` | Calculates whether the feature values in two pairs are similar.
    `double[]` | `getFeatureValues()` | No setter - feature values are calculated and assigned to XML structure
    `java.util.List<java.util.List<java.lang.String>>` | `getFieldValues()` |
    `RecPairId` | `getId()` |
    `RecPair.Label` | `getLabel()` |
    `int` | `getNFields()` |
    `static int` | `getNRecords()` |
    `DataPartition` | `getPartition()` |
    `RLinkOut` | `getPrediction()` | No public setter - model result is calculated during training.
    `RecPair.Label` | `getTrainLabel()` | No setter - training label is saved together with model prediction.
    `int` | `hashCode()` |
    `boolean` | `hasPrediction()` |
    `boolean` | `incorrectPrediction()` |
    `boolean` | `isFalseNeg()` |
    `boolean` | `isFalsePos()` |
    `boolean` | `isReview()` |
    `void` | `setLabel​(RecPair.Label value)` |
    `void` | `setPartition​(DataPartition value)` | Sets the data partition.
    `void` | `setReview​(boolean value)` | Sets the Review property (whether the pair needs to be reviewed).
    `java.lang.String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### CONFIDENCE_ORDER

          public static final java.util.Comparator<RecPair> CONFIDENCE_ORDER

      Provides ascending order by prediction confidence. Pairs without predictions will be at the start of the sorted collection. The comparator is consistent with equals: pairs that have the same confidence or no confidence are ordered by record keys.

  - ### Constructor Detail

    - #### RecPair

          public RecPair​(java.lang.String key0,
                         java.lang.String key1,
                         java.util.List<java.lang.String> values0,
                         java.util.List<java.lang.String> values1)

      Creates a new record pair with required data to be passed to Learn API. The provided field values must match the list of non-key fields in the data file. They must not contain nulls - use empty strings instead.
      Parameters:
        `key0` - - key field value of record 0.
        `key1` - - key field value of record 1.
        `values0` - - values of record 0. Not null.
        `values1` - - values of record 1. Not null.
      Throws:
        `java.lang.IllegalArgumentException` - if either list is empty, or lists do not have the same number of field values.

    - #### RecPair

          public RecPair​(java.lang.String key0,
                         java.lang.String key1,
                         java.util.List<java.lang.String> values0,
                         java.util.List<java.lang.String> values1,
                         RecPair.Label label)

      Creates a labeled record pair to be passed to Learn API.
      See Also:
        `RecPair(String, String, List, List)`

  - ### Method Detail

    - #### getNRecords

          public static int getNRecords()

      Returns:
        the number of records in a record pair (2).

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### equals

          public boolean equals​(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`
      Returns:
        true if the IDs of the two record pairs are equal.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code of the record pair ID.

    - #### getId

          public RecPairId getId()

      Returns:
        the ID (two keys) for the records in the pair. Not null.

    - #### getFieldValues

          public java.util.List<java.util.List<java.lang.String>> getFieldValues()

      Returns:
        a copy of field values for both records in the pair. Not null.

    - #### getNFields

          public int getNFields()

      Returns:
        the number of field values (not including key field) in each of the two records.

    - #### setLabel

          public void setLabel​(RecPair.Label value)

      Parameters:
        `value` - - new label of the record pair. Not null.

    - #### getLabel

          public RecPair.Label getLabel()

      Returns:
        assigned label, or null if label has not been assigned.

    - #### setReview

          public void setReview​(boolean value)

      Sets the Review property (whether the pair needs to be reviewed).

    - #### isReview

          public boolean isReview()

      Returns:
        the Review property (whether the pair needs to be reviewed).

    - #### setPartition

          public void setPartition​(DataPartition value)

      Sets the data partition. Note that this has no effect on which dataset this pair will be added to, that dataset is always determined automatically.

    - #### getPartition

          public DataPartition getPartition()

      Returns:
        the dataset that the pair belongs to. Returns null if this pair was created outside the Learn API.

    - #### getFeatureValues

          public double[] getFeatureValues()

      No setter - feature values are calculated and assigned to XML structure
      Returns:
        feature values, or null if feature values were not assigned

    - #### calcFeatureScores

          public void calcFeatureScores​(RecPairScorer scorer)
                                 throws java.io.IOException,
                                        com.netrics.likeit.NetricsException

      Calculates and saves symmetric feature scores in this object.
      Throws:
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - - if I/O error occurs while communicating with server

    - #### calcAndScore

          public double calcAndScore​(RecPairScorer scorer)
                              throws java.io.IOException,
                                     com.netrics.likeit.NetricsException

      Calculates the symmetric match score of using all feature querylets (that compute symmetric querylet scores) combined with an AND score combiner. Does not change the prediction score (if any) stored in this object.
      Parameters:
        `scorer` - - the scorer created from project that is compatible with this pair.
      Returns:
        the AND score.
      Throws:
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - - if I/O error occurs while communicating with server

    - #### calcQltScore

          public double calcQltScore​(java.lang.String featureName,
                                     int qltIndex,
                                     RecPairScorer scorer)
                              throws java.io.IOException,
                                     com.netrics.likeit.NetricsException

      Calculates score of a single querylet of the given feature.
      Parameters:
        `featureName` - - name of the feature. If several features have the same name, the first such feature is used.
        `qltIndex` - - index of the querylet within the feature.
        `scorer` - - the scorer created from project that is compatible with this pair.
      Returns:
        the score of the single querylet.
      Throws:
        `java.lang.IllegalArgumentException` - if feature with the given name is not found.
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - - if I/O error occurs while communicating with server

    - #### featureValuesSimilar

          public boolean featureValuesSimilar​(RecPair other,
                                              double maxDiff)

      Calculates whether the feature values in two pairs are similar.
      Parameters:
        `maxDiff` - - maximum difference in each feature value.
      Returns:
        true if all feature scores in the two pairs do not differ by more than maxDiff, false otherwise. Returns false if other pair is null, or if feature scores were not calculated for either pair, or if the number of feature values is different in the two pairs.

    - #### getPrediction

          public RLinkOut getPrediction()

      No public setter - model result is calculated during training.
      Returns:
        model prediction. May be null if model prediction has not been saved.

    - #### getTrainLabel

          public RecPair.Label getTrainLabel()

      No setter - training label is saved together with model prediction.
      Returns:
        the label used during training. Null if model prediction has not been saved. May be null or Unsure if the pair was not used in training.

    - #### hasPrediction

          public boolean hasPrediction()

      Returns:
        true if the record pair has a saved model result with boolean label and a model score.

    - #### correctPrediction

          public boolean correctPrediction()

      Returns:
        true if the prediction stored in this RecPair is correct; false if it is incorrect or if record pair contains no prediction with bool label.

    - #### incorrectPrediction

          public boolean incorrectPrediction()

      Returns:
        true if the prediction stored in this RecPair is incorrect; false if it is correct or if record pair contains no prediction with bool label.

    - #### isFalsePos

          public boolean isFalsePos()

      Returns:
        true if the record pair prediction exists and it is false positive.

    - #### isFalseNeg

          public boolean isFalseNeg()

      Returns:
        true if the record pair prediction exists and it is false negative.