Skip to content

Click in-app to access the full platform documentation for your version of DataRobot.

Prediction Explanations for models

Endpoint: /<projectId>/<modelId>/predictionExplanations

Warning

The /predApi/v1.0/<projectId>/<modelId>/predictionExplanations endpoint in the Prediction API is deprecated. With release v6.0, /predApi/v1.0/deployments/<deploymentId>/predictionExplanations will be the only supported endpoint for prediction servers. Contact your DataRobot representative if you need help migrating to the new API routes.

Makes predictions on a given deployment and provides explanations. To use this endpoint, you must have calculated the feature impact and initialized Prediction Explanations, which provide a qualitative indicator of the effect variables have on the predictions. (Prediction Explanations identify why a given model made a certain prediction.)

Note

Prediction Explanations cannot be generated for multiclass projects.

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 Required for Managed AI Cloud users; string type 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

Datarobot-key: This header is required only with Managed AI Cloud. It is used as a precaution to secure user data from other verified DataRobot users.

Additional parameters

Key Description Example(s)
maxExplanations Optional; integer type

Limits the number of explanations returned by server. Previously called maxCodes.
?maxExplanations=5
thresholdHigh Optional; number type

The prediction explanation high threshold. Predictions must be above this value (or below the 'thresholdLow' value) to have PredictionExplanations computed.
?thresholdHigh=0.805
thresholdLow Optional; number type

The prediction explanation low threshold. Predictions must be below this value (or above the 'thresholdHigh' value) to have PredictionExplanations computed.
?thresholdLow=0.1396484375
excludeAdjustedPredictions Optional; string type

If True (the default), adjusted predictions are included in the PredictionExplanationsSample response.
?excludeAdjustedPredictions=false
passthroughColumns Optional; string type

Controls which columns from a scoring dataset to expose (or to copy over) in a prediction response.

The request may contain zero, one, or more columns. (There’s no limit on how many column names you can pass.) Column names must be passed as UTF-8 bytes and must be percent-encoded (see the HTTP standard on this requirement). Make sure to use the actual name of a column as a value.
/v1.0/:projectId/:modelId/predictionExplanations?passthroughColumns=colA&passthroughColumns=colB
passthroughColumnsSet Optional; string type

Controls which columns from a scoring dataset to expose (or to copy over) in a prediction response. The only possible option is “all” and, if passed, all columns from a scoring dataset are exposed.
/v1.0/:projectId/:modelId/predictionExplanations?passthroughColumnsSet=all

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

"qualitativeStrength" indicator

The "qualitativeStrength" indicates how important the feature was when making the current predictions, based on feature impact calculations.

This indicator... Means...
+++ 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.

Binary prediction 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
                }
            ]
        }
    ]
}

Errors List

HTTP Code Sample error message Reason(s)
400 BAD REQUEST {"message": "Model :modelId not found"} Provided an invalid :modelId or provided model is from a different project.
404 NOT FOUND {"message": "Not found"} Provided an invalid :projectId (deleted project).
404 NOT FOUND {"message": "Bad request"} Provided the wrong format for :projectId or :modelId.
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 threshol\_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 timeSeriesPredict route instead."} Provided the projectId and modelId of a time series project, which are 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.

Updated September 2, 2021
Back to top