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:
|
|
| Content-Type | Optional; string type |
|
| 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. |
|
| 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 |
|
|
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. |