{"id":33115144,"url":"https://github.com/givasile/effector","last_synced_at":"2026-04-05T01:31:57.678Z","repository":{"id":227473370,"uuid":"476206307","full_name":"givasile/effector","owner":"givasile","description":"Effector - a Python package for global and regional effect methods","archived":false,"fork":false,"pushed_at":"2026-01-14T13:58:56.000Z","size":157827,"stargazers_count":117,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-26T06:22:30.122Z","etag":null,"topics":["explainability","iml","xai"],"latest_commit_sha":null,"homepage":"https://xai-effector.github.io/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/givasile.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-03-31T07:54:32.000Z","updated_at":"2025-11-24T14:42:38.000Z","dependencies_parsed_at":"2025-02-27T11:32:19.447Z","dependency_job_id":"b9cb32f1-a119-4ed4-b42c-c9263576ec3c","html_url":"https://github.com/givasile/effector","commit_stats":null,"previous_names":["givasile/effector"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/givasile/effector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/givasile%2Feffector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/givasile%2Feffector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/givasile%2Feffector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/givasile%2Feffector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/givasile","download_url":"https://codeload.github.com/givasile/effector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/givasile%2Feffector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31421869,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T00:25:07.052Z","status":"ssl_error","status_checked_at":"2026-04-05T00:25:05.923Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["explainability","iml","xai"],"created_at":"2025-11-15T02:00:25.341Z","updated_at":"2026-04-05T01:31:57.660Z","avatar_url":"https://github.com/givasile.png","language":"Jupyter Notebook","readme":"# Effector\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/static/effector_logo.png\" width=\"500\"/\u003e\n\u003c/p\u003e\n\n[![PyPI version](https://badge.fury.io/py/effector.svg?icon=si%3Apython)](https://badge.fury.io/py/effector)\n![Execute Tests](https://github.com/givasile/effector/actions/workflows/run_tests.yml/badge.svg)\n[![codecov](https://codecov.io/gh/givasile/effector/branch/main/graph/badge.svg)](https://codecov.io/gh/givasile/effector)\n![Publish Documentation](https://github.com/givasile/effector/actions/workflows/publish_documentation.yml/badge.svg)\n[![PyPI Downloads](https://static.pepy.tech/badge/effector)](https://pepy.tech/projects/effector)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\n---\n\n`effector` an eXplainable AI package for **tabular data**. It:\n\n- creates [global and regional](https://xai-effector.github.io/quickstart/global_and_regional_effects/) effect plots\n- has a [simple API](https://xai-effector.github.io/quickstart/simple_api/) with smart defaults, but can become [flexible](https://xai-effector.github.io/quickstart/flexible_api/) if needed\n- is model agnostic; can explain [any underlying ML model](https://xai-effector.github.io/)\n- integrates easily with popular ML libraries, like [Scikit-Learn, Tensorflow and Pytorch](https://xai-effector.github.io/quickstart/simple_api/#__tabbed_2_2)\n- is fast, for both [global](https://xai-effector.github.io/notebooks/guides/efficiency_global/) and [regional](https://xai-effector.github.io/notebooks/guides/efficiency_global/) methods\n- provides a large collection of [global and regional effects methods](https://xai-effector.github.io/#supported-methods)\n\n---\n\n📖 [Documentation](https://xai-effector.github.io/) | 🔍 [Intro to global and regional effects](https://xai-effector.github.io/quickstart/global_and_regional_effects/) | 🔧 [API](https://xai-effector.github.io/api/) | 🏗 [Examples](https://xai-effector.github.io/examples)\n\n---\n\n## Installation\n\nEffector requires Python 3.10+:\n\n```bash\npip install effector\n```\n\nDependencies: `numpy`, `scipy`, `matplotlib`, `tqdm`, `shap`.\n\n---\n\n## Quickstart\n\n### Train an ML model\n\n```python\nimport effector\nimport keras\nimport numpy as np\nimport tensorflow as tf\n\nnp.random.seed(42)\ntf.random.set_seed(42)\n\n# Load dataset\nbike_sharing = effector.datasets.BikeSharing(pcg_train=0.8)\nX_train, Y_train = bike_sharing.x_train, bike_sharing.y_train\nX_test, Y_test = bike_sharing.x_test, bike_sharing.y_test\n\n# Define and train a neural network\nmodel = keras.Sequential([\n    keras.layers.Dense(1024, activation=\"relu\"),\n    keras.layers.Dense(512, activation=\"relu\"),\n    keras.layers.Dense(256, activation=\"relu\"),\n    keras.layers.Dense(1)\n])\nmodel.compile(optimizer=\"adam\", loss=\"mse\", metrics=[\"mae\", keras.metrics.RootMeanSquaredError()])\nmodel.fit(X_train, Y_train, batch_size=512, epochs=20, verbose=1)\nmodel.evaluate(X_test, Y_test, verbose=1)\n```\n\n### Wrap it in a callable\n\n```python\ndef predict(x):\n    return model(x).numpy().squeeze()\n```\n\n### Explain it with global effect plots\n\n```python\n# Initialize the Partial Dependence Plot (PDP) object\npdp = effector.PDP(\n    X_test,  # Use the test set as background data\n    predict,  # Prediction function\n    feature_names=bike_sharing.feature_names,  # (optional) Feature names\n    target_name=bike_sharing.target_name  # (optional) Target variable name\n)\n\n# Plot the effect of a feature\npdp.plot(\n    feature=3,  # Select the 3rd feature (feature: hour)\n    nof_ice=200,  # (optional) Number of Individual Conditional Expectation (ICE) curves to plot\n    scale_x={\"mean\": bike_sharing.x_test_mu[3], \"std\": bike_sharing.x_test_std[3]},  # (optional) Scale x-axis\n    scale_y={\"mean\": bike_sharing.y_test_mu, \"std\": bike_sharing.y_test_std},  # (optional) Scale y-axis\n    centering=True,  # (optional) Center PDP and ICE curves\n    show_avg_output=True,  # (optional) Display the average prediction\n    y_limits=[-200, 1000]  # (optional) Set y-axis limits\n)\n```\n\n![Feature effect plot](https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_3_0.png)\n\n### Explain it with regional effect plots\n\n```python\n# Initialize the Regional Partial Dependence Plot (RegionalPDP)\nr_pdp = effector.RegionalPDP(\n    X_test,  # Test set data\n    predict,  # Prediction function\n    feature_names=bike_sharing.feature_names,  # Feature names\n    target_name=bike_sharing.target_name  # Target variable name\n)\n\n# Summarize the subregions of the 3rd feature (temperature)\nr_pdp.summary(\n    features=3,  # Select the 3rd feature for the summary\n    scale_x_list=[  # scale each feature with mean and std\n        {\"mean\": bike_sharing.x_test_mu[i], \"std\": bike_sharing.x_test_std[i]}\n        for i in range(X_test.shape[1])\n    ]\n)\n```\n\n```\nFeature 3 - Full partition tree:\n🌳 Full Tree Structure:\n───────────────────────\nhr 🔹 [id: 0 | heter: 0.43 | inst: 3476 | w: 1.00]\n    workingday = 0.00 🔹 [id: 1 | heter: 0.36 | inst: 1129 | w: 0.32]\n        temp ≤ 6.50 🔹 [id: 3 | heter: 0.17 | inst: 568 | w: 0.16]\n        temp \u003e 6.50 🔹 [id: 4 | heter: 0.21 | inst: 561 | w: 0.16]\n    workingday ≠ 0.00 🔹 [id: 2 | heter: 0.28 | inst: 2347 | w: 0.68]\n        temp ≤ 6.50 🔹 [id: 5 | heter: 0.19 | inst: 953 | w: 0.27]\n        temp \u003e 6.50 🔹 [id: 6 | heter: 0.20 | inst: 1394 | w: 0.40]\n--------------------------------------------------\nFeature 3 - Statistics per tree level:\n🌳 Tree Summary:\n─────────────────\nLevel 0🔹heter: 0.43\n    Level 1🔹heter: 0.31 | 🔻0.12 (28.15%)\n        Level 2🔹heter: 0.19 | 🔻0.11 (37.10%)\n```\n\nThe summary of feature `hr` (hour) says that its effect on the output is highly dependent on the value of features:\n- `workingday`, wheteher it is a workingday or not\n- `temp`, what is the temperature the specific hour\n\nLet's see how the effect changes on these subregions!\n\n---\n#### Is it workingday or not?\n\n```python\n# Plot regional effects after the first-level split (workingday vs non-workingday)\nfor node_idx in [1, 2]:  # Iterate over the nodes of the first-level split\n    r_pdp.plot(\n        feature=3,  # Feature 3 (temperature)\n        node_idx=node_idx,  # Node index (1: workingday, 2: non-workingday)\n        nof_ice=200,  # Number of ICE curves\n        scale_x_list=[  # Scale features by mean and std\n            {\"mean\": bike_sharing.x_test_mu[i], \"std\": bike_sharing.x_test_std[i]}\n            for i in range(X_test.shape[1])\n        ],\n        scale_y={\"mean\": bike_sharing.y_test_mu, \"std\": bike_sharing.y_test_std},  # Scale the target\n        y_limits=[-200, 1000]  # Set y-axis limits\n    )\n```\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_5_0.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_5_1.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\n#### Is it hot or cold?\n\n```python\n# Plot regional effects after second-level splits (workingday vs non-workingday and hot vs cold temperature)\nfor node_idx in [3, 4, 5, 6]:  # Iterate over the nodes of the second-level splits\n    r_pdp.plot(\n        feature=3,  # Feature 3 (temperature)\n        node_idx=node_idx,  # Node index (hot/cold temperature and workingday/non-workingday)\n        nof_ice=200,  # Number of ICE curves\n        scale_x_list=[  # Scale features by mean and std\n            {\"mean\": bike_sharing.x_test_mu[i], \"std\": bike_sharing.x_test_std[i]}\n            for i in range(X_test.shape[1])\n        ],\n        scale_y={\"mean\": bike_sharing.y_test_mu, \"std\": bike_sharing.y_test_std},  # Scale target\n        y_limits=[-200, 1000]  # Set y-axis limits\n    )\n\n```\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_6_0.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_6_1.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_6_2.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/notebooks/quickstart/readme_example_files/readme_example_6_3.png\" alt=\"Feature effect plot\"\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Supported Methods\n\n`effector` implements global and regional effect methods:\n\n| Method  | Global Effect  | Regional Effect | Reference | ML model          | Speed                                        |\n|---------|----------------|-----------------|-----------|-------------------|----------------------------------------------|\n| PDP     | `PDP`          | `RegionalPDP`   | [PDP](https://projecteuclid.org/euclid.aos/1013203451) | any               | Fast for a small dataset                     |\n| d-PDP   | `DerPDP`       | `RegionalDerPDP`| [d-PDP](https://arxiv.org/abs/1309.6392) | differentiable    | Fast for a small dataset      |\n| ALE     | `ALE`          | `RegionalALE`   | [ALE](https://academic.oup.com/jrsssb/article/82/4/1059/7056085) | any | Fast                                         |\n| RHALE   | `RHALE`        | `RegionalRHALE` | [RHALE](https://ebooks.iospress.nl/doi/10.3233/FAIA230354) | differentiable    | Very fast                                    |\n| SHAP-DP | `ShapDP`       | `RegionalShapDP`| [SHAP](https://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions) | any | Fast for a small dataset and a light ML model |\n\n---\n\n## Method Selection Guide\n\nFrom the runtime persepective there are three criterias:\n\n- is the dataset `small` (N\u003c10K) or `large` (N\u003e10K instances) ? \n- is the ML model `light` (runtime \u003c 0.1s) or `heavy` (runtime \u003e 0.1s) ?\n- is the ML model `differentiable` or `non-differentiable` ?\n\nTrust us and follow this guide:\n\n- `light` + `small` + `differentiable` = `any([PDP, RHALE, ShapDP, ALE, DerPDP])` \n- `light` + `small` + `non-differentiable`: `[PDP, ALE, ShapDP]`\n- `heavy` + `small` + `differentiable` = `any([PDP, RHALE, ALE, DerPDP])`\n- `heavy` + `small` + `non differentiable` = `any([PDP, ALE])`\n- `big` +  `not differentiable` = `ALE`\n- `big` +  `differentiable` = `RHALE` \n\n---\n\n## Citation\n\nIf you use `effector`, please cite it:\n\n```bibtex\n@misc{gkolemis2024effector,\n  title={effector: A Python package for regional explanations},\n  author={Vasilis Gkolemis et al.},\n  year={2024},\n  eprint={2404.02629},\n  archivePrefix={arXiv},\n  primaryClass={cs.LG}\n}\n```\n\n---\n\n## Spotlight on `effector`\n\n### 📚 Featured Publications  \n- **Gkolemis, Vasilis, et al.**  \n  *\"Fast and Accurate Regional Effect Plots for Automated Tabular Data Analysis.\"*  \n  [Proceedings of the VLDB Endowment](https://vldb.org/workshops/2024/proceedings/TaDA/TaDA.5.pdf) | ISSN 2150-8097  \n\n### 🎤 Talks \u0026 Presentations  \n- **LMU-IML Group Talk**  \n  [Slides \u0026 Materials](https://github.com/givasile/effector-paper/tree/main/presentation-general) | [LMU-IML Research](https://www.slds.stat.uni-muenchen.de/research/explainable-ai.html)  \n- **AIDAPT Plenary Meeting**  \n  [Deep dive into effector](https://github.com/givasile/presentation-aidapt-xai-effector/tree/main)  \n- **XAI World Conference 2024**  \n  [Poster](https://github.com/givasile/effector-paper/blob/main/poster-general/main.pdf) | [Paper](https://github.com/givasile/effector-paper/blob/main/xai-conference-submission/effector_xai_conf.pdf)  \n\n### 🌍 Adoption \u0026 Collaborations  \n- **[AIDAPT Project](https://www.ai-dapt.eu/effector/)**  \n  Leveraging `effector` for explainable AI solutions.  \n\n### 🔍 Additional Resources  \n\n- **Medium Post**  \n  [Effector: An eXplainability Library for Global and Regional Effects](https://medium.com/@ntipakos/effector-bfe17206672c)\n\n- **Courses \u0026 Lists**:  \n  [IML Course @ LMU](https://slds-lmu.github.io/iml/)  \n  [Awesome ML Interpretability](https://github.com/jphall663/awesome-machine-learning-interpretability)  \n  [Awesome XAI](https://github.com/wangyongjie-ntu/Awesome-explainable-AI)  \n  [Best of ML Python](https://github.com/ml-tooling/best-of-ml-python)  \n\n### 📚 Related Publications\n\nPapers that have inspired `effector`:\n\n- **REPID: Regional Effects in Predictive Models**  \n  Herbinger et al., 2022 - [Link](https://proceedings.mlr.press/v151/herbinger22a)  \n\n- **Decomposing Global Feature Effects Based on Feature Interactions**  \n  Herbinger et al., 2023 - [Link](https://arxiv.org/pdf/2306.00541.pdf)  \n\n- **RHALE: Robust Heterogeneity-Aware Effects**  \n  Gkolemis Vasilis et al., 2023 - [Link](https://ebooks.iospress.nl/doi/10.3233/FAIA230354)  \n\n- **DALE: Decomposing Global Feature Effects**  \n  Gkolemis Vasilis et al., 2023 - [Link](https://proceedings.mlr.press/v189/gkolemis23a/gkolemis23a.pdf)  \n\n- **Greedy Function Approximation: A Gradient Boosting Machine**  \n  Friedman, 2001 - [Link](https://projecteuclid.org/euclid.aos/1013203451)  \n\n- **Visualizing Predictor Effects in Black-Box Models**  \n  Apley, 2016 - [Link](https://arxiv.org/abs/1612.08468)  \n\n- **SHAP: A Unified Approach to Model Interpretation**  \n  Lundberg \u0026 Lee, 2017 - [Link](https://papers.nips.cc/paper/7062-a-unified-approach-to-interpreting-model-predictions)  \n\n- **Regionally Additive Models: Explainable-by-design models minimizing feature interactions**  \n  Gkolemis Vasilis et al., 2023 - [Link](https://arxiv.org/abs/2309.12215)\n\n---\n\n## License\n\n`effector` is released under the [MIT License](https://github.com/givasile/effector/blob/main/LICENSE).\n\n\n\n---\n\n## Powered by:\n\n- **[AIDAPT](https://www.ai-dapt.eu/)**  \n  \u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/static/aidapt_logo.png\" width=\"130\"/\u003e\n\n- **XMANAI**  \n\u003cimg src=\"https://raw.githubusercontent.com/givasile/effector/main/docs/docs/static/xmanai_logo.jpg\" width=\"70\"/\u003e","funding_links":[],"categories":["Python Libraries(sort in alphabeta order)","Tools","Technical Resources"],"sub_categories":["Evaluation methods","Interpretability/Explicability","Open Source/Access Responsible AI Software Packages"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgivasile%2Feffector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgivasile%2Feffector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgivasile%2Feffector/lists"}