Package com.tibco.patterns.learn.training

## Class COScoreChange

- java.lang.Object
- - com.tibco.patterns.learn.training.COIterationCount
  - - com.tibco.patterns.learn.training.COScoreChange

- All Implemented Interfaces:
    `ConvergenceObserver`, `TrainingObserver`

      public class COScoreChange
      extends COIterationCount

  Stops the training when the maximum change in prediction scores compared with the previous iteration is below the given threshold. Always does at least minIterations.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `COScoreChange()` | Creates object with default parameters.
    `COScoreChange​(double targetScoreChange, int minIterations, int maxIterations)` | Creates the object with given parameters.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `beginIteration()` | Prepares to accumulate statistics for a new training iteration.
    `void` | `endIteration()` | If printing is enabled, outputs the maximum score change of the iteration that has just ended.
    `void` | `evaluatePrediction​(VectorExample e)` | Updates the current maximum score change based on the prediction score for the given example.
    `static int` | `getDftMinIterations()` |
    `static double` | `getDftTargetScoreChange()` |
    `double` | `getProgressEstimate()` | Returns an estimate of training progress, which can be used to indicate how close the desired convergence is.
    `boolean` | `isConverged()` | Returns whether the trained model has converged.
    `boolean` | `isPerfectResult()` |
    `boolean` | `needStopTraining()` | Returns whether the training has to be stopped after current iteration.
    `COScoreChange` | `setPrint​(boolean value)` | Enables printing of iteration results to console.
    `java.lang.String` | `toString()` |

    - ### Methods inherited from class com.tibco.patterns.learn.training.COIterationCount

      `getDftMaxIterations, getMaxIterations, getNIterations, hasIterations, setMaxIterations, verifyIterationBegun, verifyIterationEnded`

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

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

- - ### Constructor Detail

    - #### COScoreChange

          public COScoreChange​(double targetScoreChange,
                               int minIterations,
                               int maxIterations)

      Creates the object with given parameters.
      Parameters:
        `targetScoreChange` - - target change of prediction scores that is used as a threshold to stop the training.
        `minIterations` - - minimum number of iterations that is always performed.
        `maxIterations` - - maximum number of model training iterations to perform.
      Throws:
        `java.lang.IllegalArgumentException` - if max iterations is not positive, or target score change is not positive, or min iterations is not less than max iterations, or min iterations is negative.

    - #### COScoreChange

          public COScoreChange()

      Creates object with default parameters.
      See Also:
        `getDftTargetScoreChange()`, `getDftMinIterations()`

  - ### Method Detail

    - #### getDftTargetScoreChange

          public static double getDftTargetScoreChange()

      Returns:
        default target score change (0.01).

    - #### getDftMinIterations

          public static int getDftMinIterations()

      Returns:
        default minimum number of iterations to perform (0).

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `COIterationCount`

    - #### setPrint

          public COScoreChange setPrint​(boolean value)

      Enables printing of iteration results to console.

    - #### beginIteration

          public void beginIteration()

      Prepares to accumulate statistics for a new training iteration.
      Specified by:
        `beginIteration` in interface `TrainingObserver`
      Overrides:
        `beginIteration` in class `COIterationCount`
      Throws:
        `java.lang.IllegalStateException` - if an iteration has already begun.

    - #### endIteration

          public void endIteration()

      If printing is enabled, outputs the maximum score change of the iteration that has just ended.
      Specified by:
        `endIteration` in interface `TrainingObserver`
      Overrides:
        `endIteration` in class `COIterationCount`
      Throws:
        `java.lang.IllegalStateException` - if iteration has not begun.

    - #### evaluatePrediction

          public void evaluatePrediction​(VectorExample e)

      Updates the current maximum score change based on the prediction score for the given example. The examples in the dataset can be trained/evaluated in any order.
      Specified by:
        `evaluatePrediction` in interface `TrainingObserver`
      Overrides:
        `evaluatePrediction` in class `COIterationCount`
      Parameters:
        `e` - - must contain RLink prediction.
      Throws:
        `java.lang.IllegalStateException` - if iteration has not begun.

    - #### getProgressEstimate

          public double getProgressEstimate()

      Description copied from interface: `ConvergenceObserver`
      Returns an estimate of training progress, which can be used to indicate how close the desired convergence is. The interpretation and range of the returned value can vary between subclasses. Typically, the return value approaches 0 as the model is converging. Should be called after an iteration, not in the middle of iteration.
      Specified by:
        `getProgressEstimate` in interface `ConvergenceObserver`
      Overrides:
        `getProgressEstimate` in class `COIterationCount`
      Returns:
        maximum change in prediction scores compared with previous iteration.
      Throws:
        `java.lang.IllegalStateException` - if iteration has not ended or no iterations were performed.

    - #### isConverged

          public boolean isConverged()

      Description copied from interface: `ConvergenceObserver`
      Returns whether the trained model has converged. Depending on implementation, this can be based on one or several iterations of evaluating the verification set.
      Specified by:
        `isConverged` in interface `ConvergenceObserver`
      Overrides:
        `isConverged` in class `COIterationCount`
      Returns:
        true if minimum number of iterations were done and the maximum change in prediction scores compared with previous iteration is below the target score change.
      Throws:
        `java.lang.IllegalStateException` - if iteration has not ended or no iterations were performed.

    - #### needStopTraining

          public boolean needStopTraining()

      Description copied from interface: `ConvergenceObserver`
      Returns whether the training has to be stopped after current iteration. This may mean that the model has converged, based on all score evaluations that were performed. Or the model may have failed to converge and another termination condition was reached.
      Specified by:
        `needStopTraining` in interface `ConvergenceObserver`
      Overrides:
        `needStopTraining` in class `COIterationCount`
      Returns:
        true if maximum number of iterations was performed or convergence criteria are satisfied.
      Throws:
        `java.lang.IllegalStateException` - if iteration has not ended or no iterations were performed.
      See Also:
        `isConverged()`

    - #### isPerfectResult

          public boolean isPerfectResult()

      Specified by:
        `isPerfectResult` in interface `TrainingObserver`
      Overrides:
        `isPerfectResult` in class `COIterationCount`
      Returns:
        true if there was no change in any prediction score compared with the previous iteration
      Throws:
        `java.lang.IllegalStateException` - if iteration has not ended or no iterations were performed.