RuleKit 2

Rule-based models are often used for data analysis as they combine interpretability with predictive power. We present RuleKit 2, a versatile tool for rule learning. Based on a sequential covering induction algorithm, it is suitable for classification, regression, and survival problems. The presence of user-guided induction mode facilitates verifying hypotheses concerning data dependencies which are expected or of interest. The powerful and flexible experimental environment allows straightforward investigation of different induction schemes. Unlike the first revision, RuleKit 2 does not depend on RapidMiner. The analysis can be performed in batch mode and through Python package. A documented Java API is also provided for convenience. Running RuleKit as a RapidMiner plugin and R package is no longer supported in version 2.

RuleKit provides latest versions of our algorithms (some of them were initially published as independent packages and integrated later):

• LR-Rules (Wróbel et al, 2017) - survival rules induction,
• GuideR (Sikora et al, 2019) - user-guided induction.
• RuleKit-CS (Gudyś et al, 2024) - contrast set mining.

Getting started

In the following subsections we provide a brief introduction on how to install and use RuleKit batch interface. The software requires Java Development Kit in version 8 (version 1.8.0 tested) to work properly. In Windows one can download the installer from Oracle webpage. In Linux, a system package manager should be used instead. For instance, in Ubuntu 16.04 execute the following command:

sudo apt-get install default-jdk

Batch interface

In order to use batch mode, please download rulekit-<version>-all.jar file from the releases folder. Alternatively, one can build the package from the sources by running the following commands in the adaa.analytics.rules directory of this repository. Windows:

gradlew -b build.gradle rjar

Linux:

./gradlew -b build.gradle rjar

The JAR file will be placed in adaa.analytics.rules/build/libs subdirectory. Once the package has been downloaded/built, the analysis can be performed. The example batch experiment concerns the problem of classifying whether a person making a purchase will be a future customer. The corresponding dataset is named deals and is split into train and test parts (download). To run the experiment, copy RuleKit JAR file into ./examples folder of the repository and execute:

java -jar rulekit-<version>-all.jar minimal-deals.xml

Ignore the SLF4J warning reported on the console - it does not affect the procedure. The results of the analysis will be located in ./examples/results-minimal/deals/ folder. Note, that the repository already contains reference results - they will be overwritten. See this Wiki section for detailed information on how to configure batch analyses in RuleKit.

Python package

Rulekit Python package can be found here

Documentation

The detailed RuleKit documentation can be found on Wiki pages which cover the following topics:

1. Batch interface
   1. General information
   2. Parameter set definition
   3. Dataset definition
   4. Example
2. RapidMiner plugin
   1. Installation
   2. Usage
   3. Example
3. R package
   1. Installation
   2. Usage
   3. Example
4. Quality and evaluation
   1. Rule quality
   2. Model characteristics
   3. Performance metrices
5. Output files
   1. Training report
   2. Prediction performance report
6. User-guided induction
   1. Defining user's knowledge
   2. Examples from GuideR paper
7. Library API
   1. Running an experiment
   2. Developing a new algorithm
8. Empirical results
9. Contrast set mining

JavaDoc for the project is available here.

Datasets

The repository contains the datasets used in the GuideR study. We also provide the latest UCI revision of the Bone marrow transplant: children dataset. We recommend using this dataset at it contains lots of improvements compared to the previous release (e.g., textual encoding of attribute values).

Authors and licensing

RuleKit Development Team:

• Adam Gudyś
• Łukasz Wróbel
• Marek Sikora

Contributors:

• Wojciech Górka
• Joanna Henzel
• Paweł Matyszok
• Wojciech Sikora

The software is publicly available under GNU AGPL-3.0 license.

Commercial applications

The software is publicly available under GNU AGPL-3.0 license. Any derivative work obtained under this license must be licensed under the AGPL if this derivative work is distributed to a third party. For commercial projects that require the ability to distribute RuleKit code as part of a program that cannot be distributed under the AGPL, it may be possible to obtain an appropriate license from the authors.

Citing

Gudyś, A, Sikora, M, Wróbel, Ł (2024) Separate and conquer heuristic allows robust mining of contrast sets in classification, regression, and survival data, Expert Systems with Applications, 248: 123376

Gudyś, A, Sikora, M, Wróbel, Ł (2020) RuleKit: A comprehensive suite for rule-based learning, Knowledge-Based Systems, 194: 105480

Sikora, M, Wróbel, Ł, Gudyś, A (2019) GuideR: a guided separate-and-conquer rule learning in classification, regression, and survival settings, Knowledge-Based Systems, 173:1-14.

Wróbel, Ł, Gudyś, A, Sikora, M (2017) Learning rule sets from survival data, BMC Bioinformatics, 18(1):285.