Package com.tibco.patterns.learn.recpair

## Class RecPairScorer

- java.lang.Object
- - com.tibco.patterns.learn.recpair.RecPairScorer

- All Implemented Interfaces:
    `java.lang.AutoCloseable`

      public final class RecPairScorer
      extends java.lang.Object
      implements java.lang.AutoCloseable

  Manages calculation of feature scores and communication with Patterns server. Does approximate text matching between the two records in the pair. Runs specific queries on the server using the feature query, maintains the necessary thesauri and an optional model on the server. The input of Record Pair Scorer is predefined record pairs (from file, other class, etc.) Features are defined in FeatureQuery object. Output is a feature vector for the RecPairExample. It contains match scores for each feature.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `RecPairScorer​(com.netrics.likeit.NetricsServerInterface server, com.netrics.likeit.NetricsTable tableDef, FeatureQuery featureQuery, java.nio.file.Path thesDir)` | Creates scorer object for scoring records.
    `RecPairScorer​(com.netrics.likeit.NetricsServerInterface server, java.lang.String table, FeatureQuery featureQuery, java.nio.file.Path thesDir)` | Creates scorer object for scoring records and getting field values from the existing table on the server.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `double` | `calcAndScore​(java.util.List<java.lang.String> tableRecValues, java.util.List<java.lang.String> queryValues)` | Calculates symmetric match score for the given pair of records using all feature querylets (that compute symmetric querylet scores) combined with an AND score combiner.
    `double` | `calcQltScore​(java.lang.String featureName, int qltIndex, java.util.List<java.lang.String> tableRecValues, java.util.List<java.lang.String> queryValues)` | Calculates score of a single querylet of the given feature.
    `void` | `close()` | Deletes thesauri and model (if it exists) from server.
    `protected void` | `finalize()` | Provided for safety, but client code must call `close()` explicitly.
    `java.util.List<com.netrics.likeit.NetricsSearchResult>` | `getLowConfMatches​(java.util.List<java.lang.String> queryValues, double confThreshold, Confidence conf)` | Runs a query on server to get the low confidence matches in the data table for the given query record.The query uses the model and thesauri on server.
    `boolean` | `isModelLoaded()` | Checks if the model was loaded to server by this object.
    `void` | `loadModel​(java.lang.String projectName, java.nio.file.Path modelFile)` | Loads the model to server.
    `void` | `safeDeleteModel()` | Deletes the model from server if it has been loaded.
    `double[]` | `scoreRecPair​(RecPairId recPairId)` | Computes symmetric querylet scores for the pair of records defined by key0 and key1.
    `double[]` | `scoreRecPair​(java.util.List<java.lang.String> tableRecValues, java.util.List<java.lang.String> queryValues)` | Computes symmetric querylet scores for the given pair of records.
    `java.lang.String` | `toString()` |

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

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

- - ### Constructor Detail

    - #### RecPairScorer

          public RecPairScorer​(com.netrics.likeit.NetricsServerInterface server,
                               com.netrics.likeit.NetricsTable tableDef,
                               FeatureQuery featureQuery,
                               java.nio.file.Path thesDir)
                        throws java.io.IOException,
                               com.netrics.likeit.NetricsException

      Creates scorer object for scoring records. Does not use existing table on the server. Methods that search or get field values from the table on server cannot be used.
      Parameters:
        `server` - - refers to the server instance used to calculate feature scores. Not null.
        `tableDef` - - definition of the table that all records come from. Not null.
        `featureQuery` - - defines the query with model features (querylets). Not null.
        `thesDir` - - the directory with all thesaurus files used in feature query. May be null if no thesauri are used.
      Throws:
        `com.netrics.likeit.NetricsException` - if error occured on server.
        `java.io.IOException` - if the server does not exist, is not accessible, or if an I/O error occurs while communicating with server

    - #### RecPairScorer

          public RecPairScorer​(com.netrics.likeit.NetricsServerInterface server,
                               java.lang.String table,
                               FeatureQuery featureQuery,
                               java.nio.file.Path thesDir)
                        throws java.io.IOException,
                               com.netrics.likeit.NetricsException

      Creates scorer object for scoring records and getting field values from the existing table on the server. Loads thesauri to server.
      Parameters:
        `server` - - refers to the server instance used to calculate feature scores.
        `table` - - the table that contains all records. Must exist on server.
        `featureQuery` - - defines the query with model features (querylets)
        `thesDir` - - the directory with all thesaurus files used in feature query. May be null if no thesauri are used.
      Throws:
        `com.netrics.likeit.NetricsException` - if the given table is not found on server (TBLNOTFOUND), or if another error occured on server.
        `java.io.IOException` - if the server does not exist, is not accessible or if an I/O error occurs while communicating with server.

  - ### Method Detail

    - #### close

          public void close()
                     throws java.io.IOException,
                            com.netrics.likeit.NetricsException

      Deletes thesauri and model (if it exists) from server. Must be called when this object will no longer be used.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `com.netrics.likeit.NetricsException` - if the server indicates that an error has occured
        `java.io.IOException` - if an I/O error occurs while communicating with server

    - #### finalize

          protected void finalize()
                           throws java.io.IOException,
                                  com.netrics.likeit.NetricsException

      Provided for safety, but client code must call `close()` explicitly.
      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `com.netrics.likeit.NetricsException` - if the server indicates that an error has occured
        `java.io.IOException` - if an I/O error occurs while communicating with server

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        information on table, query, thesauri and model on server.

    - #### scoreRecPair

          public double[] scoreRecPair​(RecPairId recPairId)
                                throws java.io.IOException,
                                       com.netrics.likeit.NetricsException

      Computes symmetric querylet scores for the pair of records defined by key0 and key1. The two records must exist in the server table which must be provided to the constructor.
      Parameters:
        `recPairId` - - the keys for the record pair to be scored. Not null.
      Returns:
        Feature vector, i.e. querylet scores for the record pair.
      Throws:
        `com.netrics.likeit.NetricsException` - if a record does not exist in the server table, or other errors on server.
        `java.io.IOException` - if I/O error occurs while communicating with server
        `java.lang.IllegalArgumentException` - if number of query field values does not match the number of all fields in feature query.
        `java.lang.IllegalStateException` - if server table was not provided to the constructor, or if the object has been closed.

    - #### scoreRecPair

          public double[] scoreRecPair​(java.util.List<java.lang.String> tableRecValues,
                                       java.util.List<java.lang.String> queryValues)
                                throws java.io.IOException,
                                       com.netrics.likeit.NetricsException

      Computes symmetric querylet scores for the given pair of records.
      Parameters:
        `tableRecValues` - - field values of record 0. Does not include the key field. Not null.
        `queryValues` - - field values of record 1. Does not include the key field. Not null.
      Returns:
        Feature vector, i.e. querylet scores for the record pair.
      Throws:
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - if I/O error occurs while communicating with server
        `java.lang.IllegalArgumentException` - if numbers of values in table record and query do not match, or if number of query field values does not match the number of all fields in feature query.
        `java.lang.IllegalStateException` - if this object has been closed.

    - #### calcAndScore

          public double calcAndScore​(java.util.List<java.lang.String> tableRecValues,
                                     java.util.List<java.lang.String> queryValues)
                              throws java.io.IOException,
                                     com.netrics.likeit.NetricsException

      Calculates symmetric match score for the given pair of records using all feature querylets (that compute symmetric querylet scores) combined with an AND score combiner.
      Parameters:
        `tableRecValues` - - field values of record 0. Does not include the key field. Not null.
        `queryValues` - - field values of record 1. Does not include the key field. Not null.
      Returns:
        the match score for the record pair from the AND score combiner.
      Throws:
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - if I/O error occurs while communicating with server
        `java.lang.IllegalArgumentException` - if numbers of values in table record and query do not match, or if number of query field values does not match the number of all fields in feature query.
        `java.lang.IllegalStateException` - if this object has been closed.

    - #### calcQltScore

          public double calcQltScore​(java.lang.String featureName,
                                     int qltIndex,
                                     java.util.List<java.lang.String> tableRecValues,
                                     java.util.List<java.lang.String> queryValues)
                              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.
        `tableRecValues` - - field values of record 0. Does not include the key field. Not null.
        `queryValues` - - field values of record 1. Does not include the key field. Not null.
      Returns:
        the match score of the querylet.
      Throws:
        `java.lang.IllegalArgumentException` - if feature with the given name is not found, or if number of query field values does not match the number of all fields.
        `java.lang.IllegalStateException` - if this object has been closed.
        `com.netrics.likeit.NetricsException` - - errors on the server
        `java.io.IOException` - if I/O error occurs while communicating with server

    - #### loadModel

          public void loadModel​(java.lang.String projectName,
                                java.nio.file.Path modelFile)
                         throws com.netrics.likeit.NetricsException,
                                java.io.IOException

      Loads the model to server. Deletes any previous model.
      Parameters:
        `projectName` - - project name to be prepended to the model name on server.
        `modelFile` - - full path to the model file to be loaded.
      Throws:
        `com.netrics.likeit.NetricsException` - if the server indicates that an error has occured
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalArgumentException` - if modelFile does not exist.
        `java.lang.IllegalStateException` - if this object has been closed.

    - #### safeDeleteModel

          public void safeDeleteModel()
                               throws com.netrics.likeit.NetricsException,
                                      java.io.IOException

      Deletes the model from server if it has been loaded.
      Throws:
        `com.netrics.likeit.NetricsException` - if the server indicates that an error has occured.
        `java.io.IOException` - if an I/O error occurs.

    - #### isModelLoaded

          public boolean isModelLoaded()

      Checks if the model was loaded to server by this object. (It does not check the server if the loaded model is still there.)
      Returns:
        true if the trained model has been leaded to server.

    - #### getLowConfMatches

          public java.util.List<com.netrics.likeit.NetricsSearchResult> getLowConfMatches​(java.util.List<java.lang.String> queryValues,
                                                                                          double confThreshold,
                                                                                          Confidence conf)
                                                                                   throws com.netrics.likeit.NetricsException,
                                                                                          java.io.IOException

      Runs a query on server to get the low confidence matches in the data table for the given query record.The query uses the model and thesauri on server.
      Parameters:
        `queryValues` - - field values for the query record. Not null.
        `confThreshold` - - return records with confidence less than or equal to this threshold.
        `conf` - - contains feature confidence parameters to be used in the query. Not null.
      Returns:
        the low confidence matches in the data table returned by the query.
      Throws:
        `com.netrics.likeit.NetricsException` - if the server indicates that an error has occured
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalStateException` - if this object has been closed, or if the data table or the model was not loaded to server, or if conf is not FeatureQConf.