org.apache.ignite.ml.composition.boosting

## Class GDBTrainer

- java.lang.Object
- - org.apache.ignite.ml.trainers.DatasetTrainer<GDBModel,Double>
  - - org.apache.ignite.ml.composition.boosting.GDBTrainer

- Direct Known Subclasses:
    GDBBinaryClassifierTrainer, GDBRegressionTrainer

      public abstract class GDBTrainer
      extends DatasetTrainer<GDBModel,Double>

  Abstract Gradient Boosting trainer. It implements gradient descent in functional space using user-selected regressor in child class. Each learning iteration the trainer evaluate gradient of error-function and fit regression model to it. After learning step the model is used in models composition of regressions with weight equal to gradient descent step. These classes can be used as regressor trainers: `DecisionTreeRegressionTrainer`, `KNNRegressionTrainer`, `LinearRegressionLSQRTrainer`, `RandomForestRegressionTrainer`, `LinearRegressionSGDTrainer`. But in practice Decision Trees is most used regressors (see: `DecisionTreeRegressionTrainer`).

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.ignite.ml.trainers.DatasetTrainer

      `DatasetTrainer.EmptyDatasetException`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ConvergenceCheckerFactory` | `checkConvergenceStgyFactory` Check convergence strategy factory.
    `protected Loss` | `loss` Loss function.

    - ### Fields inherited from class org.apache.ignite.ml.trainers.DatasetTrainer

      `envBuilder, environment`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GDBTrainer(double gradStepSize, Integer cntOfIterations, Loss loss)` Constructs GDBTrainer instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected abstract @NotNull DatasetTrainer<? extends IgniteModel<Vector,Double>,Double>` | `buildBaseModelTrainer()` Returns regressor model trainer for one step of GDB.
    `protected <V,K,C extends Serializable> IgniteBiTuple<Double,Long>` | `computeInitialValue(LearningEnvironmentBuilder envBuilder, DatasetBuilder<K,V> builder, Preprocessor<K,V> preprocessor)` Compute mean value of label as first approximation.
    `protected abstract double` | `externalLabelToInternal(double lbl)` Maps external representation of label to internal.
    `<K,V> GDBModel` | `fitWithInitializedDeployingContext(DatasetBuilder<K,V> datasetBuilder, Preprocessor<K,V> preprocessor)` Trains model based on the specified data.
    `protected GDBLearningStrategy` | `getLearningStrategy()` Returns learning strategy.
    `protected abstract double` | `internalLabelToExternal(double lbl)` Maps internal representation of label to external.
    `boolean` | `isUpdateable(GDBModel mdl)`
    `protected abstract <V,K> boolean` | `learnLabels(DatasetBuilder<K,V> builder, Preprocessor<K,V> preprocessor)` Defines unique labels in dataset if need (useful in case of classification).
    `protected <K,V> GDBModel` | `updateModel(GDBModel mdl, DatasetBuilder<K,V> datasetBuilder, Preprocessor<K,V> preprocessor)` Gets state of model in arguments, update in according to new data and return new model.
    `GDBTrainer` | `withCheckConvergenceStgyFactory(ConvergenceCheckerFactory factory)` Sets CheckConvergenceStgyFactory.
    `GDBTrainer` | `withEnvironmentBuilder(LearningEnvironmentBuilder envBuilder)` Changes learning Environment.

    - ### Methods inherited from class org.apache.ignite.ml.trainers.DatasetTrainer

      `fit, fit, fit, fit, fit, fit, getLastTrainedModelOrThrowEmptyDatasetException, identityTrainer, learningEnvironment, update, update, update, update, update, withConvertedLabels`

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

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

- - ### Field Detail

    - #### loss

          protected final Loss loss

      Loss function.

    - #### checkConvergenceStgyFactory

          protected ConvergenceCheckerFactory checkConvergenceStgyFactory

      Check convergence strategy factory.

  - ### Constructor Detail

    - #### GDBTrainer

          public GDBTrainer(double gradStepSize,
                            Integer cntOfIterations,
                            Loss loss)

      Constructs GDBTrainer instance.
      Parameters:
        `gradStepSize` - Grad step size.
        `cntOfIterations` - Count of learning iterations.
        `loss` - Gradient of loss function. First argument is sample size, second argument is valid answer third argument is current model prediction.

  - ### Method Detail

    - #### fitWithInitializedDeployingContext

          public <K,V> GDBModel fitWithInitializedDeployingContext(DatasetBuilder<K,V> datasetBuilder,
                                                                   Preprocessor<K,V> preprocessor)

      Trains model based on the specified data.
      Specified by:
        `fitWithInitializedDeployingContext` in class `DatasetTrainer<GDBModel,Double>`
      Type Parameters:
        `K` - Type of a key in `upstream` data.
        `V` - Type of a value in `upstream` data.
      Parameters:
        `datasetBuilder` - Dataset builder.
        `preprocessor` - Extractor of `UpstreamEntry` into `LabeledVector`.
      Returns:
        Model.

    - #### updateModel

          protected <K,V> GDBModel updateModel(GDBModel mdl,
                                               DatasetBuilder<K,V> datasetBuilder,
                                               Preprocessor<K,V> preprocessor)

      Gets state of model in arguments, update in according to new data and return new model.
      Specified by:
        `updateModel` in class `DatasetTrainer<GDBModel,Double>`
      Type Parameters:
        `K` - Type of a key in `upstream` data.
        `V` - Type of a value in `upstream` data.
      Parameters:
        `mdl` - Learned model.
        `datasetBuilder` - Dataset builder.
        `preprocessor` - Extractor of `UpstreamEntry` into `LabeledVector`.
      Returns:
        Updated model.

    - #### isUpdateable

          public boolean isUpdateable(GDBModel mdl)

      Specified by:
        `isUpdateable` in class `DatasetTrainer<GDBModel,Double>`
      Parameters:
        `mdl` - Model.
      Returns:
        True if current critical for training parameters correspond to parameters from last training.

    - #### withEnvironmentBuilder

          public GDBTrainer withEnvironmentBuilder(LearningEnvironmentBuilder envBuilder)

      Changes learning Environment.
      Overrides:
        `withEnvironmentBuilder` in class `DatasetTrainer<GDBModel,Double>`
      Parameters:
        `envBuilder` - Learning environment builder.

    - #### learnLabels

          protected abstract <V,K> boolean learnLabels(DatasetBuilder<K,V> builder,
                                                       Preprocessor<K,V> preprocessor)

      Defines unique labels in dataset if need (useful in case of classification).
      Parameters:
        `builder` - Dataset builder.
        `preprocessor` - Upstream preprocessor.
      Returns:
        True if labels learning was successful.

    - #### buildBaseModelTrainer

          @NotNull
          protected abstract @NotNull DatasetTrainer<? extends IgniteModel<Vector,Double>,Double> buildBaseModelTrainer()

      Returns regressor model trainer for one step of GDB.

    - #### externalLabelToInternal

          protected abstract double externalLabelToInternal(double lbl)

      Maps external representation of label to internal.
      Parameters:
        `lbl` - Label value.

    - #### internalLabelToExternal

          protected abstract double internalLabelToExternal(double lbl)

      Maps internal representation of label to external.
      Parameters:
        `lbl` - Label value.

    - #### computeInitialValue

          protected <V,K,C extends Serializable> IgniteBiTuple<Double,Long> computeInitialValue(LearningEnvironmentBuilder envBuilder,
                                                                                                DatasetBuilder<K,V> builder,
                                                                                                Preprocessor<K,V> preprocessor)

      Compute mean value of label as first approximation.
      Parameters:
        `builder` - Dataset builder.
        `envBuilder` - Learning environment builder.
        `preprocessor` - Vectorizer.

    - #### withCheckConvergenceStgyFactory

          public GDBTrainer withCheckConvergenceStgyFactory(ConvergenceCheckerFactory factory)

      Sets CheckConvergenceStgyFactory.
      Parameters:
        `factory` - Factory.
      Returns:
        Trainer.

    - #### getLearningStrategy

          protected GDBLearningStrategy getLearningStrategy()

      Returns learning strategy.
      Returns:
        Learning strategy.

${current.year} Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.15.0
Release Date | : April 25 2023