[DOCS] Add feature_importance_baseline to get trained model API (#63279)

Co-authored-by: Benjamin Trent <ben.w.trent@gmail.com>

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

@@ -37,6 +37,7 @@ public class GetTrainedModelsRequest implements Validatable {
 
     private static final String DEFINITION = "definition";
     private static final String TOTAL_FEATURE_IMPORTANCE = "total_feature_importance";
+    private static final String FEATURE_IMPORTANCE_BASELINE = "feature_importance_baseline";
     public static final String ALLOW_NO_MATCH = "allow_no_match";
     public static final String FOR_EXPORT = "for_export";
     public static final String DECOMPRESS_DEFINITION = "decompress_definition";
@@ -105,6 +106,11 @@ public class GetTrainedModelsRequest implements Validatable {
         return this;
     }
 
+    public GetTrainedModelsRequest includeFeatureImportanceBaseline() {
+        this.includes.add(FEATURE_IMPORTANCE_BASELINE);
+        return this;
+    }
+
     /**
      * Whether to include the full model definition.
      *

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

@@ -3721,10 +3721,11 @@ public class MlClientDocumentationIT extends ESRestHighLevelClientTestCase {
                 .setPageParams(new PageParams(0, 1)) // <2>
                 .includeDefinition() // <3>
                 .includeTotalFeatureImportance() // <4>
-                .setDecompressDefinition(false) // <5>
-                .setAllowNoMatch(true) // <6>
-                .setTags("regression") // <7>
-                .setForExport(false); // <8>
+                .includeFeatureImportanceBaseline() // <5>
+                .setDecompressDefinition(false) // <6>
+                .setAllowNoMatch(true) // <7>
+                .setTags("regression") // <8>
+                .setForExport(false); // <9>
             // end::get-trained-models-request
             request.setTags((List<String>)null);
 

docs/java-rest/high-level/ml/get-trained-models.asciidoc

@@ -22,19 +22,21 @@ IDs, or the special wildcard `_all` to get all trained models.
 --------------------------------------------------
 include-tagged::{doc-tests-file}[{api}-request]
 --------------------------------------------------
-<1> Constructing a new GET request referencing an existing trained model
-<2> Set the paging parameters
-<3> Indicate if the complete model definition should be included
+<1> Constructing a new GET request referencing an existing trained model.
+<2> Set the paging parameters.
+<3> Indicate if the complete model definition should be included.
 <4> Indicate if the total feature importance for the features used in training
-    should be included in the model `metadata` field.
-<5> Should the definition be fully decompressed on GET
-<6> Allow empty response if no trained models match the provided ID patterns.
+    should is included in the metadata.
+<5> Indicate if the feature importance baselines that were used in training are
+    included in the metadata.
+<6> Should the definition be fully decompressed on GET.
+<7> Allow empty response if no trained models match the provided ID patterns.
     If false, an error will be thrown if no trained models match the
     ID patterns.
-<7> An optional list of tags used to narrow the model search. A trained model
+<8> An optional list of tags used to narrow the model search. A trained model
     can have many tags or none. The trained models in the response will
     contain all the provided tags.
-<8> Optional boolean value for requesting the trained model in a format that can
+<9> Optional boolean value for requesting the trained model in a format that can
     then be put into another cluster. Certain fields that can only be set when
     the model is imported are removed.
 

docs/reference/ml/df-analytics/apis/get-trained-models.asciidoc

@@ -75,13 +75,15 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=from-models]
 
 `include`::
 (Optional, string)
-A comma delimited string of optional fields to include in the response body.
-Valid options are:
+A comma delimited string of optional fields to include in the response body. The
+default value is empty, indicating no optional fields are included. Valid
+options are:
  - `definition`: Includes the model definition
- - `total_feature_importance`: Includes the total feature importance for the
-   training data set. This field is available in the `metadata` field in the
-   response body.
-Default is empty, indicating including no optional fields.
+ - `feature_importance_baseline`: Includes the baseline for {feat-imp} values.
+ - `total_feature_importance`: Includes the total {feat-imp} for the training
+   data set.
+The baseline and total {feature-imp} values are returned in the `metadata` field
+in the response body.
 
 `size`::
 (Optional, integer)
@@ -141,14 +143,19 @@ created by {dfanalytics} contain `analysis_config` and `input` objects.
 .Properties of metadata
 [%collapsible%open]
 =====
+`feature_importance_baseline`:::
+(object)
+An object that contains the baseline for {feat-imp} values. For {reganalysis},
+it is a single value. For {classanalysis}, there is a value for each class.
+
 `total_feature_importance`:::
 (array)
-An array of the total feature importance for each feature used from
+An array of the total {feat-imp} for each feature used from
 the training data set. This array of objects is returned if {dfanalytics} trained
 the model and the request includes `total_feature_importance` in the `include`
 request parameter.
 +
-.Properties of total feature importance
+.Properties of total {feat-imp}
 [%collapsible%open]
 ======
 
@@ -158,9 +165,9 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-impo
 
 `importance`:::
 (object)
-A collection of feature importance statistics related to the training data set for this particular feature.
+A collection of {feat-imp} statistics related to the training data set for this particular feature.
 +
-.Properties of feature importance
+.Properties of {feat-imp}
 [%collapsible%open]
 =======
 `mean_magnitude`:::
@@ -179,10 +186,10 @@ include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=inference-metadata-feature-impo
 
 `classes`:::
 (array)
-If the trained model is a classification model, feature importance statistics are gathered
+If the trained model is a classification model, {feat-imp} statistics are gathered
 per target class value.
 +
-.Properties of class feature importance
+.Properties of class {feat-imp}
 [%collapsible%open]
 
 =======
@@ -193,9 +200,9 @@ The target class value. Could be a string, boolean, or number.
 
 `importance`:::
 (object)
-A collection of feature importance statistics related to the training data set for this particular feature.
+A collection of {feat-imp} statistics related to the training data set for this particular feature.
 +
-.Properties of feature importance
+.Properties of {feat-imp}
 [%collapsible%open]
 ========
 `mean_magnitude`:::