Ripple Down Rules (RDR)
A python implementation of the various ripple down rules versions, including Single Classification (SCRDR), Multi Classification (MCRDR), and Generalised Ripple Down Rules (GRDR).
SCRDR, MCRDR, and GRDR are rule-based classifiers that are built incrementally, and can be used to classify data cases. The rules are refined as new data cases are classified.
SCRDR, MCRDR, and GRDR implementation were inspired from the book: "Ripple Down Rules: An Alternative to Machine Learning" by Paul Compton, Byeong Ho Kang.
Installation
sudo apt-get install graphviz graphviz-dev
pip install ripple_down_rules
For GUI support, also install:
sudo apt-get install libxcb-cursor-dev
Documentation
Read the documentation here.
Example Usage
Propositional Example
By propositional, I mean that each rule conclusion is a propositional logic statement with a constant value.
For this example, we will use the UCI Zoo dataset to classify animals into their species based on their features. The dataset contains 101 animals with 16 features, and the target is th e species of the animal.
To install the dataset:
pip install ucimlrepo
from __future__ import annotations
from ripple_down_rules.datastructures.dataclasses import CaseQuery
from ripple_down_rules.datastructures.case import create_cases_from_dataframe
from ripple_down_rules.rdr import GeneralRDR
from ripple_down_rules.utils import render_tree
from ucimlrepo import fetch_ucirepo
from enum import Enum
class Species(str, Enum):
"""Enum for the species of the animals in the UCI Zoo dataset."""
mammal = "mammal"
bird = "bird"
reptile = "reptile"
fish = "fish"
amphibian = "amphibian"
insect = "insect"
molusc = "molusc"
@classmethod
def from_str(cls, value: str) -> Species:
return getattr(cls, value)
# fetch dataset
zoo = fetch_ucirepo(id=111)
# data (as pandas dataframes)
X = zoo.data.features
y = zoo.data.targets
# This is a utility that allows each row to be a Case instance,
# which simplifies access to column values using dot notation.
all_cases = create_cases_from_dataframe(X, name="Animal")
# The targets are the species of the animals
category_names = ["mammal", "bird", "reptile", "fish", "amphibian", "insect", "molusc"]
category_id_to_name = {i + 1: name for i, name in enumerate(category_names)}
targets = [Species.from_str(category_id_to_name[i]) for i in y.values.flatten()]
# Now that we are done with the data preparation, we can create and use the Ripple Down Rules classifier.
grdr = GeneralRDR()
# Fit the GRDR to the data
case_queries = [CaseQuery(case, 'species', type(target), True, _target=target)
for case, target in zip(all_cases[:10], targets[:10])]
grdr.fit(case_queries, animate_tree=True)
# Render the tree to a file
render_tree(grdr.start_rules[0], use_dot_exporter=True, filename="species_rdr")
# Classify a case
cat = grdr.classify(all_cases[50])['species']
assert cat == targets[50]
When prompted to write a rule, I wrote the following inside the template function that the Ripple Down Rules created:
return case.milk == 1
then
return case.aquatic == 1
The rule tree generated from fitting all the dataset will look like this:
Relational Example
By relational, I mean that each rule conclusion is not a constant value, but is related to the case being classified, you can understand it better by the next example.
In this example, we will create a simple robot with parts and use Ripple Down Rules to find the contained objects inside another object, in this case, a robot. You see, the result of such a rule will vary depending on the robot and the parts it has.
from __future__ import annotations
import os.path
from dataclasses import dataclass, field
from typing_extensions import List, Optional
from ripple_down_rules.datastructures.dataclasses import CaseQuery
from ripple_down_rules.rdr import GeneralRDR
@dataclass(unsafe_hash=True)
class PhysicalObject:
"""
A physical object is an object that can be contained in a container.
"""
name: str
contained_objects: List[PhysicalObject] = field(default_factory=list, hash=False)
@dataclass(unsafe_hash=True)
class Part(PhysicalObject):
...
@dataclass(unsafe_hash=True)
class Robot(PhysicalObject):
parts: List[Part] = field(default_factory=list, hash=False)
part_a = Part(name="A")
part_b = Part(name="B")
part_c = Part(name="C")
robot = Robot("pr2", parts=[part_a])
part_a.contained_objects = [part_b]
part_b.contained_objects = [part_c]
case_query = CaseQuery(robot, "contained_objects", (PhysicalObject,), False)
load = True # Set to True if you want to load an existing model, False if you want to create a new one.
if load and os.path.exists('./part_containment_rdr'):
grdr = GeneralRDR.load('./', model_name='part_containment_rdr')
grdr.ask_always = False # Set to True if you want to always ask the expert for a target value.
else:
grdr = GeneralRDR(save_dir='./', model_name='part_containment_rdr')
grdr.fit_case(case_query)
print(grdr.classify(robot)['contained_objects'])
assert grdr.classify(robot)['contained_objects'] == {part_b}
When prompted to write a rule, I wrote the following inside the template function that the Ripple Down Rules created
for me, this function takes a case object as input:
contained_objects = []
for part in case.parts:
contained_objects.extend(part.contained_objects)
return contained_objects
And then when asked for conditions, I wrote the following inside the template function that the Ripple Down Rules created:
return len(case.parts) > 0
This means that the rule will only be applied if the robot has parts.
If you notice, the result only contains part B, while one could say that part C is also contained in the robot, but, the rule we wrote only returns the contained objects of the parts of the robot. To get part C, we would have to add another rule that says that the contained objects of my contained objects are also contained in me, you can try that yourself and see if it works!
To Cite:
@software{bassiouny2025rdr,
author = {Bassiouny, Abdelrhman},
title = {Ripple-Down-Rules},
url = {https://github.com/AbdelrhmanBassiouny/ripple_down_rules},
version = {0.5.4},
}
1 maintainer
Metadata
1 maintainer
Release files for ripple-down-rules 0.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| ripple_down_rules-0.7.1.tar.gz | 3.5 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| ripple_down_rules-0.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.6 MB
Release files / ripple_down_rules-0.7.1.tar.gz
| Download URL | ripple_down_rules-0.7.1.tar.gz |
|---|---|
| Size | 3.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ec9430a75b2d2200d7b6b01daa46544db3e0b2d897fc961beccc350f415a469
|
|
BLAKE2b-256 checksum How to use checksums |
5b90d503558e9c3b5a21c7ebcb6f8127e14d78dc5b98a4c686b89895abf31cb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 6, 2025.
Transparency logRelease files / ripple_down_rules-0.7.1-py3-none-any.whl
| Download URL | ripple_down_rules-0.7.1-py3-none-any.whl |
|---|---|
| Size | 120.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
69cac0260424fa54373a341d038b7234d989b2377e645c85c4bfd49ad7b3844c
|
|
BLAKE2b-256 checksum How to use checksums |
94eee70f6e718b6ef0e9268eab540020fd88dc0e3e238ba13c5c949dda6961cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 6, 2025.
Transparency log
