DataRobot API resources > API reference documentation > DataRobot Prediction API > Dedicated Prediction API reference > Prediction Explanations for deployment

Prediction Explanations for deployments¶

Endpoint: /deployments/<deploymentId>/predictions?maxExplanations=<number>

Prediction Explanations identify why a given model makes a certain prediction. To calculate Prediction Explanations, use the same endpoint used for calculating bare predictions with the maxExplanations URI parameter set to a positive integer value.

Prediction Explanations can be either:

XEMP-based (the default). To use XEMP-based explanations, first calculate feature impact and initialize Prediction Explanations to provide a qualitative indicator (qualitativeStrength) of the effect variables have on the predictions. Explanations are computed for the top 50 features, ranked by feature impact scores (not including features with zero feature impact).
SHAP-based if the Include only models with SHAP value support advanced option is enabled prior to model building. Calculating feature impact is not required; note that the qualitativeStrength indicator is not available for SHAP.

XEMP- and SHAP-based explanations are mutually exclusive—a model cannot have both XEMP and SHAP explanations. See the Prediction Explanations full documentation for specific calculation information.

Note the following:

SHAP-based explanations are not available for time series or custom models.
Neither XEMP or SHAP explanations are available for images (that is, no Image Explanations).

Performance considerations for XEMP-based explanations

XEMP-based explanations can be 100x slower than regular predictions. Avoid them for low-latency critical use cases. SHAP-based explanations are much faster but can add some latency too.

Multiclass support

Prediction Explanations cannot be generated for XEMP- or SHAP-based multiclass projects. More information to consider while working with explanations can be found here.

Request Method: POST

Request URL: deployed URL, for example: https://your-company.orm.datarobot.com/predApi/v1.0

Request parameters¶

Headers¶

Key	Description	Example(s)
Datarobot-key	A per-organization secret used as an additional authentication factor for prediction servers. Retrieve a `datarobot-key` programmatically by accessing the `/api/v2/predictionServers` endpoint. The endpoint returns a URL to a prediction server and a corresponding `datarobot-key`. Required for Self-Managed AI Platform users; string type Once a model is deployed, see the code snippet in the DataRobot UI, Predictions > Prediction API.	`DR-key-12345abcdb-xyz6789`
Authorization	Required; string Three methods are supported: Bearer authentication (deprecated) Basic authentication: User_email and API token (deprecated) API token	Example for Bearer authentication method: `Bearer API_key-12345abcdb-xyz6789` (deprecated) Example for User_email and API token method: `Basic Auth_basic-12345abcdb-xyz6789` (deprecated) Example for API token method: `Token API_key-12345abcdb-xyz6789`
Content-Type	Optional; string type	textplain; charset=UTF-8 text/csv application/JSON multipart/form-data (For files with data, i.e., .csv, .txt files)
Content-Encoding	Optional; string type Currently supports only gzip-encoding with the default data extension.	gzip

Datarobot-key: This header is required only with the managed AI Platform. It is used as a precaution to secure user data from other verified DataRobot users. The key can also be retrieved with the following request to DataRobot API:
GET <URL>/api/v2/modelDeployments/<deploymentId>

Query arguments (explanations specific)¶

Note

To trigger prediction explanations, your request must send maxExplanations=N where N is greater than 0.

Key	Type	Description	Example(s)
maxExplanations	int OR string	(Optional) Limits the number of explanations returned by server. Previously called `maxCodes` (deprecated). For SHAP explanations only a special constant `all` is also accepted.	`?maxExplanations=5` `?maxExplanations=all`
thresholdLow	float	(Optional) The lower threshold for requiring a Prediction Explanation. Predictions must be below this value (or above the thresholdHigh value) for Prediction Explanations to compute.	`?thresholdLow=0.678`
thresholdHigh	float	(Optional) The upper threshold for requiring a Prediction Explanation. Predictions must be above this value (or below the thresholdLow value) for Prediction Explanations to compute.	`?thresholdHigh=0.345`
excludeAdjustedPredictions	bool	(Optional) Includes or excludes exposure-adjusted predictions in prediction responses if exposure was used during model building. The default value is `true` (exclude exposure-adjusted predictions).	`?excludeAdjustedPredictions=true`
explanationNumTopClasses	int	(Optional) This argument is only for multiclass model explanations and it is mutually exclusive with `explanationClassNames`. The number of top predicted classes to explain for each row. The default value is `1`.	`?explanationNumTopClasses=5`
explanationClassNames	list of string types	(Optional) This argument is only for multiclass model explanations and it is mutually exclusive with `explanationNumTopClasses`. A list of class names to explain for each row. Class names must be passed as UTF-8 bytes and must be percent-encoded (see the HTTP standard for this requirement). By default, `explanationNumTopClasses=1` is assumed.	`?explanationClassNames=classA&explanationClassNames=classB`

The rest of the parameters like passthroughColumns, passthroughColumnsSet, and predictionWarningEnabled can also be used with Prediction Explanations.

Body¶

Data	Type	Example(s)
Data to predict	raw text form-data	PassengerId,Pclass,Name,Sex,Age,SibSp,Parch,Ticket,Fare,Cabin,Embarked 892,3,"Kelly, Mr. James",male,34.5,0,0,330911,7.8292,,Q 893,3,"Wilkes, Mrs. James (Ellen Needs)",female,47,1,0,363272,7,,S 894,2,"Myles, Mr. Thomas Francis",male,62,0,0,240276,9.6875,,Q Key: file, value: file_with_data_to_predict.csv

Response 200¶

Binary XEMP-based explanation response example¶


{
    "data": [
        {
            "predictionValues": [
                {
                    "value": 0.07836511,
                    "label": 1
                },
                {
                    "value": 0.92163489,
                    "label": 0
                }
            ],
            "predictionThreshold": 0.5,
            "prediction": 0,
            "rowId": 0,
            "predictionExplanations": [
                {
                    "featureValue": "male",
                    "strength": -0.6706725349,
                    "feature": "Sex",
                    "qualitativeStrength": "---",
                    "label": 1
                },
                {
                    "featureValue": 62,
                    "strength": -0.6325465255,
                    "feature": "Age",
                    "qualitativeStrength": "---",
                    "label": 1
                },
                {
                    "featureValue": 9.6875,
                    "strength": -0.353000328,
                    "feature": "Fare",
                    "qualitativeStrength": "--",
                    "label": 1
                }
            ]
        }
    ]
}

Binary SHAP-based explanation response example¶


{
   "data":[
      {
         "deploymentApprovalStatus": "APPROVED",
         "prediction": 0.0,
         "predictionExplanations": [
            {
               "featureValue": "9",
               "strength": 0.0534648234,
               "qualitativeStrength": null,
               "feature": "number_diagnoses",
               "label": 1
            },
            {
               "featureValue": "0",
               "strength": -0.0490243586,
               "qualitativeStrength": null,
               "feature": "number_inpatient",
               "label": 1
            }
         ],
         "rowId": 0,
         "predictionValues": [
            {
               "value": 0.3111782477,
               "label": 1
            },
            {
               "value": 0.6888217523,
               "label": 0.0
            }
         ],
         "predictionThreshold": 0.5,
         "shapExplanationsMetadata": {
            "warnings": null,
            "remainingTotal": -0.089668474,
            "baseValue": 0.3964062631
         }
      }
   ]
}

"qualitativeStrength" indicator¶

The "qualitativeStrength" indicates the effect of the feature's value on predictions, based on XEMP calculations. The following table provides an example for a model with two features. See the XEMP calculation reference for full calculation details.

Note

This response is an XEMP-only feature.

Indicator...	Description
+++	Absolute score is > 0.75 and feature has positive impact.
---	Absolute score is > 0.75 and feature has negative impact.
++	Absolute score is between (0.25, 0.75) and feature has positive impact.
--	Absolute score is between (0.25, 0.75) and feature has negative impact.
+	Absolute score is between (0.001, 0.25) and feature has positive impact.
-	Absolute score is between (0.001, 0.25) and feature has negative impact.
<+	Absolute score is between (0, 0.001) and feature has positive impact.
<-	Absolute score is between (0, 0.001) and feature has negative impact.

Errors List¶

HTTP Code	Sample error message	Reason(s)
404 NOT FOUND	`{"message": "Not found"}`	Provided an invalid :deploymentId (deleted deployment).
404 NOT FOUND	`{"message": "Bad request"}`	Provided the wrong format for :deploymentId.
422 UNPROCESSABLE ENTITY	`{"message": "{'max_codes': DataError(value can't be converted to int)}"}`	Provided `maxCodes` parameter in unsupported data type (i.e., non-integer values).
422 UNPROCESSABLE ENTITY	`{"message": "{'threshold_high': DataError(value can't be converted to float)}"}`	Provided `threshold_high` parameter in unsupported data type (i.e., non-integer values).
422 UNPROCESSABLE ENTITY	`{"message": "{'threshold_low': DataError(value can't be converted to float)}"}`	Provided `threshold_low` parameter in unsupported data type (i.e., non-integer values).
422 UNPROCESSABLE ENTITY	`{"message": "Multiclass models cannot be used for Prediction Explanations"}`	Provided a multiclass classification problem dataset, which is not supported for this endpoint.
422 UNPROCESSABLE ENTITY	`{"message": "This endpoint does not support predictions on time series models. Please use the timeSeriesPredictions route instead."}`	Provided the deploymentId of a time series project, which is not supported for this endpoint.
422 UNPROCESSABLE ENTITY	`{"message": "{'exclude\_adjusted\_predictions': DataError(value can't be converted to Bool)}"}`	Sent an empty or non-Boolean value with the `excludeAdjustedPredictions` parameter.
422 UNPROCESSABLE ENTITY	`{"message": "'predictionWarningEnabled': value can't be converted to Bool"}`	Provided an invalid (non-boolean) value for `predictionWarningEnabled` parameter.

Was this page helpful?

Great! Let us know what you found helpful.

What can we do to improve the content?

Thanks for your feedback!