Package: psyke
PSyKESome quick links:Home PageGitHub RepositoryPyPi RepositoryIssuesIntroPSyKE(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 on2ppy(tuProlog in Python) for logic support, which in turn is based on the2p-Ktlogic ecosystem.Class diagram overview:PSyKE is designed around the notion ofextractor.
More precisely, anExtractoris any object capable of extracting a logicTheoryout of a trained sub-symbolic regressor or classifier.
Accordingly, anExtractoris 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,
straightforward extracts rules from both classification and regression decision trees;Classification:REAL(Rule Extraction As Learning),
generates and generalizes rules strarting from dataset samples;Trepan,
generates rules by inducing a decision tree and possibly exploiting m-of-n expressions;Regression:ITER,
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,
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).UsersEnd usersPSyKE is deployed as a library on Pypi, and it can therefore be installed as Python package by running:pipinstallpsykeRequirementsnumpypandasscikit-learn2ppyTest requirementsskl2onnxonnxruntimeparameterizedOnce 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 namedpredictto be properly used as an oracle.End usersA brief example is presented indemo.pyscript in thedemo/folder.
Usingsklearn'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.DevelopersWorking with PSyKE codebase requires a number of tools to be installed:Python 3.9Python version greater than3.9.xare currentlynotsupportedJDK 11+ (please ensure theJAVA_HOMEenvironment variable is properly configured)Git 2.20+Develop PSyKE with PyCharmTo participate in the development of PSyKE, we suggest thePyCharmIDE.Importing the projectClone this repository in a folder of your preference usinggit_cloneappropriatelyOpen PyCharmSelectOpenNavigate your file system and find the folder where you cloned the repositoryClickOpenDeveloping the projectContributions to this project are welcome. Just some rules:We usegit flow, so if you write new features, please do so in a separatefeature/branchWe recommend forking the project, developing your code, then contributing back via pull requestCommit oftenStay in sync with thedevelop(ormaster) branch (pull frequently if the build passes)Do not introduce low quality or untested codeIssue trackingIf you meet some problems in using or developing PSyKE, you are encouraged to signal it through the project"Issues" sectionon GitHub.