Add num_top_classes parameter to HLRC

Document this parameter in HLRC docs

Author: przemekwitek

client/rest-high-level/src/main/java/org/elasticsearch/client/ml/dataframe/Classification.java

@@ -48,6 +48,7 @@ public static Builder builder(String dependentVariable) {
     static final ParseField FEATURE_BAG_FRACTION = new ParseField("feature_bag_fraction");
     static final ParseField PREDICTION_FIELD_NAME = new ParseField("prediction_field_name");
     static final ParseField TRAINING_PERCENT = new ParseField("training_percent");
+    static final ParseField NUM_TOP_CLASSES = new ParseField("num_top_classes");
 
     private static final ConstructingObjectParser<Classification, Void> PARSER =
         new ConstructingObjectParser<>(
@@ -61,7 +62,8 @@ public static Builder builder(String dependentVariable) {
                 (Integer) a[4],
                 (Double) a[5],
                 (String) a[6],
-                (Double) a[7]));
+                (Double) a[7],
+                (Integer) a[8]));
 
     static {
         PARSER.declareString(ConstructingObjectParser.constructorArg(), DEPENDENT_VARIABLE);
@@ -72,6 +74,7 @@ public static Builder builder(String dependentVariable) {
         PARSER.declareDouble(ConstructingObjectParser.optionalConstructorArg(), FEATURE_BAG_FRACTION);
         PARSER.declareString(ConstructingObjectParser.optionalConstructorArg(), PREDICTION_FIELD_NAME);
         PARSER.declareDouble(ConstructingObjectParser.optionalConstructorArg(), TRAINING_PERCENT);
+        PARSER.declareInt(ConstructingObjectParser.optionalConstructorArg(), NUM_TOP_CLASSES);
     }
 
     private final String dependentVariable;
@@ -82,10 +85,11 @@ public static Builder builder(String dependentVariable) {
     private final Double featureBagFraction;
     private final String predictionFieldName;
     private final Double trainingPercent;
+    private final Integer numTopClasses;
 
     private Classification(String dependentVariable, @Nullable Double lambda, @Nullable Double gamma, @Nullable Double eta,
                            @Nullable Integer maximumNumberTrees, @Nullable Double featureBagFraction, @Nullable String predictionFieldName,
-                           @Nullable Double trainingPercent) {
+                           @Nullable Double trainingPercent, @Nullable Integer numTopClasses) {
         this.dependentVariable = Objects.requireNonNull(dependentVariable);
         this.lambda = lambda;
         this.gamma = gamma;
@@ -94,6 +98,7 @@ private Classification(String dependentVariable, @Nullable Double lambda, @Nulla
         this.featureBagFraction = featureBagFraction;
         this.predictionFieldName = predictionFieldName;
         this.trainingPercent = trainingPercent;
+        this.numTopClasses = numTopClasses;
     }
 
     @Override
@@ -133,6 +138,10 @@ public Double getTrainingPercent() {
         return trainingPercent;
     }
 
+    public Integer getNumTopClasses() {
+        return numTopClasses;
+    }
+
     @Override
     public XContentBuilder toXContent(XContentBuilder builder, Params params) throws IOException {
         builder.startObject();
@@ -158,14 +167,17 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
         if (trainingPercent != null) {
             builder.field(TRAINING_PERCENT.getPreferredName(), trainingPercent);
         }
+        if (numTopClasses != null) {
+            builder.field(NUM_TOP_CLASSES.getPreferredName(), numTopClasses);
+        }
         builder.endObject();
         return builder;
     }
 
     @Override
     public int hashCode() {
         return Objects.hash(dependentVariable, lambda, gamma, eta, maximumNumberTrees, featureBagFraction, predictionFieldName,
-            trainingPercent);
+            trainingPercent, numTopClasses);
     }
 
     @Override
@@ -180,7 +192,8 @@ public boolean equals(Object o) {
             && Objects.equals(maximumNumberTrees, that.maximumNumberTrees)
             && Objects.equals(featureBagFraction, that.featureBagFraction)
             && Objects.equals(predictionFieldName, that.predictionFieldName)
-            && Objects.equals(trainingPercent, that.trainingPercent);
+            && Objects.equals(trainingPercent, that.trainingPercent)
+            && Objects.equals(numTopClasses, that.numTopClasses);
     }
 
     @Override
@@ -197,6 +210,7 @@ public static class Builder {
         private Double featureBagFraction;
         private String predictionFieldName;
         private Double trainingPercent;
+        private Integer numTopClasses;
 
         private Builder(String dependentVariable) {
             this.dependentVariable = Objects.requireNonNull(dependentVariable);
@@ -237,9 +251,14 @@ public Builder setTrainingPercent(Double trainingPercent) {
             return this;
         }
 
+        public Builder setNumTopClasses(Integer numTopClasses) {
+            this.numTopClasses = numTopClasses;
+            return this;
+        }
+
         public Classification build() {
             return new Classification(dependentVariable, lambda, gamma, eta, maximumNumberTrees, featureBagFraction, predictionFieldName,
-                trainingPercent);
+                trainingPercent, numTopClasses);
         }
     }
 }

client/rest-high-level/src/test/java/org/elasticsearch/client/MachineLearningIT.java

@@ -1266,8 +1266,7 @@ public void testPutDataFrameAnalyticsConfig_GivenRegression() throws Exception {
             .setDest(DataFrameAnalyticsDest.builder()
                 .setIndex("put-test-dest-index")
                 .build())
-            .setAnalysis(org.elasticsearch.client.ml.dataframe.Regression
-                .builder("my_dependent_variable")
+            .setAnalysis(org.elasticsearch.client.ml.dataframe.Regression.builder("my_dependent_variable")
                 .setTrainingPercent(80.0)
                 .build())
             .setDescription("this is a regression")
@@ -1301,9 +1300,9 @@ public void testPutDataFrameAnalyticsConfig_GivenClassification() throws Excepti
             .setDest(DataFrameAnalyticsDest.builder()
                 .setIndex("put-test-dest-index")
                 .build())
-            .setAnalysis(org.elasticsearch.client.ml.dataframe.Classification
-                .builder("my_dependent_variable")
+            .setAnalysis(org.elasticsearch.client.ml.dataframe.Classification.builder("my_dependent_variable")
                 .setTrainingPercent(80.0)
+                .setNumTopClasses(1)
                 .build())
             .setDescription("this is a classification")
             .build();

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/MlClientDocumentationIT.java

@@ -2951,6 +2951,7 @@ public void testPutDataFrameAnalytics() throws Exception {
                 .setFeatureBagFraction(0.4) // <6>
                 .setPredictionFieldName("my_prediction_field_name") // <7>
                 .setTrainingPercent(50.0) // <8>
+                .setNumTopClasses(1) // <9>
                 .build();
             // end::put-data-frame-analytics-classification
 

client/rest-high-level/src/test/java/org/elasticsearch/client/ml/dataframe/ClassificationTests.java

@@ -34,6 +34,7 @@ public static Classification randomClassification() {
             .setFeatureBagFraction(randomBoolean() ? null : randomDoubleBetween(0.0, 1.0, false))
             .setPredictionFieldName(randomBoolean() ? null : randomAlphaOfLength(10))
             .setTrainingPercent(randomBoolean() ? null : randomDoubleBetween(1.0, 100.0, true))
+            .setNumTopClasses(randomBoolean() ? null : randomIntBetween(0, 10))
             .build();
     }
 

docs/java-rest/high-level/ml/put-data-frame-analytics.asciidoc

@@ -118,6 +118,7 @@ include-tagged::{doc-tests-file}[{api}-classification]
 <6> The fraction of features which will be used when selecting a random bag for each candidate split. A double in (0, 1].
 <7> The name of the prediction field in the results object.
 <8> The percentage of training-eligible rows to be used in training. Defaults to 100%.
+<9> The number of top classes to be reported in the results. Defaults to 2.
 
 ===== Regression