Add evaluation metrics descriptions

Author: przemekwitek

docs/reference/ml/df-analytics/apis/evaluate-dfanalytics.asciidoc

@@ -42,31 +42,32 @@ result field to be present.
 [[ml-evaluate-dfanalytics-request-body]]
 ==== {api-request-body-title}
 
+`index`::
+(Required, object) Defines the `index` in which the evaluation will be
+performed.
+
+`query`::
+(Optional, object) A query clause that retrieves a subset of data from the
+source index. See <<query-dsl>>.
+
 `evaluation`::
-(Required, object) Defines the type of evaluation you want to perform. The 
-value of this object can be different depending on the type of evaluation you 
-want to perform. See <<ml-evaluate-dfanalytics-resources>>.
+(Required, object) Defines the type of evaluation you want to perform.
+See <<ml-evaluate-dfanalytics-resources>>.
 +
 --
 Available evaluation types:
+
 * `binary_soft_classification`
 * `regression`
 * `classification`
---
 
-`index`::
-(Required, object) Defines the `index` in which the evaluation will be
-performed.
-
-`query`::
-(Optional, object) A query clause that retrieves a subset of data from the 
-source index. See <<query-dsl>>.
+--
 
 [[ml-evaluate-dfanalytics-resources]]
 ==== {dfanalytics-cap} evaluation resources
 
 [[binary-sc-resources]]
-===== Binary soft classification configuration objects
+===== Binary soft classification evaluation objects
 
 Binary soft classification evaluates the results of an analysis which outputs 
 the probability that each document belongs to a certain class. For example, in 
@@ -87,20 +88,20 @@ document is an outlier.
   (Optional, object) Specifies the metrics that are used for the evaluation. 
   Available metrics:
 
-  `auc_roc`::
+  `auc_roc`:::
     (Optional, object) The AUC ROC (area under the curve of the receiver 
     operating characteristic) score and optionally the curve. Default value is 
     {"includes_curve": false}.
 
-  `precision`::
+  `precision`:::
     (Optional, object) Set the different thresholds of the {olscore} at where 
     the metric is calculated. Default value is {"at": [0.25, 0.50, 0.75]}.
 
-  `recall`::
+  `recall`:::
     (Optional, object) Set the different thresholds of the {olscore} at where 
     the metric is calculated. Default value is {"at": [0.25, 0.50, 0.75]}.
 
-  `confusion_matrix`::
+  `confusion_matrix`:::
     (Optional, object) Set the different thresholds of the {olscore} at where 
     the metrics (`tp` - true positive, `fp` - false positive, `tn` - true 
     negative, `fn` - false negative) are calculated. Default value is 
@@ -122,9 +123,18 @@ which outputs a prediction of values.
   in other words the results of the {regression} analysis.
 
 `metrics`::
-  (Required, object) Specifies the metrics that are used for the evaluation. 
-  Available metrics are `r_squared` and `mean_squared_error`.
-  
+  (Optional, object) Specifies the metrics that are used for the evaluation.
+  Available metrics:
+
+  `mean_squared_error`:::
+    (Optional, object) Average squared difference between the predicted values and the actual (`ground truth`) value.
+    Read more on https://en.wikipedia.org/wiki/Mean_squared_error[Wikipedia]
+
+  `r_squared`:::
+    (Optional, object) Proportion of the variance in the dependent variable that is predictable from the independent variables.
+    Read more on https://en.wikipedia.org/wiki/Coefficient_of_determination[Wikipedia]
+
+
 
 [[classification-evaluation-resources]]
 ==== {classification-cap} evaluation objects
@@ -134,8 +144,8 @@ outputs a prediction that identifies to which of the classes each document
 belongs.
 
 `actual_field`::
-  (Required, string) The field of the `index` which contains the ground truth. 
-  The data type of this field must be keyword.
+  (Required, string) The field of the `index` which contains the `ground truth`.
+  The data type of this field must be categorical.
 
 `predicted_field`::
   (Required, string) The field in the `index` that contains the predicted value, 
@@ -146,8 +156,20 @@ belongs.
   example, `predicted_field` : `ml.animal_class_prediction.keyword`.
 
 `metrics`::
-  (Required, object) Specifies the metrics that are used for the evaluation.
-  Available metric is `multiclass_confusion_matrix`.
+  (Optional, object) Specifies the metrics that are used for the evaluation.
+  Available metrics:
+
+  `accuracy`:::
+    (Optional, object) Accuracy of predictions (per-class and overall)
+
+  `precision`:::
+    (Optional, object) Precision of predictions (per-class and average)
+
+  `recall`:::
+    (Optional, object) Recall of predictions (per-class and average)
+
+  `multiclass_confusion_matrix`:::
+    (Optional, object) Multiclass confusion matrix
 
 
 ////