# 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:
```bash
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.
<p align="center">
<img src="https://raw.githubusercontent.com/jovanavidenovic/ConteXAI/main/other/XAI_2_page-0001.jpg" alt="Report structure" width="85%">
</p>
### 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.
```bash
{
# 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:
```python
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](https://github.com/jovanavidenovic/ConteXAI/tree/main/titanic).
#### Examples
Examples of the generated reports are shown below. Problem domain was diabetes prediction.
Raw data
{
"_id": null,
"home_page": null,
"name": "dscontexai",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, first package",
"author": "Jovana V., Haris K., Luka M.",
"author_email": "hk8302@student.uni-lj.si",
"download_url": "https://files.pythonhosted.org/packages/94/88/c390cdc3f944385ce6e4314bae7034cdd48bd29b443621d50e6e91df5af1/dscontexai-1.1.0.tar.gz",
"platform": null,
"description": "\n# ConteXAI - Contextualizing model's decisions with natural language explanations\n\nThe library ConteXAI **links local explainability methods with natural language explanations**, allowing users to gain detailed insights into model predictions.\nBy incorporating additional domain knowledge, users can obtain even better insights into the model's predictions.\n\n### Install\n\nConteXAI can be installed using pip:\n```bash\npip install dscontexai\n```\n\n### Generate XAI reports\n\nUsing 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.\nThe library can be used for binary classification problems, for all models that output probabilities.\n\nThe report consists of four main segments: \n\n (1) Description of local feature importances, \n\n (2) Explanation of the instance's prediction, \n\n (3) Visualization of local feature importances, \n\n (4) Explanation of the visualization in natural language and context related to the domain and the prediction. \n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jovanavidenovic/ConteXAI/main/other/XAI_2_page-0001.jpg\" alt=\"Report structure\" width=\"85%\">\n</p>\n\n### Preparing configuration file\nTo use this tool with your model and dataset, you need to provide a configuration JSON file for a dataset, structured like the one below.\n\n```bash\n{\n # domain-based context\n \"optimal_values\": [\n ...\n [0, 6.5], # HbA1c level optimal range is from 0 to 6.5\n [100, 140] # Glucose level optimal range is from 100 to 140 \n ],\n \"descriptions\": {\n \"below_optimal\": [\n # Context for feature values falling below the optimal range\n ],\n \"optimal\": [\n # Context for feature values falling within the optimal range\n ],\n \"above_optimal\": [\n # Context for feature values falling above the optimal range\n ]\n },\n # Data transformations for feature mapping\n \"transformation\": {\n \"0\": [\"Man\", \"Woman\"], # Transformation for Gender\n \"1\": [], # No transformation for Age (numeric)\n \"2\": [\"No\", \"Yes\"], # Transformation for Hypertension\n ...\n },\n \"feature_names\": [\n \"Gender\",\n \"Age\",\n \"Hypertension\",\n \"Heart_disease\",\n \"Smoking_history\",\n \"BMI\",\n \"HbA1c_level\",\n \"Blood_glucose_level\"\n ],\n # variables needed for structuring the description\n \"target1\": \"diabetes\", # Target variable the model is predicting\n \"target2\": \"Person\", # The object representing a sample in a data\n \"supporting\": [\"does\", \"have\"] # Supporting verbs used in descriptions\n}\n```\n\n#### Running the generation\nOnce you have model, dataset, and config file ready, to generate the report, you can use the following code snippet:\n\n ```python\n from dscontexai.generate_report import general\n\n general.generate_report(model_path= \"path/to/model.pkl\", dataset_path=\"path/to/data.csv\", config=\"path/to/config.json\", idx=sample_idx)\n ```\n\nAfter successful generation, you will find a PDF report in the directory prototype/ under the name output_{sample_idx}.pdf.\n\n#### Example notebooks\n\nWorking example, as well as the example of the generated report and the configuration file, can be found [here](https://github.com/jovanavidenovic/ConteXAI/tree/main/titanic).\n\n#### Examples\nExamples of the generated reports are shown below. Problem domain was diabetes prediction.\n\n\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Contextualizing model's decisions with natural language explanations.",
"version": "1.1.0",
"project_urls": null,
"split_keywords": [
"python",
" first package"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d36df656d0f980f9a87edf2ea0c14bbe21c1aa80310a622ffd0c21ae01465dcc",
"md5": "8b54029a3a99cfdbee75b251099cf92f",
"sha256": "cd267f0d8e9a463729a0b5aa68e0475c418f8d4544d7e89063011d7529de85e6"
},
"downloads": -1,
"filename": "dscontexai-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b54029a3a99cfdbee75b251099cf92f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 17321,
"upload_time": "2024-05-26T21:09:38",
"upload_time_iso_8601": "2024-05-26T21:09:38.600267Z",
"url": "https://files.pythonhosted.org/packages/d3/6d/f656d0f980f9a87edf2ea0c14bbe21c1aa80310a622ffd0c21ae01465dcc/dscontexai-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9488c390cdc3f944385ce6e4314bae7034cdd48bd29b443621d50e6e91df5af1",
"md5": "18241a7f52a29aead0697bbc90c855cb",
"sha256": "80b6fbf5287b81f4da41e1c5eaa9613431473031e5b251c9fd4a82b5f5492ffb"
},
"downloads": -1,
"filename": "dscontexai-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "18241a7f52a29aead0697bbc90c855cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15293,
"upload_time": "2024-05-26T21:09:41",
"upload_time_iso_8601": "2024-05-26T21:09:41.023961Z",
"url": "https://files.pythonhosted.org/packages/94/88/c390cdc3f944385ce6e4314bae7034cdd48bd29b443621d50e6e91df5af1/dscontexai-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-26 21:09:41",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "dscontexai"
}
JSON