Explanations generation

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

List allowed explanations

GET 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.

Headers

Name	Type	Description
access-token	string	Active JWT token
Content-Type	string	Value: "application/json"

200

{
    "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"
}

Model Explanation

POST 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.

Path Parameters

Name	Type	Description
model_id	string	Unique ID from the model you want to explain

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
sample_id	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.

201 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"
}

Variable Explanation

POST 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.

Path Parameters

Name	Type	Description
model_id	string	Unique ID from the model you want to explain

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
variables	array	Array of variables that should be explained.
variables_type	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	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.

201 Successful explanation

{
    "code": "success",
    "http_code": 201,
    "message": "Resource created",
    "visualizations": {
        "variable_contribution_plot": {
            "variable1":"[JSON HERE]”,
            "variable2":"[JSON HERE]”
        }
    }
}

Prediction Explanation

POST 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.

Path Parameters

Name	Type	Description
model_id	string	Unique ID from the model you want to explain

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
index	string	Unique index for the prediction that should be explained.
sample_id	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.

201 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]”
    }
}

WHAT IF Explanation

POST 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.

Path Parameters

Name	Type	Description
model_id	string	Unique ID from the model you want to explain

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
variables	array	Variables on which potential values should be explored.
variables_type	string	Dictionary containing the type for each variable that is going to be explored. Variable names as keys and 'numerical'/'categorical' as values.
index	string	Index for the prediction on which WHAT IF will be executed.
sample_id	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.

201 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]”
}

WHAT IF BATTLE Explanation

POST 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.

Path Parameters

Name	Type	Description
model_id	string	Unique ID from the model you want to explain

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
index	string	Unique index for the prediction that should be modified
replace_dict	string	Dictionary containing the replacements done to the original input to the model: {variable1: new_value, ...}
sample_id	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.
variables	array	Variables on which some changes are set

201 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]”
    }
}

Store Explanation

POST 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.

Path Parameters

Name	Type	Description
project_id	string	Unique ID from the project in which you want to store your explanation

Headers

Name	Type	Description
access-token	string	Active JWT token

Request Body

Name	Type	Description
model_id	string	Unique ID for the model that was explained.
explanation_json	string	Plotly JSON representing the explanation.
explanation_name_des	string	Title for the explanation
explanation_summary_des	string	Description for the explanation.
explanation_type_id	string	Identifier for the generated explanation. See table below.
variables_type	string	Dictionary containing variables types
variables	array	Array of variables to be explained
index	string	Unique index for the prediction that should be modified
replace_dict	string	Dictionary containing the replacements done to the original input to the model: {variable1: new_value, ...}
sample_id	string	ID from the input sample to explaining the model.
subset_indexes	array	List of row indexes used for explanation
subset_filters	string	Dictionary containing filtering rules for the dataframe.
target_class	string	If you are explaining a categorical model, choose the class for which you want to obtain insights.

201 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 Explanation

DELETE https://api.expai.io/api/projects/<project_id>/explanation/<explanation_id>

Delete a Model in a Project

Path Parameters

Name	Type	Description
project_id	string	Unique ID for the project containing the sample
explanation_id	string	Unique ID for the explanation to be deleted

Headers

Name	Type	Description
access-token	string	Active JWT token

204 Successful deletion

{
    "code": "success",
    "http_code": 204,
    "message": "success"

List All Explanations

GET https://api.expai.io/api/projects/<project_id>/explanation/list

List all explanations stored within a project

Path Parameters

Name	Type	Description
project_id	string	Unique ID from the project you want to retrieve explanations

Headers

Name	Type	Description
access-token	string	Active JWT token

200 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"
         },
         ...
    ]
}

List all Explanations containing a string in title

GET https://api.expai.io/api/projects/<project_id>/explanation/list/contains/<text>

List all explanations containing a given text in their titles.

Path Parameters

Name	Type	Description
text	string	Substring to be searched in explanations titles
project_id	string	Unique ID from the project you want to retrieve explanations

Headers

Name	Type	Description
access-token	string	Active JWT token

200 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"
         },
         ...
    ]
}

List last N Explanations

GET https://api.expai.io/api/projects/<project_id>/explanation/list/last/<N>

List last N explanations stored within a project

Path Parameters

Name	Type	Description
N	number	Number of explanations to be retrieved
project_id	string	Unique ID from the project you want to retrieve explanations

Headers

Name	Type	Description
access-token	string	Active JWT token

200 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"
         },
         ...
    ]
}