ConteXAI - Contextualizing model's decisions with natural language explanations

The library ConteXAI links local explainability methods with natural language explanations, allowing users to gain detailed insights into model predictions. By incorporating additional domain knowledge, users can obtain even better insights into the model's predictions.

Install

ConteXAI can be installed using pip:

pip install dscontexai

Generate XAI reports

Using this library, you can fully automatically develop your XAI reports. Currently, it supports SHAP values, which is a local feature importance measure, to which we added textual explanations and domain-related context. The library can be used for binary classification problems, for all models that output probabilities.

The report consists of four main segments:

(1) Description of local feature importances,

(2) Explanation of the instance's prediction,

(3) Visualization of local feature importances,

(4) Explanation of the visualization in natural language and context related to the domain and the prediction.

Preparing configuration file

To use this tool with your model and dataset, you need to provide a configuration JSON file for a dataset, structured like the one below.

{
  # domain-based context
  "optimal_values": [
  ...
    [0, 6.5],               # HbA1c level optimal range is from 0 to 6.5
    [100, 140]              # Glucose level optimal range is from 100 to 140 
  ],
  "descriptions": {
    "below_optimal": [
      # Context for feature values falling below the optimal range
    ],
    "optimal": [
      # Context for feature values falling within the optimal range
    ],
    "above_optimal": [
      # Context for feature values falling above the optimal range
    ]
  },
  # Data transformations for feature mapping
  "transformation": {
    "0": ["Man", "Woman"],  # Transformation for Gender
    "1": [],                # No transformation for Age (numeric)
    "2": ["No", "Yes"],     # Transformation for Hypertension
    ...
  },
  "feature_names": [
    "Gender",
    "Age",
    "Hypertension",
    "Heart_disease",
    "Smoking_history",
    "BMI",
    "HbA1c_level",
    "Blood_glucose_level"
  ],
  # variables needed for structuring the description
  "target1": "diabetes",    # Target variable the model is predicting
  "target2": "Person",      # The object representing a sample in a data
  "supporting": ["does", "have"]  # Supporting verbs used in descriptions
}

Running the generation

Once you have model, dataset, and config file ready, to generate the report, you can use the following code snippet:

from dscontexai.generate_report import general

general.generate_report(model_path= "path/to/model.pkl", dataset_path="path/to/data.csv", config="path/to/config.json", idx=sample_idx)

After successful generation, you will find a PDF report in the directory prototype/ under the name output_{sample_idx}.pdf.

Example notebooks

Working example, as well as the example of the generated report and the configuration file, can be found here.

Examples

Examples of the generated reports are shown below. Problem domain was diabetes prediction.