<p align="center">
<a href="#readme">
<img alt="PowerShap logo" src="https://raw.githubusercontent.com/predict-idlab/powershap/main/powershap_full_scaled.png" width=70%>
</a>
</p>
[](https://pypi.org/project/powershap/)
[](https://img.shields.io/pypi/pyversions/powershap)
[](https://codecov.io/gh/predict-idlab/powershap)
[](https://pepy.tech/project/powershap)
[](http://makeapullrequest.com)
[](https://github.com/predict-idlab/powershap/actions/workflows/test.yml)
[](https://zenodo.org/badge/latestdoi/470633431)
> *powershap* is a **feature selection method** that uses statistical hypothesis testing and power calculations on **Shapley values**, enabling fast and intuitive wrapper-based feature selection.
## Installation ⚙️
| [**pip**](https://pypi.org/project/powershap/) | `pip install powershap` |
| ---| ----|
## Usage 🛠
*powershap* is built to be intuitive, it supports various models including linear, tree-based, and even deep learning models for classification and regression tasks.
<!-- It is also implented as sklearn `Transformer` component, allowing convenient integration in `sklearn` pipelines. -->
```py
from powershap import PowerShap
from catboost import CatBoostClassifier
X, y = ... # your classification dataset
selector = PowerShap(
model=CatBoostClassifier(n_estimators=250, verbose=0, use_best_model=True)
)
selector.fit(X, y) # Fit the PowerShap feature selector
selector.transform(X) # Reduce the dataset to the selected features
```
## Features ✨
* default automatic mode
* `scikit-learn` compatible
* supports various models
* insights into the feature selection method: call the `._processed_shaps_df` on a fitted `PowerSHAP` feature selector.
* tested code!
## Benchmarks ⏱
Check out our benchmark results [here](examples/results/).
## How does it work ⁉️
Powershap is built on the core assumption that *an informative feature will have a larger impact on the prediction compared to a known random feature.*
* Powershap trains multiple models with different random seeds on different subsets of the data. Each iteration it adds a random uniform feature to the dataset for training.
* In a single iteration after training a model, powershap calculates the absolute Shapley values of all features, including the random feature. If there are multiple outputs or multiple classes, powershap uses the maximum across these multiple outputs. These values are then averaged for each feature, symbolising the impact of the feature in this iteration.
* After performing all iterations, each feature then has an array of impacts. The impact array of each feature is then compared to the average of the random feature impact array using the percentile formula to provide a p-value. This tests whether the feature has a larger impact than the random feature and outputs a low p-value if true.
* Powershap then outputs all features with a p-value below the provided threshold. The threshold is by default 0.01.
### Automatic mode 🤖
The required number of iterations and the threshold values are hyperparameters of powershap. However, to *avoid manually optimizing the hyperparameters* powershap by default uses an automatic mode that automatically determines these hyperparameters.
* The automatic mode first starts with executing powershap using ten iterations.
* Then, for each feature powershap calculates the effect size and the statistical power of the test using a student-t power test.
* Using the calculated effect size, powershap then calculates the required iterations to achieve a predefined power requirement. By default this is 0.99, which represents a false positive probability of 0.01.
* If the required iterations are larger than the already performed iterations, powershap then further executes for the extra required iterations.
* Afterward, powershap re-calculates the required iterations and it keeps re-executing until the required iterations are met.
## Referencing our package :memo:
If you use *powershap* in a scientific publication, we would highly appreciate citing us as:
```bibtex
@InProceedings{10.1007/978-3-031-26387-3_5,
author="Verhaeghe, Jarne
and Van Der Donckt, Jeroen
and Ongenae, Femke
and Van Hoecke, Sofie",
title="Powershap: A Power-Full Shapley Feature Selection Method",
booktitle="Machine Learning and Knowledge Discovery in Databases",
year="2023",
publisher="Springer International Publishing",
address="Cham",
pages="71--87",
isbn="978-3-031-26387-3"
}
```
Paper was presented at ECML PKDD 2022. The manuscript can be found [here](https://link.springer.com/chapter/10.1007/978-3-031-26387-3_5) and on the github.
---
<p align="center">
👤 <i>Jarne Verhaeghe, Jeroen Van Der Donckt</i>
</p>
## License
This package is available under the MIT license. More information can be found here: https://github.com/predict-idlab/powershap/blob/main/LICENSE
Raw data
{
"_id": null,
"home_page": "https://github.com/predict-idlab/powershap",
"name": "powershap",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.12,>=3.9",
"maintainer_email": null,
"keywords": "feature selection, shap, data-science, machine learning",
"author": "Jarne Verhaeghe, Jeroen Van Der Donckt",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/03/8f/e6b08969614ec73569c77a63cdcb7c868301737a00b1d066cabe56e98846/powershap-0.0.10.tar.gz",
"platform": null,
"description": "\t\n<p align=\"center\">\n <a href=\"#readme\">\n <img alt=\"PowerShap logo\" src=\"https://raw.githubusercontent.com/predict-idlab/powershap/main/powershap_full_scaled.png\" width=70%>\n </a>\n</p>\n\n[](https://pypi.org/project/powershap/)\n[](https://img.shields.io/pypi/pyversions/powershap)\n[](https://codecov.io/gh/predict-idlab/powershap)\n[](https://pepy.tech/project/powershap)\n[](http://makeapullrequest.com)\n[](https://github.com/predict-idlab/powershap/actions/workflows/test.yml)\n[](https://zenodo.org/badge/latestdoi/470633431)\n\n> *powershap* is a **feature selection method** that uses statistical hypothesis testing and power calculations on **Shapley values**, enabling fast and intuitive wrapper-based feature selection. \n\n## Installation \u2699\ufe0f\n\n| [**pip**](https://pypi.org/project/powershap/) | `pip install powershap` | \n| ---| ----|\n\n## Usage \ud83d\udee0\n\n*powershap* is built to be intuitive, it supports various models including linear, tree-based, and even deep learning models for classification and regression tasks. \n<!-- It is also implented as sklearn `Transformer` component, allowing convenient integration in `sklearn` pipelines. -->\n\n```py\nfrom powershap import PowerShap\nfrom catboost import CatBoostClassifier\n\nX, y = ... # your classification dataset\n\nselector = PowerShap(\n model=CatBoostClassifier(n_estimators=250, verbose=0, use_best_model=True)\n)\n\nselector.fit(X, y) # Fit the PowerShap feature selector\nselector.transform(X) # Reduce the dataset to the selected features\n\n```\n\n## Features \u2728\n\n* default automatic mode\n* `scikit-learn` compatible\n* supports various models\n* insights into the feature selection method: call the `._processed_shaps_df` on a fitted `PowerSHAP` feature selector.\n* tested code!\n\n## Benchmarks \u23f1\n\nCheck out our benchmark results [here](examples/results/). \n\n## How does it work \u2049\ufe0f\n\nPowershap is built on the core assumption that *an informative feature will have a larger impact on the prediction compared to a known random feature.*\n\n* Powershap trains multiple models with different random seeds on different subsets of the data. Each iteration it adds a random uniform feature to the dataset for training.\n* In a single iteration after training a model, powershap calculates the absolute Shapley values of all features, including the random feature. If there are multiple outputs or multiple classes, powershap uses the maximum across these multiple outputs. These values are then averaged for each feature, symbolising the impact of the feature in this iteration.\n* After performing all iterations, each feature then has an array of impacts. The impact array of each feature is then compared to the average of the random feature impact array using the percentile formula to provide a p-value. This tests whether the feature has a larger impact than the random feature and outputs a low p-value if true. \n* Powershap then outputs all features with a p-value below the provided threshold. The threshold is by default 0.01.\n\n\n### Automatic mode \ud83e\udd16\n\nThe required number of iterations and the threshold values are hyperparameters of powershap. However, to *avoid manually optimizing the hyperparameters* powershap by default uses an automatic mode that automatically determines these hyperparameters. \n\n* The automatic mode first starts with executing powershap using ten iterations.\n* Then, for each feature powershap calculates the effect size and the statistical power of the test using a student-t power test. \n* Using the calculated effect size, powershap then calculates the required iterations to achieve a predefined power requirement. By default this is 0.99, which represents a false positive probability of 0.01.\n* If the required iterations are larger than the already performed iterations, powershap then further executes for the extra required iterations. \n* Afterward, powershap re-calculates the required iterations and it keeps re-executing until the required iterations are met.\n\n## Referencing our package :memo:\n\nIf you use *powershap* in a scientific publication, we would highly appreciate citing us as:\n\n```bibtex\n@InProceedings{10.1007/978-3-031-26387-3_5,\nauthor=\"Verhaeghe, Jarne\nand Van Der Donckt, Jeroen\nand Ongenae, Femke\nand Van Hoecke, Sofie\",\ntitle=\"Powershap: A Power-Full Shapley Feature Selection Method\",\nbooktitle=\"Machine Learning and Knowledge Discovery in Databases\",\nyear=\"2023\",\npublisher=\"Springer International Publishing\",\naddress=\"Cham\",\npages=\"71--87\",\nisbn=\"978-3-031-26387-3\"\n}\n```\n\nPaper was presented at ECML PKDD 2022. The manuscript can be found [here](https://link.springer.com/chapter/10.1007/978-3-031-26387-3_5) and on the github.\n\n---\n\n<p align=\"center\">\n\ud83d\udc64 <i>Jarne Verhaeghe, Jeroen Van Der Donckt</i>\n</p>\n\n## License\nThis package is available under the MIT license. More information can be found here: https://github.com/predict-idlab/powershap/blob/main/LICENSE\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Feature selection using statistical significance of shap values",
"version": "0.0.10",
"project_urls": {
"Homepage": "https://github.com/predict-idlab/powershap",
"Repository": "https://github.com/predict-idlab/powershap"
},
"split_keywords": [
"feature selection",
" shap",
" data-science",
" machine learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec52990bc00a60656918562a33757a2ef0492c776a276ba45772680a2da58762",
"md5": "c665c36e46fb176d8b6de764f441d6cf",
"sha256": "f3abf9fba4546e4e9b784a984e9dbc8af2f326258965d6df946d65a575683fe5"
},
"downloads": -1,
"filename": "powershap-0.0.10-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c665c36e46fb176d8b6de764f441d6cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.12,>=3.9",
"size": 15757,
"upload_time": "2024-05-02T08:02:13",
"upload_time_iso_8601": "2024-05-02T08:02:13.578657Z",
"url": "https://files.pythonhosted.org/packages/ec/52/990bc00a60656918562a33757a2ef0492c776a276ba45772680a2da58762/powershap-0.0.10-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "038fe6b08969614ec73569c77a63cdcb7c868301737a00b1d066cabe56e98846",
"md5": "b88d5c29594e934789b549a20c7ee284",
"sha256": "85b9b115889ed9b408985745c4386914dd3b0d13befb667198dc2a4c11b90591"
},
"downloads": -1,
"filename": "powershap-0.0.10.tar.gz",
"has_sig": false,
"md5_digest": "b88d5c29594e934789b549a20c7ee284",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.12,>=3.9",
"size": 15718,
"upload_time": "2024-05-02T08:02:15",
"upload_time_iso_8601": "2024-05-02T08:02:15.329438Z",
"url": "https://files.pythonhosted.org/packages/03/8f/e6b08969614ec73569c77a63cdcb7c868301737a00b1d066cabe56e98846/powershap-0.0.10.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 08:02:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "predict-idlab",
"github_project": "powershap",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "powershap"
}
JSON
