Explanations generation

In this section, we share endpoints used to generate explanations. A model and an input sample are required.

get
List allowed explanations

https://api.expai.io/api/explain/get_allowed
EXPAI implements several types of explanations. This endpoint returns all available techniques including a summary and preview.
Request
Response
Request
Headers
access-token
required
string
Active JWT token
Content-Type
required
string
Value: "application/json"
Response
200: OK
{
"code": "success",
"explanations": [
{
"explanation_image_path": "publicIP/static/images/explanations/model_explanation.jpg",
"explanation_type_des": "Explicación del modelo",
"explanation_summary_des": "Muestra la contribución media absoluta de cada variable del modelo sobre la predicción. Usa un dataset completo o una parte de él.",
"explanation_type_id": 1
},
{
"explanation_image_path": "publicIP/static/images/explanations/variable_explanation.jpg",
"explanation_type_des": "Explicación de la variable",
"explanation_summary_des": "Representa el valor de la predicción en función de una variable de interés. Permite comprender cómo los diferentes valores influyen sobre la predicción.",
"explanation_type_id": 2
},
{
"explanation_image_path": "publicIP/static/images/explanations/sample_explanation.jpg",
"explanation_type_des": "Explicación de la muestra",
"explanation_summary_des": "Representa el impacto que cada variable ha tenido sobre la predicción de una determinada muestra. Permite entender cada predicción que realice el modelo.",
"explanation_type_id": 3
},
{
"explanation_image_path": "publicURL/static/images/explanations/what_if_explanation.jpg",
"explanation_type_des": "What If",
"explanation_summary_des": "Permite definir el impacto que tendría sobre la predicción del modelo, para una muestra determinada, el cambio del valor de una o más variables.",
"explanation_type_id": 4
},
{
"explanation_image_path": "publicURL/static/images/explanations/what_if_battle_explanation.jpg",
"explanation_type_des": "What If Battle",
"explanation_summary_des": "Permite visualizar la explicación de una muestra determinada y el impacto que tendría sobre la predicción la modificación del valor de alguna de las variables.",
"explanation_type_id": 5
}
],
"http_code": 200,
"message": "success"
}

post
Model Explanation

https://api.expai.io/api/explain/<model_id>/graphics
Generate a Model Explanation. You can filter your data to provide insights based on meaningful subsets. Returns a Plotly JSON object and the raw values for the explanation.
Request
Response
Request
Path Parameters
model_id
required
string
Unique ID from the model you want to explain
Headers
access-token
required
string
Active JWT token
Body Parameters
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful project creation
{
"code": "success",
"raw_values": "[{\"variable\":\"registration\",\"contribution\":0.0},{\"variable\":\"body\",\"contribution\":40.8438532434},{\"variable\":\"engType\",\"contribution\":99.2660057708},{\"variable\":\"model\",\"contribution\":181.6627453379},{\"variable\":\"car\",\"contribution\":682.4127359704},{\"variable\":\"drive\",\"contribution\":1976.5138912029},{\"variable\":\"mileage\",\"contribution\":2961.6075204103},{\"variable\":\"_baseline_\",\"contribution\":7247.5495223389},{\"variable\":\"year\",\"contribution\":9946.5714144367}]"
"visualizations":
{
"absolute_contribution_plot": "[JSON HERE]
}
],
"http_code": 201,
"message": "success"
}

post
Variable Explanation

https://api.expai.io/api/explain/<model_id>/variable/graphics
Generate a Variable Explanation. You can filter your data to provide insights based on meaningful subsets. Returns a Plotly JSON object and the raw values for the explanation.
Request
Response
Request
Path Parameters
model_id
required
string
Unique ID from the model you want to explain
Headers
access-token
required
string
Active JWT token
Body Parameters
variables
required
array
Array of variables that should be explained.
variables_type
optional
string
Dictionary containing the type for each variable that is going to be explained. Variable names as keys and 'numerical'/'categorical' as values.
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful explanation
{
"code": "success",
"http_code": 201,
"message": "Resource created",
"visualizations": {
"variable_contribution_plot": {
"variable1":"[JSON HERE],
"variable2":"[JSON HERE]
}
}
}

post
Prediction Explanation

https://api.expai.io/api/explain/<model_id>/sample/graphics
Generate a Prediction Explanation. You can filter your data to provide insights based on meaningful subsets. Returns a Plotly JSON object and the raw values for the explanation.
Request
Response
Request
Path Parameters
model_id
required
string
Unique ID from the model you want to explain
Headers
access-token
required
string
Active JWT token
Body Parameters
index
required
string
Unique index for the prediction that should be explained.
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful project creation
{
"code": "success",
"http_code": 201,
"message": "Resource created",
"raw_values":"[{\"feature\":\"Drive|model\",\"contribution\":\"1.0|475.0\"},{\"feature\":\"Engtype\",\"contribution\":\"1.0\"},{\"feature\":\"Engv\",\"contribution\":\"2.5\"},{\"feature\":\"Mileage\",\"contribution\":\"68.0\"},{\"feature\":\"Predicci\ón media\",\"contribution\":null},{\"feature\":\"Predicci\ón muestra\",\"contribution\":null},{\"feature\":\"Registration|car\",\"contribution\":\"1.0|23.0\"},{\"feature\":\"Year|body\",\"contribution\":\"2010.0|0.0\"}]",
"visualizations": {
"single_explanation":"[JSON HERE]
}
}

post
WHAT IF Explanation

https://api.expai.io/api/explain/<model_id>/what_if
Generate a WHAT IF Explanation. You can filter your data to provide insights based on meaningful subsets. Returns a Plotly JSON object and the raw values for the explanation.
Request
Response
Request
Path Parameters
model_id
required
string
Unique ID from the model you want to explain
Headers
access-token
required
string
Active JWT token
Body Parameters
variables
required
array
Variables on which potential values should be explored.
variables_type
optional
string
Dictionary containing the type for each variable that is going to be explored. Variable names as keys and 'numerical'/'categorical' as values.
index
required
string
Index for the prediction on which WHAT IF will be executed.
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful explanation
{
"code": "success",
"http_code": 201,
"message": "Resource created",
"raw_values": {
"year": "[{\"new_value\":1984,\"original_value\":2013.0,\"new_prediction\":5476.7211914062},{\"new_value\":1985,\"original_value\":2013.0,\"new_prediction\":5476.7211914062},{\"new_value\":1986,\"original_value\":2013.0,\"new_prediction\":5476.7211914062},{\"new_value\":1987,\"original_value\":2013.0,\"new_prediction\":5476.7211914062},{\"new_value\":1988,\"original_value\":2013.0,\"new_prediction\":5476.7211914062},{\"new_value\":1989,\"original_value\":2013.0,\"new_prediction\":5633.6762695312},{\"new_value\":1990,\"original_value\":2013.0,\"new_prediction\":5659.4916992188},{\"new_value\":1991,\"original_value\":2013.0,\"new_prediction\":5659.4916992188},{\"new_value\":1992,\"original_value\":2013.0,\"new_prediction\":5931.4614257812},{\"new_value\":1993,\"original_value\":2013.0,\"new_prediction\":6290.6176757812},{\"new_value\":1994,\"original_value\":2013.0,\"new_prediction\":6336.8022460938},{\"new_value\":1995,\"original_value\":2013.0,\"new_prediction\":6509.4907226562},{\"new_value\":1996,\"original_value\":2013.0,\"new_prediction\":6613.3940429688},{\"new_value\":1997,\"original_value\":2013.0,\"new_prediction\":6789.5922851562},{\"new_value\":1998,\"original_value\":2013.0,\"new_prediction\":6913.3735351562},{\"new_value\":1999,\"original_value\":2013.0,\"new_prediction\":7017.1420898438},{\"new_value\":2000,\"original_value\":2013.0,\"new_prediction\":7168.8461914062},{\"new_value\":2001,\"original_value\":2013.0,\"new_prediction\":7871.3168945312},{\"new_value\":2002,\"original_value\":2013.0,\"new_prediction\":8260.0263671875},{\"new_value\":2003,\"original_value\":2013.0,\"new_prediction\":9031.3857421875},{\"new_value\":2004,\"original_value\":2013.0,\"new_prediction\":9595.0673828125},{\"new_value\":2005,\"original_value\":2013.0,\"new_prediction\":10847.4267578125},{\"new_value\":2006,\"original_value\":2013.0,\"new_prediction\":11177.388671875},{\"new_value\":2007,\"original_value\":2013.0,\"new_prediction\":11612.970703125},{\"new_value\":2008,\"original_value\":2013.0,\"new_prediction\":12354.54296875},{\"new_value\":2009,\"original_value\":2013.0,\"new_prediction\":14540.68359375},{\"new_value\":2010,\"original_value\":2013.0,\"new_prediction\":15766.8544921875},{\"new_value\":2011,\"original_value\":2013.0,\"new_prediction\":15985.8955078125},{\"new_value\":2012,\"original_value\":2013.0,\"new_prediction\":15814.984375},{\"new_value\":2013,\"original_value\":2013.0,\"new_prediction\":18379.17578125},{\"new_value\":2014,\"original_value\":2013.0,\"new_prediction\":20331.81640625},{\"new_value\":2015,\"original_value\":2013.0,\"new_prediction\":24175.234375},{\"new_value\":2016,\"original_value\":2013.0,\"new_prediction\":28790.4921875}]"
},
"visualizations": {
"what_if_plot": {
"variable":"[JSON HERE]
}

post
WHAT IF BATTLE Explanation

https://api.expai.io/api/explain/<model_id>/variable/graphics
Generate a WHAT IF BATTLE Explanation. You can filter your data to provide insights based on meaningful subsets. Returns a Plotly JSON object and the raw values for the explanation.
Request
Response
Request
Path Parameters
model_id
required
string
Unique ID from the model you want to explain
Headers
access-token
required
string
Active JWT token
Body Parameters
index
required
string
Unique index for the prediction that should be modified
replace_dict
required
string
Dictionary containing the replacements done to the original input to the model: {variable1: new_value, ...}
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful explanation
{
"code": "success",
"http_code": 201,
"message": "Resource created",
"raw_values": {
"original_raw_values":"[{\"feature\":\"Body\",\"contribution\":\"vagon\"},{\"feature\":\"Car\",\"contribution\":\"volkswagen\"},{\"feature\":\"Drive\",\"contribution\":\"front\"},{\"feature\":\"Engtype\",\"contribution\":\"diesel\"},{\"feature\":\"Engv\",\"contribution\":\"1.9\"},{\"feature\":\"Mileage\",\"contribution\":\"320.0\"},{\"feature\":\"Model\",\"contribution\":\"passat b5\"},{\"feature\":\"Predicci\ón media\",\"contribution\":null},{\"feature\":\"Predicci\ón muestra\",\"contribution\":null},{\"feature\":\"Registration\",\"contribution\":\"no\"},{\"feature\":\"Year\",\"contribution\":\"2000.0\"}]",
"updated_raw_values":"[{\"feature\":\"Body\",\"contribution\":\"vagon\"},{\"feature\":\"Car\",\"contribution\":\"volkswagen\"},{\"feature\":\"Drive\",\"contribution\":\"front\"},{\"feature\":\"Engtype\",\"contribution\":\"diesel\"},{\"feature\":\"Engv\",\"contribution\":\"1.9\"},{\"feature\":\"Mileage\",\"contribution\":\"320.0\"},{\"feature\":\"Model\",\"contribution\":\"passat b5\"},{\"feature\":\"Predicci\ón media\",\"contribution\":null},{\"feature\":\"Predicci\ón muestra\",\"contribution\":null},{\"feature\":\"Registration\",\"contribution\":\"yes\"},{\"feature\":\"Year\",\"contribution\":\"2000.0\"}]"
},
"visualizations": {
"what_if_battle":"[JSON HERE]
}
}

post
Store Explanation

https://api.expai.io/api/projects/<project_id>/explanation/create
Store an explanation within a project. Body parameters should contain those used to generate the explanation.
Request
Response
Request
Path Parameters
project_id
required
string
Unique ID from the project in which you want to store your explanation
Headers
access-token
required
string
Active JWT token
Body Parameters
model_id
required
string
Unique ID for the model that was explained.
explanation_json
required
string
Plotly JSON representing the explanation.
explanation_name_des
required
string
Title for the explanation
explanation_summary_des
required
string
Description for the explanation.
explanation_type_id
required
string
Identifier for the generated explanation. See table below.
variables_type
optional
string
Dictionary containing variables types
variables
optional
array
Array of variables to be explained
index
optional
string
Unique index for the prediction that should be modified
replace_dict
optional
string
Dictionary containing the replacements done to the original input to the model: {variable1: new_value, ...}
sample_id
required
string
ID from the input sample to explaining the model.
subset_indexes
optional
array
List of row indexes used for explanation
subset_filters
optional
string
Dictionary containing filtering rules for the dataframe.
target_class
optional
string
If you are explaining a categorical model, choose the class for which you want to obtain insights.
Response
201: Created
Successful project creation
{
"code": "success",
"raw_values": "[{\"variable\":\"registration\",\"contribution\":0.0},{\"variable\":\"body\",\"contribution\":40.8438532434},{\"variable\":\"engType\",\"contribution\":99.2660057708},{\"variable\":\"model\",\"contribution\":181.6627453379},{\"variable\":\"car\",\"contribution\":682.4127359704},{\"variable\":\"drive\",\"contribution\":1976.5138912029},{\"variable\":\"mileage\",\"contribution\":2961.6075204103},{\"variable\":\"_baseline_\",\"contribution\":7247.5495223389},{\"variable\":\"year\",\"contribution\":9946.5714144367}]"
"visualizations":
{
"absolute_contribution_plot": "[JSON HERE]
}
],
"http_code": 201,
"message": "success"
}

delete
Delete Explanation

https://api.expai.io/api/projects/<project_id>/explanation/<explanation_id>
Delete a Model in a Project
Request
Response
Request
Path Parameters
project_id
required
string
Unique ID for the project containing the sample
explanation_id
required
string
Unique ID for the explanation to be deleted
Headers
access-token
required
string
Active JWT token
Response
204: No Content
Successful deletion
{
"code": "success",
"http_code": 204,
"message": "success"

get
List All Explanations

https://api.expai.io/api/projects/<project_id>/explanation/list
List all explanations stored within a project
Request
Response
Request
Path Parameters
project_id
required
string
Unique ID from the project you want to retrieve explanations
Headers
access-token
required
string
Active JWT token
Response
200: OK
Successful listing
{
"code": "success",
"http_code": 200,
"message": "success",
"explanations": [
{
"created_on_dt": "Mon, 29 Mar 2021 14:24:46 GMT",
"explanation_id": "6f0087e3-6ccc-495e-9b54-c502621219d0",
"explanation_image_path_des": [PUBLIC URL],
"explanation_name_des": "First test3",
"explanation_summary_des": null,
"explanation_type_des": "Explicación del modelo",
"model_id": "9b4aebcb-f316-447f-b1d7-92d0351a4208",
"model_name_des": "Fairness Pipeline",
"project_id": "86a6f587-7095-4572-afe0-990bc14b7748",
"project_name_des": "Proyecto Test Modelo",
"query_display_replace_dict": null,
"query_replace_dict": null,
"query_sample_index": null,
"query_subset_filters": null,
"query_subset_indexes": null,
"query_target_class": null,
"query_variables": null,
"query_variables_type": null,
"sample_id": "38c813eb-e758-48c5-8c44-adecff877763",
"sample_name_des": "Fairness"
},
...
]
}

get
List all Explanations containing a string in title

https://api.expai.io/api/projects/<project_id>/explanation/list/contains/<text>
List all explanations containing a given text in their titles.
Request
Response
Request
Path Parameters
text
required
string
Substring to be searched in explanations titles
project_id
required
string
Unique ID from the project you want to retrieve explanations
Headers
access-token
required
string
Active JWT token
Response
200: OK
Successful listing
{
"code": "success",
"http_code": 200,
"message": "success",
"explanations": [
{
"created_on_dt": "Mon, 29 Mar 2021 14:24:46 GMT",
"explanation_id": "6f0087e3-6ccc-495e-9b54-c502621219d0",
"explanation_image_path_des": [PUBLIC URL],
"explanation_name_des": "First test3",
"explanation_summary_des": null,
"explanation_type_des": "Explicación del modelo",
"model_id": "9b4aebcb-f316-447f-b1d7-92d0351a4208",
"model_name_des": "Fairness Pipeline",
"project_id": "86a6f587-7095-4572-afe0-990bc14b7748",
"project_name_des": "Proyecto Test Modelo",
"query_display_replace_dict": null,
"query_replace_dict": null,
"query_sample_index": null,
"query_subset_filters": null,
"query_subset_indexes": null,
"query_target_class": null,
"query_variables": null,
"query_variables_type": null,
"sample_id": "38c813eb-e758-48c5-8c44-adecff877763",
"sample_name_des": "Fairness"
},
...
]
}

get
List last N Explanations

https://api.expai.io/api/projects/<project_id>/explanation/list/last/<N>
List last N explanations stored within a project
Request
Response
Request
Path Parameters
N
required
number
Number of explanations to be retrieved
project_id
required
string
Unique ID from the project you want to retrieve explanations
Headers
access-token
required
string
Active JWT token
Response
200: OK
Successful listing
{
"code": "success",
"http_code": 200,
"message": "success",
"explanations": [
{
"created_on_dt": "Mon, 29 Mar 2021 14:24:46 GMT",
"explanation_id": "6f0087e3-6ccc-495e-9b54-c502621219d0",
"explanation_image_path_des": [PUBLIC URL],
"explanation_name_des": "First test3",
"explanation_summary_des": null,
"explanation_type_des": "Explicación del modelo",
"model_id": "9b4aebcb-f316-447f-b1d7-92d0351a4208",
"model_name_des": "Fairness Pipeline",
"project_id": "86a6f587-7095-4572-afe0-990bc14b7748",
"project_name_des": "Proyecto Test Modelo",
"query_display_replace_dict": null,
"query_replace_dict": null,
"query_sample_index": null,
"query_subset_filters": null,
"query_subset_indexes": null,
"query_target_class": null,
"query_variables": null,
"query_variables_type": null,
"sample_id": "38c813eb-e758-48c5-8c44-adecff877763",
"sample_name_des": "Fairness"
},
...
]
}