{"id":48065504,"url":"https://github.com/anselmeamekoe/tabsra","last_synced_at":"2026-04-04T14:35:56.601Z","repository":{"id":183694987,"uuid":"670219861","full_name":"anselmeamekoe/TabSRA","owner":"anselmeamekoe","description":"Use an intrinsically interpretable model or explain a black box?","archived":false,"fork":false,"pushed_at":"2024-09-13T15:30:10.000Z","size":30728,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-09-14T06:25:13.882Z","etag":null,"topics":["attention","interpretable-machine-learning","tabular"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anselmeamekoe.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}},"created_at":"2023-07-24T14:54:16.000Z","updated_at":"2024-09-13T15:30:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"a0b2fb84-c61b-4081-9ccf-ca9cae852f29","html_url":"https://github.com/anselmeamekoe/TabSRA","commit_stats":{"total_commits":4,"total_committers":2,"mean_commits":2.0,"dds":0.25,"last_synced_commit":"644acf31717d367f69e0738f405d6b44c922a430"},"previous_names":["anselmeamekoe/tabsra"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anselmeamekoe/TabSRA","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselmeamekoe%2FTabSRA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselmeamekoe%2FTabSRA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselmeamekoe%2FTabSRA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselmeamekoe%2FTabSRA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anselmeamekoe","download_url":"https://codeload.github.com/anselmeamekoe/TabSRA/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anselmeamekoe%2FTabSRA/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["attention","interpretable-machine-learning","tabular"],"created_at":"2026-04-04T14:35:56.056Z","updated_at":"2026-04-04T14:35:56.588Z","avatar_url":"https://github.com/anselmeamekoe.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Exploring Accuracy and Interpretability trade-off in Tabular Learning with Novel Attention-Based Models\n Apart from the predictive performance, interpretability is essential for :\n - uncovering hidden patterns in the data\n - providing meaningful justification of decisions made by machine learning mode\n - ...\n   \n In this concern, an important question arises: should one use *inherently interpretable* models or explain full-complexity models such as XGBoost, Random Forest with post hoc tools?\n\nIn this repository, we provide some concrete numerical results that can guide practitioners (or researchers) in their choice between using inherently interpretable\nsolutions and explaining full-complexity models. \n\nThis study includes, *TabSRAs*, an attention based inherently interpretable model which is proving to be a viable option for (i) generating stable or robust explanations, and (ii) incorporating\nhuman knowledge during the training phase.\n\n## What is the actual performance gap between the full-complexity state-of-the-art models and their inherently interpretable counterparts in terms of accuracy?\n| Model            | Rank (min)|   Rank (max)      |   Rank (mean)    | Rank (median)|Test score (mean)|Test score (median)|Test score (std)|Runing Time (mean)|Runing Time (meadian)|\n|------------------|-----|-----|--------|--------|-------|--------|-------|---------|----------|\n|DT | 2 | 12 | 10.476 | 11|                      0.868 |  0.907 | 0.163 |     0.294 |   0.032 |\n| EBM\\_S | 1 | 11 |  7.692 |  8 |                      0.931 |  0.955 | 0.087 |    23.997 |   5.144 |\n| EBM | 1 | 10 | 5.477 |  5 |                      0.959 |  0.982 | 0.067 |    97.837 |  19.737 |\n| LR | 7 | 12 | 11.701 | 12 |                      0.760 |  0.839 | 0.232 |    21.124 |  19.716 |\n|TabSRALinear | 1 | 12 |  8.225 |  9 |                      0.901 |  0.971 | 0.197 |   47.576 |  38.073 |\n|                  |                                                                                 |\n| MLP | 1 | 12 |  6.992 |  8 |                      0.924 |  0.973 | 0.159 |    24.165 |  19.256 |\n| ResNet | 1 | 12 |  7.120 |  8 |                     0.909 |  0.975 | 0.195 |    95.123 |  53.212 |\n|SAINT | 1 | 12 |  5.625 |  6 |                      0.946 |  0.982 | 0.093 |   216.053 | 126.841 |\n| FT-Transformer | 1 | 11 |  5.203 | 5 |                      0.944 |  0.984 | 0.109 |   126.589 |  77.465 |\n  Random Forest | 1 | 10 |  4.214 |  4 |                      0.985 |  0.992 | 0.021 |   39.030 |  8.252 |\n| XGBoost | 1 | 11 |  2.728 | 2 |                      0.988 |  0.998 | 0.029 |    18.254 |  12.561 |\n| CatBoost |1 | 10 |  2.545 |  2 |                      0.991 |  0.999 | 0.021 |    12.176 |   4.025 |\n\n\nPredictive performance of models across a benchmark of 45 datasets (59 tasks) introduced in the paper \"Why do tree-based models still outperform deep learning on typical tabular data?\". We report the rank over all tasks, the relative test score (Accuracy/ $R^2$ ) and running time (training+inference) in seconds.\n\nThe considered inherently interpretable models are:\n- Decision Trees [(DT)](https://scikit-learn.org/stable/modules/tree.html)\n- Explainable Boosting Machine [EBMs](https://github.com/interpretml/interpret)\n  - EBM: EBMs with **pairwise interaction** terms\n  - EBM_S: EBMs **without pairwise interaction** terms\n- Linear/Logistic Regression (LR): pytorch is used for the implementation\n- TabSRALinear: an instantiation of TabSRAs, which imitates the formulation of classical Linear models. More details or in the papers [ESANN](https://www.esann.org/sites/default/files/proceedings/2023/ES2023-37.pdf), [ECML@XKDD](http://xkdd2023.isti.cnr.it/papers/426.pdf)\n  \nAmong full-complexty models, we considered:\n- MultiLayer Perceptron (MLP): pytorch is used for the implementation\n- [ResNet](https://arxiv.org/pdf/2106.11959.pdf)\n- [SAINT](https://arxiv.org/pdf/2106.01342.pdf)\n- [FT Transformer](https://arxiv.org/pdf/2106.11959.pdf)\n- [Random Forest](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.RandomForestClassifier.html)\n- [XGBoost](https://xgboost.readthedocs.io/en/stable/)\n\n### What about the robustness of explanations, are the produced feature attributions similar for similar inputs?\n\u003cimg src=\"https://github.com/anselmeamekoe/TabSRA/blob/main/ressources/Stability_CardFraud_Split0_hideen1_1E_3.png\" width=600px\u003e\n\nChanges in feature attributions (the lower the better) using the [CreditCardFraud](https://www.kaggle.com/datasets/mlg-ulb/creditcardfraud) dataset. \n\nLR = Logistic Regression, SRA=TabSRALinear, XGB_SHAP=XGBoost+TreeSHAP\n\n\n## Usage\n### Prerequisites\nCreate a new python environment, install the [requirements](https://github.com/anselmeamekoe/TabSRA/blob/main/requirements.txt)\n### Replicating the analyses/results on the predictive performance\n1. Clone this repository of your machine\n2. Dowanload the random search results using the links:\n   - [full-complexity models](https://figshare.com/ndownloader/files/40081681)\n   - [inherently interpretable models and CatBoost](https://drive.google.com/file/d/1roIloMQIcEVCPpHieesqGwlH9udGh-4A/view?usp=sharing)\n3.  Copy and paste the downloaded files to ```TabSRA/tabular-benchmark/analyses/```\n4.  Run the [Notebook](https://github.com/anselmeamekoe/TabSRA/blob/main/tabular-benchmark/analyses/results.ipynb) for reproducing results\n   \nNB: To use the notebook, you will need to install it in the python environment you have created using pip for example\n\n### Replicating the results on the robustness of explanations \n1. Use the [Notebook](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Robustness_Study_CreditCardFraud.ipynb) for the example on the Credit Card Fraud dataset\n2. Use the [Notebook](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Robustness_Study_HelocFico.ipynb) for the example on the Heloc Fico dataset\n\n### Replicating the results on the study of the faithfulness of explanations\n1. [Linear functions](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Synthetic1_Regression_Example.ipynb)\n2. [Parabolic functions](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Synthetic2_Regression_Example.ipynb) \n3. [Linear functions with interactions](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Synthetic3_Regression_Example.ipynb) \n\n### Real-world examples of TabSRALinear's unique capabilities\n1. [Churn modeling with bias correction](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Application1_BankChurnModeling.ipynb)\n2. [Credit Default modeling with a group of correlated features](https://github.com/anselmeamekoe/TabSRA/blob/main/notebooks/Application2_TaiwanCreditDefault.ipynb)\n   \n### Benchmarking your own or another  algorithm\nPlease follow the instructions [here](https://github.com/LeoGrin/tabular-benchmark/tree/main) to benchmark a new model depending on your budget.\n### Usage of TabSRALinear\nWe use the [skorch](https://skorch.readthedocs.io/en/stable/) framework to make our implementation more scikit-learn friendly.\n[Here](https://github.com/anselmeamekoe/TabSRA/tree/main/ESANN_XKDD) is the old version.\n\n```python\nimport torch\nimport torch.nn as nn\nfrom skorch.callbacks import EarlyStopping,LRScheduler,Checkpoint, TrainEndCheckpoint, EpochScoring, InputShapeSetterTabSRA\nfrom skorch.dataset import Dataset\nfrom skorch.helper import predefined_split\nfrom sramodels.SRAModels import TabSRALinearClassifier\nfrom sklearn.metrics import roc_auc_score\n\nconfigs = {\n         \"module__n_head\":1,\n         \"module__dim_head\":8,\n         \"module__n_hidden_encoder\":1,\n         \"module__dropout_rate\":0.3,\n         \"optimizer__lr\":0.001,\n         \"random_state\":42,\n         \"criterion\": nn.BCEWithLogitsLoss,\n         \"max_epochs\":100,\n         \"batch_size\":256,\n         \"device\":'cpu'\n}\nscoring = EpochScoring(scoring='roc_auc',lower_is_better=False)#the scoring function\nsetter = InputShapeSetterTabSRA(regression=False)#used for setting the input and output dimension automatically\nearly_stop = EarlyStopping(monitor=scoring.scoring, patience=10,load_best=True,lower_is_better=False, threshold=0.0001,threshold_mode='abs')\ncallbacks = [scoring, setter, early_stop, lr_scheduler]\n\nvalid_dataset = Dataset(X_val.values.astype(np.float32),Y_val.astype(np.float32))# custom validation dataset\nTabClassifier = TabSRALinearClassifier(**configs,train_split = predefined_split(valid_dataset),callbacks = callbacks)\n_ = TabClassifier.fit(X_train_.values.astype(np.float32),Y_train_.astype(np.float32))\n\n# prediction\nY_val_pred = TabClassifier.predict_proba(X_val.values.astype(np.float32))\nbest_aucroc = roc_auc_score(Y_val.astype(np.float32), Y_val_pred[:,1])\n\n# feature attribution\nattributions_val = TabClassifier.get_feature_attribution(X_val.values.astype(np.float32))\n\n# attention weights\nattentions_val = TabClassifier.get_attention(X_val.values.astype(np.float32))\n\n```\nKey parameters\nthe model parameters are preceded by ```module```.\n - ```module_n_head```: int (default=2)\n   Number of SRA head/ensemble. Bigger values gives capacity to the model to produce less stable/robust explanations.\n   Typical values are 1 or 2.\n  \n - ```module__dim_head```: int (default=8)\n   The attention head dimension , $d_k$ in the paper.\n   Typical values are {4,8,12}.\n   \n  - ```module__n_hidden_encoder```: int (default=1)\n   The number of hidden layers in  in the Key/Query encoder.\n   Typical values are {1,2}.\n\n - ```module__dropout_rate```: float (default=0.0) \n   The neuron dropout rate used  in the Key/Query encorder during the training.\n   \n - ```module__classifier_bias```: bool (default=True)\n   Whether to use bias term in the downstream linear classifier.\n   \n - ```optimizer```: (default=torch.optim.Adam)\n   \n - ```optimizer__lr```: float (default=0.05)\n   learning rate used for the training.\n   \n - ```max_epochs```: int (default=100)\n   Maximal number of training iterations.\n  \n - ```batch_size```: int (default=256)\n\n### Todo \nTabSRA package with sklearn interface\n\n### Acknowledgments\nThis work has been done in collaboration between BPCE Group, Laboratoire d'Informatique de Paris Nord (LIPN UMR 7030),  DAVID Lab UVSQ-Université Paris Saclay and was supported by the program Convention\nIndustrielle de Formation par la Recherche (CIFRE) of the Association Nationale de la Recherche et de la Technologie (ANRT).\n### Citations\n  If you find the code useful, please cite it by using the following BibTeX entry:\n  ```\n@article{amekoe2024exploring,\n  title={Exploring accuracy and interpretability trade-off in tabular learning with novel attention-based models},\n  author={Amekoe, Kodjo Mawuena and Azzag, Hanane and Dagdia, Zaineb Chelly and Lebbah, Mustapha and Jaffre, Gregoire},\n  journal={Neural Computing and Applications},\n  pages={1--29},\n  year={2024},\n  publisher={Springer}\n}\n  ```  \n  ```\n@inproceedings{kodjoEs23,\n author       = {Kodjo Mawuena Amekoe and\n                  Mohamed Djallel Dilmi and\n                  Hanene Azzag and\n                  Zaineb Chelly Dagdia and\n                    Mustapha Lebbah and\n                  Gregoire Jaffre},\n  title = {TabSRA: An Attention based Self-Explainable Model for Tabular Learning},\n booktitle = {The31th European Symposium on Artificial Neural Networks, Computational  Intelligence and Machine Learning (ESANN)},\n  year         = {2023}\n }\n  ```\n  ```\n@inproceedings{XKDD23,\n author       = {Kodjo Mawuena Amekoe and\n                  Hanene Azzag and\n                    Mustapha Lebbah and\n                  Zaineb Chelly Dagdia and\n                  Gregoire Jaffre},\n  title = {A New Class of Intelligible Models for Tabular Learning},\n booktitle = {In The 5th International Workshop on eXplainable Knowledge Discovery in Data Mining (PKDD)-ECML-PKDD},\n  year         = {2023}\n }\n  ```\n  ```\n  https://arxiv.org/abs/2305.11684\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanselmeamekoe%2Ftabsra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanselmeamekoe%2Ftabsra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanselmeamekoe%2Ftabsra/lists"}