| Name | cafga JSON |
| Version |
0.0.5
JSON |
| download |
| home_page | None |
| Summary | CafGa is a library that facilitates creating and evaluating grouped-attribution explanations. |
| upload_time | 2025-09-20 02:49:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
llm
xai
nlp
salience
attribution
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CafGa (**C**ustom **a**ssignments **f**or **G**roup **a**ttribution)
## Project Links
github: https://github.com/explain-llm/CafGa
## Installation
CafGa can be installed through PyPI using
```
pip install cafga
```
When running CafGa from the repository run:
```
pip install -r requirements.txt
```
Note that some of the extra functionality requires further installations:
1. CafGa provides two jupyter widgets. The edit widget allows one to visually edit assignments and the display widget displays the attributions generated by the explanation. To use these please follow the instructions in the 'Demo Instructions.md' file.
2. CafGa offers a predefined ChatGPT model. To use it you need to place a .env file with your API key in the directory that contains the cafga.py file (in the site-packages directory).
## Using CafGa
The following provides an explanation of the main functions of cafga. To see an example of how to use cafga please look at the demo.
To begin using CafGa, start by importing CafGa creating a cafga object:
`from cafga import CafGa`
`cafga = CafGa(model = 'your_model')`
The model parameter is where you pass the model you want to explain. To allow for parallelization in how your model generates predictions (e.g. by batching) cafga sends lists of inputs to your model instead of single inputs. Thus, the function that implements your model should take a list of strings as input and output either a list of strings or a list of floats as output (i.e. a list containing one output for every input).
Once cafga is instantiated the typical usage of cafga runs proceeds in three steps: Explanation, Evaluation, and Visualisation.
### 1. Explanation
To generate an explanation run the explain function on the instantiated cafga object:
`explanation = cafga.explain(args)`
There are two way of using the explain functions.
Firstly, you can pass the string you want to get an explanation for without segmenting it into the individual parts that you want to get attributions for. In this case you need to provide the name of the predefined attribution method ('word', 'sentence', 'syntax-parse') that you want to use.
Secondly, you can provide your own segmentation of the input by using the `segmented_input` parameter. In this case you will also need to provide the assignments of input segment to group with the `input_assignments` parameter. Specifically, the `input_assignments[i] = g_i` should be the index of the group that `input_segments[i]` belongs to.
### 2. Evaluation
Once an explanation object has been generated you can pass it on to the evaluation function:
`evaluation = cafga.evaluate(explanation, args)`
The two forms of evaluation currently supported are deletion (going from all features present to no features present) and insertion (going from no features present to all features present), which can be indicated by the `direction` parameter. The resulting evaluation accordinlgy contains the array of difference values computed as part of the perturbation curve.
### 3. Visualisation
Finally, the perturbation curve generated by the evaluation can be visualised using the visualisation function:
`cafga.visualize_evaluation(evaluated_explanations, args)`
Since you may want to plot the aggregate over many evaluations the visualisation functions takes in a list of evaluations as input. The two forms of aggregation currently supported are equal width binning and linear interpolation.
Raw data
{
"_id": null,
"home_page": null,
"name": "cafga",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "LLM, XAI, NLP, salience, attribution",
"author": null,
"author_email": "Alan Boyle <aboyle@student.ethz.ch>",
"download_url": "https://files.pythonhosted.org/packages/dd/31/24fa16fd36a60ca3adf6fa8b4eeb8fb6b319cdbcd52347f5b97515c87ab8/cafga-0.0.5.tar.gz",
"platform": null,
"description": "# CafGa (**C**ustom **a**ssignments **f**or **G**roup **a**ttribution)\n\n## Project Links\n\ngithub: https://github.com/explain-llm/CafGa\n\n## Installation\n\nCafGa can be installed through PyPI using\n\n```\npip install cafga\n```\n\nWhen running CafGa from the repository run:\n\n```\npip install -r requirements.txt\n```\n\nNote that some of the extra functionality requires further installations:\n\n1. CafGa provides two jupyter widgets. The edit widget allows one to visually edit assignments and the display widget displays the attributions generated by the explanation. To use these please follow the instructions in the 'Demo Instructions.md' file. \n\n2. CafGa offers a predefined ChatGPT model. To use it you need to place a .env file with your API key in the directory that contains the cafga.py file (in the site-packages directory). \n\n## Using CafGa\n\nThe following provides an explanation of the main functions of cafga. To see an example of how to use cafga please look at the demo. \n\nTo begin using CafGa, start by importing CafGa creating a cafga object:\n\n`from cafga import CafGa`\n\n`cafga = CafGa(model = 'your_model')`\n\nThe model parameter is where you pass the model you want to explain. To allow for parallelization in how your model generates predictions (e.g. by batching) cafga sends lists of inputs to your model instead of single inputs. Thus, the function that implements your model should take a list of strings as input and output either a list of strings or a list of floats as output (i.e. a list containing one output for every input). \n\nOnce cafga is instantiated the typical usage of cafga runs proceeds in three steps: Explanation, Evaluation, and Visualisation.\n\n### 1. Explanation\n\nTo generate an explanation run the explain function on the instantiated cafga object:\n\n`explanation = cafga.explain(args)`\n\nThere are two way of using the explain functions. \n\nFirstly, you can pass the string you want to get an explanation for without segmenting it into the individual parts that you want to get attributions for. In this case you need to provide the name of the predefined attribution method ('word', 'sentence', 'syntax-parse') that you want to use. \n\nSecondly, you can provide your own segmentation of the input by using the `segmented_input` parameter. In this case you will also need to provide the assignments of input segment to group with the `input_assignments` parameter. Specifically, the `input_assignments[i] = g_i` should be the index of the group that `input_segments[i]` belongs to. \n\n### 2. Evaluation\n\nOnce an explanation object has been generated you can pass it on to the evaluation function:\n\n`evaluation = cafga.evaluate(explanation, args)`\n\nThe two forms of evaluation currently supported are deletion (going from all features present to no features present) and insertion (going from no features present to all features present), which can be indicated by the `direction` parameter. The resulting evaluation accordinlgy contains the array of difference values computed as part of the perturbation curve. \n\n### 3. Visualisation\n\nFinally, the perturbation curve generated by the evaluation can be visualised using the visualisation function:\n\n`cafga.visualize_evaluation(evaluated_explanations, args)`\n\nSince you may want to plot the aggregate over many evaluations the visualisation functions takes in a list of evaluations as input. The two forms of aggregation currently supported are equal width binning and linear interpolation. \n",
"bugtrack_url": null,
"license": null,
"summary": "CafGa is a library that facilitates creating and evaluating grouped-attribution explanations.",
"version": "0.0.5",
"project_urls": null,
"split_keywords": [
"llm",
" xai",
" nlp",
" salience",
" attribution"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "171b9c1ddc3a2095d143c06f21d5d9e9da1a13da3aeb6e153d5b5554a4945363",
"md5": "ccf3220ddc16593f0f9e2efb84327687",
"sha256": "b6ad31cb482fd743e3f2bece4bdb322121c8161ef7e8c6cfb74eae8872b0f623"
},
"downloads": -1,
"filename": "cafga-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccf3220ddc16593f0f9e2efb84327687",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19447,
"upload_time": "2025-09-20T02:49:08",
"upload_time_iso_8601": "2025-09-20T02:49:08.224343Z",
"url": "https://files.pythonhosted.org/packages/17/1b/9c1ddc3a2095d143c06f21d5d9e9da1a13da3aeb6e153d5b5554a4945363/cafga-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd3124fa16fd36a60ca3adf6fa8b4eeb8fb6b319cdbcd52347f5b97515c87ab8",
"md5": "92b6ef9150a14f89e9fd484301071cbd",
"sha256": "3792069c6e84bb5cff31f31e322e5b65e7d938bf5cfa96aba23688c508bc7452"
},
"downloads": -1,
"filename": "cafga-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "92b6ef9150a14f89e9fd484301071cbd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 19535,
"upload_time": "2025-09-20T02:49:09",
"upload_time_iso_8601": "2025-09-20T02:49:09.497099Z",
"url": "https://files.pythonhosted.org/packages/dd/31/24fa16fd36a60ca3adf6fa8b4eeb8fb6b319cdbcd52347f5b97515c87ab8/cafga-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-20 02:49:09",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cafga"
}
