ripple-down-rules 0.5.1__tar.gz → 0.5.3__tar.gz

ripple_down_rules-0.5.3/.github/workflows/build_and_deploy_doc.yml

@@ -0,0 +1,64 @@
+name: deploy-book
+
+# Run this when the master or main branch changes
+on:
+  push:
+    branches:
+    - main
+    # If your git repository has the Jupyter Book within some-subfolder next to
+    # unrelated files, you can make this run only if a file within that specific
+    # folder has been modified.
+    #
+    # paths:
+    # - some-subfolder/**
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+
+    # Install dependencies
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+        cache: pip # Implicitly uses requirements.txt for cache key
+    
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt install graphviz graphviz-dev
+        pip install -U pip && pip install -r requirements.txt && pip install . && pip install -r doc/requirements.txt
+
+    # (optional) Cache your executed notebooks between runs
+    # if you have config:
+    # execute:
+    #   execute_notebooks: cache
+    - name: cache executed notebooks
+      uses: actions/cache@v4
+      with:
+        path: doc/_build/.jupyter_cache
+        key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build doc
+
+    # Upload the book's HTML as an artifact
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: "doc/_build/html"
+
+    # Deploy the book's HTML to GitHub Pages
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

{ripple_down_rules-0.5.1 → ripple_down_rules-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.5.1
+Version: 0.5.3
 Summary: Implements the various versions of Ripple Down Rules (RDR) for knowledge representation and reasoning.
 Author-email: Abdelrhman Bassiouny <abassiou@uni-bremen.de>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -725,36 +725,161 @@ For GUI support, also install:
 sudo apt-get install libxcb-cursor-dev
 ```
 
-```bash
-
 ## Example Usage
 
-Fit the SCRDR to the data, then classify one of the data cases to check if its correct,
-and render the tree to a file:
+### 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](https://archive.ics.uci.edu/ml/datasets/zoo) 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:
+```bash
+pip install ucimlrepo
 ```
 
 ```python
+from __future__ import annotations
 from ripple_down_rules.datastructures.dataclasses import CaseQuery
-from ripple_down_rules.rdr import SingleClassRDR
-from datasets import load_zoo_dataset
+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
 
-all_cases, targets = load_zoo_dataset()
+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)
 
-scrdr = SingleClassRDR()
+# fetch dataset
+zoo = fetch_ucirepo(id=111)
 
-# Fit the SCRDR to the data
+# 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])]
-scrdr.fit(case_queries, animate_tree=True)
+grdr.fit(case_queries, animate_tree=True)
 
 # Render the tree to a file
-render_tree(scrdr.start_rule, use_dot_exporter=True, filename="scrdr")
+render_tree(grdr.start_rules[0], use_dot_exporter=True, filename="species_rdr")
 
-cat = scrdr.classify(all_cases[50])
+# Classify a case
+cat = grdr.classify(all_cases[50])['species']
 assert cat == targets[50]
 ```
 
+### 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.
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
 
 ```bib
@@ -762,6 +887,6 @@ assert cat == targets[50]
 author = {Bassiouny, Abdelrhman},
 title = {Ripple-Down-Rules},
 url = {https://github.com/AbdelrhmanBassiouny/ripple_down_rules},
-version = {0.4.1},
+version = {0.5.2},
 }
 ```

ripple_down_rules-0.5.3/README.md

@@ -0,0 +1,188 @@
+# 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"](https://doi.org/10.1201/9781003126157) by Paul Compton, Byeong Ho Kang.
+
+## Installation
+
+```bash
+sudo apt-get install graphviz graphviz-dev
+pip install ripple_down_rules
+```
+For GUI support, also install:
+
+```bash
+sudo apt-get install libxcb-cursor-dev
+```
+
+## 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](https://archive.ics.uci.edu/ml/datasets/zoo) 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:
+```bash
+pip install ucimlrepo
+```
+
+```python
+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]
+```
+
+### 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.
+
+```python
+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:
+
+```python
+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:
+
+```python
+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:
+
+```bib
+@software{bassiouny2025rdr,
+author = {Bassiouny, Abdelrhman},
+title = {Ripple-Down-Rules},
+url = {https://github.com/AbdelrhmanBassiouny/ripple_down_rules},
+version = {0.5.2},
+}
+```

ripple_down_rules-0.5.3/doc/_config.yml

@@ -0,0 +1,54 @@
+# Book settings
+# Learn more at https://jupyterbook.org/customize/config.html
+
+title: Ripple Down Rules
+author: Abdelrhman Bassiouny
+# logo: logo.png
+
+# Force re-execution of notebooks on each build.
+# See https://jupyterbook.org/content/execute.html
+execute:
+  execute_notebooks: force
+
+# Define the name of the latex output file for PDF builds
+latex:
+  latex_documents:
+    targetname: book.tex
+
+# Add a bibtex file so that we can create citations
+bibtex_bibfiles:
+  - references.bib
+
+sphinx:
+  extra_extensions:
+    - myst_nb
+    - sphinxcontrib.bibtex  # Add the BibTeX extension
+    - autoapi.extension  # Add the AutoAPI extension
+    - 'sphinx.ext.autodoc'
+    - sphinxcontrib.plantuml
+  config:
+    bibtex_bibfiles:
+      - references.bib
+    # AutoAPI configuration
+    autoapi_type: python
+    autoapi_dirs:
+      - ../src
+    autoapi_options:
+      - members
+      - undoc-members
+      - show-inheritance
+      - show-module-summary
+    autoapi_add_toctree_entry: True
+
+
+# Information about where the book exists on the web
+repository:
+  url: https://github.com/AbdelrhmanBassiouny/ripple_down_rules  # Online location of your book
+  path_to_book: doc  # Optional path to your book, relative to the repository root
+  branch: main  # Which branch of the repository should be used when creating links (optional)
+
+# Add GitHub buttons to your book
+# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
+html:
+  use_issues_button: true
+  use_repository_button: true

ripple_down_rules-0.5.3/doc/_toc.yml

@@ -0,0 +1,8 @@
+# Table of contents
+# Learn more at https://jupyterbook.org/customize/toc.html
+
+format: jb-book
+root: intro
+chapters:
+- file: bibliography
+- file: autoapi/index

ripple_down_rules-0.5.3/doc/bibliography.md

@@ -0,0 +1,4 @@
+# Bibliography
+
+```{bibliography}
+```