{"id":22938802,"url":"https://github.com/braindatalab/xai-tris","last_synced_at":"2025-08-31T09:41:28.257Z","repository":{"id":174996634,"uuid":"649623189","full_name":"braindatalab/xai-tris","owner":"braindatalab","description":"XAI-Tris","archived":false,"fork":false,"pushed_at":"2025-05-08T00:40:53.000Z","size":1195,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-08T01:32:12.010Z","etag":null,"topics":["artificial-intelligence","benchmarking","captum","explainability","explainable-ai","explainable-ml","innvestigate","interpretability","interpretable-ai","interpretable-ml","machine-learning","python","xai"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/braindatalab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-05T09:28:40.000Z","updated_at":"2024-10-13T21:29:47.000Z","dependencies_parsed_at":"2023-12-22T08:38:49.147Z","dependency_job_id":"46c058f8-516e-4d11-80a7-dafdd919019b","html_url":"https://github.com/braindatalab/xai-tris","commit_stats":{"total_commits":11,"total_committers":2,"mean_commits":5.5,"dds":0.09090909090909094,"last_synced_commit":"515184e69ad701c8e4a547079e0b4fc14145daad"},"previous_names":["braindatalab/xai-tris"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/braindatalab/xai-tris","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindatalab%2Fxai-tris","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindatalab%2Fxai-tris/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindatalab%2Fxai-tris/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindatalab%2Fxai-tris/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/braindatalab","download_url":"https://codeload.github.com/braindatalab/xai-tris/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/braindatalab%2Fxai-tris/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272965446,"owners_count":25023070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","benchmarking","captum","explainability","explainable-ai","explainable-ml","innvestigate","interpretability","interpretable-ai","interpretable-ml","machine-learning","python","xai"],"created_at":"2024-12-14T12:28:33.040Z","updated_at":"2025-08-31T09:41:28.194Z","avatar_url":"https://github.com/braindatalab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# XAI-Tris\n\nThis repository contains all the experiments presented in the paper: *\"XAI-TRIS: Non-linear benchmarks to quantify ML explanation performance\"*.\n\nWe use `Pipfiles` to create Python environments. Our main experiments use [Captum](https://github.com/pytorch/captum), however inclusion of some methods (PatternNet, PatternAttribution, DTD) from the [innvestigate](https://github.com/albermax/innvestigate) library requires particular dependencies, such as `Python=3.7`, `tensorflow==1.13.1/1.14`, and `keras==2.2.4`. If you do not wish to include these methods, you are able to remove `tensorflow` and `keras` from the Pipfile and change any specific package requirements to `*` along with the Python version of choice (we have also tested this with `Python 3.10`). \n\nTo setup pipenv, run:\n```shell\npipenv install\n```\nand then\n```shell\npipenv shell\n```\n\nIn four steps we can reproduce the results: (i) generate tetromino data, (ii) train models (iii) apply XAI methods, (iv) run the evaluation steps and generate plots.\n\n#### Generate data \n\n##### Download ImageNet data\nIf one wishes to use the data from the ImageNet-1k, we sourced it from [HuggingFace](https://huggingface.co/datasets/imagenet-1k) by making an account and agreeing to the license terms. Please respect these license terms when using this data. Download and extract images into a folder `imagenet_images/` in the top level of this repository. We used the `N=50,000` validation set due to the appropriate volume size for our datasets and benchmarks. \n\n##### 64x64 Data\nOnce ImageNet data is downloaded and extracted above (if using it), configuration is set by the `data/data_config.json` file, with fields explained in data/README.md. Generate data via:\n```shell\npython -m data.generate_data \n```\n\n##### 8x8 Data\nOne can also generate the original 8x8 data (without ImageNet backgrounds), which is quicker and less computationally demanding to run, and also produces interesting results. Configuration here is set by the `data/data_config_8by8.json` file. Generate data via:\n```shell\npython -m data.generate_data data_config_8by8\n```\n\n#### Train models\n\nUpdate the `data_path` parameter of the `training/training_config.json` with the path to the folder of freshly generated pickle files containing data, of the form `artifacts/tetris/data/YYYY-MM-DD-HH-mm`.\n\nTo train models for a particular scenario, background, and experiment number:\n\n##### Torch\n```shell\npython -m training.train_models SCENARIO BACKGROUND EXP_NUM OUT_DIR \n```\nwhere `SCENARIO=[linear|multiplicative|translations_rotations|xor]`, `BACKGROUND=[uncorrelated|correlated|imagenet]`, `EXP_NUM=[0,...,N]`, and `OUT_DIR=[str]`. For example `python -m training.train_models linear uncorrelated 0 neurips_training` will train models for the `linear` scenario with `uncorrelated` (WHITE) background for the `0`th experiment and output models and logs to the `artifacts/tetris/training/neurips_training` directory.\n\n##### Keras\n```shell\npython -m training.train_models_keras SCENARIO BACKGROUND EXP_NUM OUT_DIR \n```\nwhere input args are the same as specified above.\n\n##### Train all models\nAs you may have noticed, you will have to run this individually for all scenario-background pairs. You can also input regex into the `SCENARIO` and `BACKGROUND` input args, so running `python -m training.train_models * * EXP_NUM OUT_DIR` will train all scenario and background types for PyTorch.\n\nOne can use a somewhat approach like `./train_all.sh` which simply runs all parameterizations one after another. We can also provide a script combining all parameterizations for each frameworks if needed.\n\n#### XAI Methods\nUpdate the `data_path`, `training_output`, and `num_experiments` parameters of the `xai/xai_config.json` file with the same `data_path` as used in the training step, and the corresponding training output path of the form `artifacts/tetris/training/OUT_DIR`.\n\nTo calculate explanations for a particular scenario and background and across all experiments:\n##### Torch\n```shell\npython -m xai.calculate_explanations SCENARIO BACKGROUND OUT_DIR \n```\nwhere `SCENARIO=[linear|multiplicative|translations_rotations|xor]`, `BACKGROUND=[uncorrelated|correlated|imagenet]`, and `OUT_DIR=[str]` as in the training step. Note: as of 14/06/23, you can't use regex for `SCENARIO` and `BACKGROUND` as in the training step, as it is incompatible with the input to the next step. If/when changed, this README will be updated.\n\n##### Keras\n```shell\npython -m xai.calculate_explanations_keras SCENARIO BACKGROUND OUT_DIR \n```\nwhere input args are the same as specified above.\n\n\n#### Run evaluation metrics\nUpdate the parameters `data_path`, `training_path`, `xai_path`, and `num_experiments` of `eval/eval_config.json`, and specify the desired output directory here too, in the form `./artifacts/tetris/eval/OUT_DIR`.\n##### Torch\n```shell\npython -m eval.quantitative_metrics SCENARIO BACKGROUND \n```\nwhere `SCENARIO=[linear|multiplicative|translations_rotations|xor]` and `BACKGROUND=[uncorrelated|correlated|imagenet]`. Note: as of 14/06/23, you can't use regex for `SCENARIO` and `BACKGROUND` as in the training step, as it is incompatible with the input to the next step. If/when changed, this README will be updated.\n\n##### Keras\n```shell\npython -m eval.quantitative_metrics_keras SCENARIO BACKGROUND OUT_DIR \n```\nwhere input args are the same as specified above.\n\n#### Generate plots\nWith the same parameters of  `eval/eval_config.json` as before, simply run:\n##### Qualitative plots (local and global)\n```shell\npython -m eval.plot_qualitative\n```\n##### Quantitative plots\n```shell\npython -m eval.plot_quantitative\n```\n\n#### Questions and Issues\nIf you have any questions and/or issues with the above, please do not hesitate to contact the authors!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraindatalab%2Fxai-tris","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbraindatalab%2Fxai-tris","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbraindatalab%2Fxai-tris/lists"}