<commit_before>[role="xpack"]
[testenv="platinum"]
[[explain-dfanalytics]]
=== Explain {dfanalytics} API

[subs="attributes"]
++++
<titleabbrev>Explain {dfanalytics} API</titleabbrev>
++++

Explains a {dataframe-analytics-config}.

experimental[]


[[ml-explain-dfanalytics-request]]
==== {api-request-title}

`GET _ml/data_frame/analytics/_explain` +

`POST _ml/data_frame/analytics/_explain` +

`GET _ml/data_frame/analytics/<data_frame_analytics_id>/_explain` +

`POST _ml/data_frame/analytics/<data_frame_analytics_id>/_explain`


[[ml-explain-dfanalytics-prereq]]
==== {api-prereq-title}

If the {es} {security-features} are enabled, you must have the following 
privileges:

* cluster: `monitor_ml`
  
For more information, see <<security-privileges>> and <<built-in-roles>>.


[[ml-explain-dfanalytics-desc]]
==== {api-description-title}

This API provides explanations for a {dataframe-analytics-config} that either 
exists already or one that has not been created yet.
The following explanations are provided:

* which fields are included or not in the analysis and why,
* how much memory is estimated to be required. The estimate can be used when 
  deciding the appropriate value for `model_memory_limit` setting later on.

If you have object fields or fields that are excluded via source filtering,
they are not included in the explanation.


[[ml-explain-dfanalytics-path-params]]
==== {api-path-parms-title}

`<data_frame_analytics_id>`::
(Optional, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics]


[[ml-explain-dfanalytics-request-body]]
==== {api-request-body-title}

`data_frame_analytics_config`::
  (Optional, object) Intended configuration of {dfanalytics-job}. Note that `id` 
  and `dest` don't need to be provided in the context of this API.


[[ml-explain-dfanalytics-results]]
==== {api-response-body-title}

The API returns a response that contains the following:

`field_selection`::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=field-selection]

`memory_estimation`::
(object) 
include::{docdir}/ml/ml-shared.asciidoc[tag=memory-estimation]


[[ml-explain-dfanalytics-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
POST _ml/data_frame/analytics/_explain
{
  "data_frame_analytics_config": {
    "source": {
      "index": "houses_sold_last_10_yrs"
    },
    "analysis": {
      "regression": {
        "dependent_variable": "price"
      }
    }
  }
}
--------------------------------------------------
// TEST[skip:TBD]


The API returns the following results:

[source,console-result]
----
{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": ["integer"],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",<commit_msg>[ML] Fix DF analytics explain API request in docs (#54510)<commit_after>[role="xpack"]
[testenv="platinum"]
[[explain-dfanalytics]]
=== Explain {dfanalytics} API

[subs="attributes"]
++++
<titleabbrev>Explain {dfanalytics} API</titleabbrev>
++++

Explains a {dataframe-analytics-config}.

experimental[]


[[ml-explain-dfanalytics-request]]
==== {api-request-title}

`GET _ml/data_frame/analytics/_explain` +

`POST _ml/data_frame/analytics/_explain` +

`GET _ml/data_frame/analytics/<data_frame_analytics_id>/_explain` +

`POST _ml/data_frame/analytics/<data_frame_analytics_id>/_explain`


[[ml-explain-dfanalytics-prereq]]
==== {api-prereq-title}

If the {es} {security-features} are enabled, you must have the following 
privileges:

* cluster: `monitor_ml`
  
For more information, see <<security-privileges>> and <<built-in-roles>>.


[[ml-explain-dfanalytics-desc]]
==== {api-description-title}

This API provides explanations for a {dataframe-analytics-config} that either 
exists already or one that has not been created yet.
The following explanations are provided:

* which fields are included or not in the analysis and why,
* how much memory is estimated to be required. The estimate can be used when 
  deciding the appropriate value for `model_memory_limit` setting later on.

If you have object fields or fields that are excluded via source filtering,
they are not included in the explanation.


[[ml-explain-dfanalytics-path-params]]
==== {api-path-parms-title}

`<data_frame_analytics_id>`::
(Optional, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics]


[[ml-explain-dfanalytics-request-body]]
==== {api-request-body-title}

A {dataframe-analytics-config} as described in <<put-dfanalytics>>.
Note that `id` and `dest` don't need to be provided in the context of this API.


[[ml-explain-dfanalytics-results]]
==== {api-response-body-title}

The API returns a response that contains the following:

`field_selection`::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=field-selection]

`memory_estimation`::
(object) 
include::{docdir}/ml/ml-shared.asciidoc[tag=memory-estimation]


[[ml-explain-dfanalytics-example]]
==== {api-examples-title}

[source,console]
--------------------------------------------------
POST _ml/data_frame/analytics/_explain
{
  "source": {
    "index": "houses_sold_last_10_yrs"
  },
  "analysis": {
    "regression": {
      "dependent_variable": "price"
    }
  }
}
--------------------------------------------------
// TEST[skip:TBD]


The API returns the following results:

[source,console-result]
----
{
  "field_selection": [
    {
      "field": "number_of_bedrooms",
      "mappings_types": ["integer"],
      "is_included": true,
      "is_required": false,
      "feature_type": "numerical"
    },
    {
      "field": "postcode",
{'fraction_non_alphanumeric': 0.1760154738878143, 'fraction_numerical': 0.0015825567082820467, 'mean_word_length': 3.89922480620155, 'pattern_counts': {'":': 25, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7249236', 'n_tokens_mistral': 1905, 'n_tokens_neox': 1855, 'n_words': 424}