Skip to content

On-premise users: click in-app to access the full platform documentation for your version of DataRobot.

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.

Updated February 16, 2024