# PSyKE
Some quick links:
* [Home Page](https://apice.unibo.it/xwiki/bin/view/PSyKE/)
* [GitHub Repository](https://github.com/psykei/psyke-python)
* [PyPi Repository](https://pypi.org/project/psyke/)
* [Issues](https://github.com/psykei/psyke-python/issues)
## Intro
[PSyKE](https://apice.unibo.it/xwiki/bin/view/PSyKE/) (Platform for Symbolic Knowledge Extraction)
is intended as a library for extracting symbolic knowledge (in the form of logic rules) out of sub-symbolic predictors.
More precisely, PSyKE offers a general purpose API for knowledge extraction, and a number of different algorithms implementing it,
supporting both classification and regression problems.
The extracted knowledge consists of a Prolog theory (i.e., a list of Horn clauses) or an OWL ontology containing SWRL rules.
PSyKE relies on [2ppy](https://github.com/tuProlog/2ppy) (tuProlog in Python) for logic support, which in turn is based on the [2p-Kt](https://github.com/tuProlog/2p-kt) logic ecosystem.
### Class diagram overview:
<!--
To generate/edit the class diagram browse the URL above, after replacing `svg` with `uml`
-->
PSyKE is designed around the notion of _extractor_.
More precisely, an `Extractor` is any object capable of extracting a logic `Theory` out of a trained sub-symbolic regressor or classifier.
Accordingly, an `Extractor` is composed of
_(i)_ a trained predictor (i.e., black-box used as an oracle) and
_(ii)_ a set of feature descriptors, and it provides two methods:
* `extract`: returns a logic theory given a dataset;
* `predict`: predicts a value using the extracted rules (instead of the original predictor).
Currently, the supported extraction algorithms are:
* [CART](https://doi.org/10.1201/9781315139470),
straightforward extracts rules from both classification and regression decision trees;
* Classification:
* [REAL](http://dx.doi.org/10.1016/B978-1-55860-335-6.50013-1) (Rule Extraction As Learning),
generates and generalizes rules strarting from dataset samples;
* [Trepan](http://dx.doi.org/10.1016/B978-1-55860-335-6.50013-1),
generates rules by inducing a decision tree and possibly exploiting m-of-n expressions;
* Regression:
* [ITER](http://dx.doi.org/10.1007/11823728_26),
builds and iteratively expands hypercubes in the input space.
Each cube holds a constant value, that is the estimated output for the samples inside the cube;
* [GridEx](http://dx.doi.org/10.1007/978-3-030-82017-6_2),
extension of the ITER algorithm that produces shorter rule lists retaining higher fidelity w.r.t. the predictor.
* GridREx,
extension of GridEx where the output of each hypercube is a linear combination of the input variables and not a constant value.
Users may exploit the PEDRO algorithm, included in PSyKE, to tune the optimal values for GridEx and GridREx hyper-parameters.
We are working on PSyKE to extend its features to encompass explainable clustering tasks, as well as to make more general-purpose the supported extraction algorithms (e.g., by adding classification support to GridEx and GridREx).
## Users
### End users
PSyKE is deployed as a library on Pypi, and it can therefore be installed as Python package by running:
```bash
pip install psyke
```
#### Requirements
* `numpy`
* `pandas`
* `scikit-learn`
* `2ppy`
##### Test requirements
* `skl2onnx`
* `onnxruntime`
* `parameterized`
Once installed, it is possible to create an extractor from a predictor
(e.g. Neural Network, Support Vector Machine, K-Nearest Neighbor, Random Forest, etc.)
and from the dataset used to train the predictor.
> **Note:** the predictor must expose a method named `predict` to be properly used as an oracle.
#### End users
A brief example is presented in `demo.py` script in the `demo/` folder.
Using `sklearn`'s Iris dataset we train a K-Nearest Neighbor to predict the correct output class.
Before training, we make the dataset discrete.
After that we create two different extractors: REAL and Trepan.
We output the extracted theory for both extractors.
REAL extracted rules:
```
iris(PetalLength, PetalWidth, SepalLength, SepalWidth, setosa) :- PetalWidth =< 1.0.
iris(PetalLength1, PetalWidth1, SepalLength1, SepalWidth1, versicolor) :- PetalLength1 > 4.9, SepalWidth1 in [2.9, 3.2].
iris(PetalLength2, PetalWidth2, SepalLength2, SepalWidth2, versicolor) :- PetalWidth2 > 1.6.
iris(PetalLength3, PetalWidth3, SepalLength3, SepalWidth3, virginica) :- SepalWidth3 =< 2.9.
iris(PetalLength4, PetalWidth4, SepalLength4, SepalWidth4, virginica) :- SepalLength4 in [5.4, 6.3].
iris(PetalLength5, PetalWidth5, SepalLength5, SepalWidth5, virginica) :- PetalWidth5 in [1.0, 1.6].
```
Trepan extracted rules:
```
iris(PetalLength6, PetalWidth6, SepalLength6, SepalWidth6, virginica) :- PetalLength6 > 3.0, PetalLength6 in [3.0, 4.9].
iris(PetalLength7, PetalWidth7, SepalLength7, SepalWidth7, versicolor) :- PetalLength7 > 3.0.
iris(PetalLength8, PetalWidth8, SepalLength8, SepalWidth8, setosa) :- true.
```
## Developers
Working with PSyKE codebase requires a number of tools to be installed:
* Python 3.9
+ Python version greater than `3.9.x` are currently __not__ supported
* JDK 11+ (please ensure the `JAVA_HOME` environment variable is properly configured)
* Git 2.20+
### Develop PSyKE with PyCharm
To participate in the development of PSyKE, we suggest the [PyCharm](https://www.jetbrains.com/pycharm/) IDE.
#### Importing the project
1. Clone this repository in a folder of your preference using `git_clone` appropriately
2. Open PyCharm
3. Select `Open`
4. Navigate your file system and find the folder where you cloned the repository
5. Click `Open`
### Developing the project
Contributions to this project are welcome. Just some rules:
* We use [git flow](https://github.com/nvie/gitflow), so if you write new features, please do so in a separate `feature/` branch
* We recommend forking the project, developing your code, then contributing back via pull request
* Commit often
* Stay in sync with the `develop` (or `master`) branch (pull frequently if the build passes)
* Do not introduce low quality or untested code
#### Issue tracking
If you meet some problems in using or developing PSyKE, you are encouraged to signal it through the project
["Issues" section](https://github.com/psykei/psyke-python/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": "https://github.com/psykei/psyke-python",
"name": "psyke",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.10,>=3.9.0",
"maintainer_email": null,
"keywords": "knowledge extraction, symbolic ai, ske, extractor, rules, prolog",
"author": "Matteo Magnini",
"author_email": "matteo.magnini@unibo.it",
"download_url": "https://files.pythonhosted.org/packages/02/6d/fb753f71cc5c999d0abe0cd8747ba64dd8c21bc3905ebc9e165839835ede/psyke-0.8.9.tar.gz",
"platform": "Independant",
"description": "# PSyKE\n\n\n\nSome quick links:\n* [Home Page](https://apice.unibo.it/xwiki/bin/view/PSyKE/)\n* [GitHub Repository](https://github.com/psykei/psyke-python)\n* [PyPi Repository](https://pypi.org/project/psyke/)\n* [Issues](https://github.com/psykei/psyke-python/issues)\n\n## Intro\n\n[PSyKE](https://apice.unibo.it/xwiki/bin/view/PSyKE/) (Platform for Symbolic Knowledge Extraction)\nis intended as a library for extracting symbolic knowledge (in the form of logic rules) out of sub-symbolic predictors.\n\nMore precisely, PSyKE offers a general purpose API for knowledge extraction, and a number of different algorithms implementing it,\nsupporting both classification and regression problems.\nThe extracted knowledge consists of a Prolog theory (i.e., a list of Horn clauses) or an OWL ontology containing SWRL rules.\n\nPSyKE relies on [2ppy](https://github.com/tuProlog/2ppy) (tuProlog in Python) for logic support, which in turn is based on the [2p-Kt](https://github.com/tuProlog/2p-kt) logic ecosystem.\n\n### Class diagram overview:\n\n\n\n<!--\nTo generate/edit the class diagram browse the URL above, after replacing `svg` with `uml`\n-->\n\nPSyKE is designed around the notion of _extractor_.\nMore precisely, an `Extractor` is any object capable of extracting a logic `Theory` out of a trained sub-symbolic regressor or classifier.\nAccordingly, an `Extractor` is composed of \n_(i)_ a trained predictor (i.e., black-box used as an oracle) and \n_(ii)_ a set of feature descriptors, and it provides two methods:\n* `extract`: returns a logic theory given a dataset;\n* `predict`: predicts a value using the extracted rules (instead of the original predictor).\n\nCurrently, the supported extraction algorithms are:\n* [CART](https://doi.org/10.1201/9781315139470),\nstraightforward extracts rules from both classification and regression decision trees;\n* Classification:\n * [REAL](http://dx.doi.org/10.1016/B978-1-55860-335-6.50013-1) (Rule Extraction As Learning),\n generates and generalizes rules strarting from dataset samples;\n * [Trepan](http://dx.doi.org/10.1016/B978-1-55860-335-6.50013-1),\n generates rules by inducing a decision tree and possibly exploiting m-of-n expressions;\n* Regression:\n * [ITER](http://dx.doi.org/10.1007/11823728_26),\n builds and iteratively expands hypercubes in the input space.\n Each cube holds a constant value, that is the estimated output for the samples inside the cube;\n * [GridEx](http://dx.doi.org/10.1007/978-3-030-82017-6_2),\n extension of the ITER algorithm that produces shorter rule lists retaining higher fidelity w.r.t. the predictor.\n * GridREx,\n extension of GridEx where the output of each hypercube is a linear combination of the input variables and not a constant value.\n \nUsers may exploit the PEDRO algorithm, included in PSyKE, to tune the optimal values for GridEx and GridREx hyper-parameters.\n\nWe are working on PSyKE to extend its features to encompass explainable clustering tasks, as well as to make more general-purpose the supported extraction algorithms (e.g., by adding classification support to GridEx and GridREx).\n\n## Users\n\n### End users\n\nPSyKE is deployed as a library on Pypi, and it can therefore be installed as Python package by running:\n```bash\npip install psyke\n```\n\n#### Requirements\n* `numpy`\n* `pandas`\n* `scikit-learn`\n* `2ppy`\n\n##### Test requirements\n* `skl2onnx`\n* `onnxruntime`\n* `parameterized`\n\nOnce installed, it is possible to create an extractor from a predictor \n(e.g. Neural Network, Support Vector Machine, K-Nearest Neighbor, Random Forest, etc.)\nand from the dataset used to train the predictor.\n\n> **Note:** the predictor must expose a method named `predict` to be properly used as an oracle.\n\n#### End users\n\nA brief example is presented in `demo.py` script in the `demo/` folder.\nUsing `sklearn`'s Iris dataset we train a K-Nearest Neighbor to predict the correct output class.\nBefore training, we make the dataset discrete.\nAfter that we create two different extractors: REAL and Trepan.\nWe output the extracted theory for both extractors.\n\nREAL extracted rules:\n```\niris(PetalLength, PetalWidth, SepalLength, SepalWidth, setosa) :- PetalWidth =< 1.0.\niris(PetalLength1, PetalWidth1, SepalLength1, SepalWidth1, versicolor) :- PetalLength1 > 4.9, SepalWidth1 in [2.9, 3.2].\niris(PetalLength2, PetalWidth2, SepalLength2, SepalWidth2, versicolor) :- PetalWidth2 > 1.6.\niris(PetalLength3, PetalWidth3, SepalLength3, SepalWidth3, virginica) :- SepalWidth3 =< 2.9.\niris(PetalLength4, PetalWidth4, SepalLength4, SepalWidth4, virginica) :- SepalLength4 in [5.4, 6.3].\niris(PetalLength5, PetalWidth5, SepalLength5, SepalWidth5, virginica) :- PetalWidth5 in [1.0, 1.6].\n```\n\nTrepan extracted rules:\n```\niris(PetalLength6, PetalWidth6, SepalLength6, SepalWidth6, virginica) :- PetalLength6 > 3.0, PetalLength6 in [3.0, 4.9].\niris(PetalLength7, PetalWidth7, SepalLength7, SepalWidth7, versicolor) :- PetalLength7 > 3.0.\niris(PetalLength8, PetalWidth8, SepalLength8, SepalWidth8, setosa) :- true.\n```\n\n\n## Developers\n\nWorking with PSyKE codebase requires a number of tools to be installed:\n* Python 3.9\n + Python version greater than `3.9.x` are currently __not__ supported\n\n* JDK 11+ (please ensure the `JAVA_HOME` environment variable is properly configured)\n* Git 2.20+\n\n### Develop PSyKE with PyCharm\n\nTo participate in the development of PSyKE, we suggest the [PyCharm](https://www.jetbrains.com/pycharm/) IDE.\n\n#### Importing the project\n\n1. Clone this repository in a folder of your preference using `git_clone` appropriately\n2. Open PyCharm\n3. Select `Open`\n4. Navigate your file system and find the folder where you cloned the repository\n5. Click `Open`\n\n### Developing the project\n\nContributions to this project are welcome. Just some rules:\n* We use [git flow](https://github.com/nvie/gitflow), so if you write new features, please do so in a separate `feature/` branch\n* We recommend forking the project, developing your code, then contributing back via pull request\n* Commit often\n* Stay in sync with the `develop` (or `master`) branch (pull frequently if the build passes)\n* Do not introduce low quality or untested code\n\n#### Issue tracking\nIf you meet some problems in using or developing PSyKE, you are encouraged to signal it through the project\n[\"Issues\" section](https://github.com/psykei/psyke-python/issues) on GitHub.\n",
"bugtrack_url": null,
"license": "Apache 2.0 License",
"summary": "Python-based implementation of PSyKE, i.e. a Platform for Symbolic Knowledge Extraction",
"version": "0.8.9",
"project_urls": {
"Bug Reports": "https://github.com/psykei/psyke-python/issues",
"Homepage": "https://github.com/psykei/psyke-python",
"Source": "https://github.com/psykei/psyke-python"
},
"split_keywords": [
"knowledge extraction",
" symbolic ai",
" ske",
" extractor",
" rules",
" prolog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42c9f9e17db3562a962edf3be9325cefb7b19ae559e7b45e8b4c7e713f1f10f9",
"md5": "f70ebcbe0de5de75904e7fb7e49f8bb2",
"sha256": "a4276361aecdf70a25ed5ae866a1bb69ec8333be89bbb986f0dfc7d97bdf78bc"
},
"downloads": -1,
"filename": "psyke-0.8.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f70ebcbe0de5de75904e7fb7e49f8bb2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.10,>=3.9.0",
"size": 66278,
"upload_time": "2024-05-05T01:16:10",
"upload_time_iso_8601": "2024-05-05T01:16:10.600868Z",
"url": "https://files.pythonhosted.org/packages/42/c9/f9e17db3562a962edf3be9325cefb7b19ae559e7b45e8b4c7e713f1f10f9/psyke-0.8.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "026dfb753f71cc5c999d0abe0cd8747ba64dd8c21bc3905ebc9e165839835ede",
"md5": "e14b3d4a0be2f0b6f7dc55e2d884ce8a",
"sha256": "40f5d726915333411be5253a9631b781a21a122257e9f8e1e7ce1141057c4c55"
},
"downloads": -1,
"filename": "psyke-0.8.9.tar.gz",
"has_sig": false,
"md5_digest": "e14b3d4a0be2f0b6f7dc55e2d884ce8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.10,>=3.9.0",
"size": 65619,
"upload_time": "2024-05-05T01:16:14",
"upload_time_iso_8601": "2024-05-05T01:16:14.276848Z",
"url": "https://files.pythonhosted.org/packages/02/6d/fb753f71cc5c999d0abe0cd8747ba64dd8c21bc3905ebc9e165839835ede/psyke-0.8.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-05 01:16:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "psykei",
"github_project": "psyke-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "build",
"specs": [
[
"==",
"1.2.2.post1"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.3"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "2ppy",
"specs": [
[
"==",
"0.4.1"
]
]
},
{
"name": "skl2onnx",
"specs": [
[
"==",
"1.18.0"
]
]
},
{
"name": "onnxruntime",
"specs": [
[
"==",
"1.19.2"
]
]
},
{
"name": "tensorflow",
"specs": [
[
"==",
"2.16.2"
]
]
},
{
"name": "parameterized",
"specs": [
[
"==",
"0.9.0"
]
]
},
{
"name": "protobuf",
"specs": [
[
"==",
"4.25.5"
]
]
},
{
"name": "setuptools",
"specs": [
[
"==",
"75.8.0"
]
]
},
{
"name": "kneed",
"specs": [
[
"==",
"0.8.5"
]
]
},
{
"name": "sympy",
"specs": [
[
"==",
"1.13.3"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.9.4"
]
]
},
{
"name": "joblib",
"specs": [
[
"==",
"1.4.2"
]
]
}
],
"lcname": "psyke"
}
JSON
