ripple-down-rules 0.0.0__tar.gz

ripple_down_rules-0.0.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: ripple_down_rules
+Version: 0.0.0
+Summary: Implements the various versions of Ripple Down Rules (RDR) for knowledge representation and reasoning.
+Author-email: Abdelrhman Bassiouny <abassiou@uni-bremen.de>
+Project-URL: Homepage, https://github.com/AbdelrhmanBassiouny/ripple_down_rules
+Keywords: robotics,knowledge,reasoning,representation
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: neem_pycram_interface==1.0.167
+
+# 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
+```
+
+## 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:
+
+```Python
+from ripple_down_rules.rdr import SingleClassRDR
+from ripple_down_rules.datasets import load_zoo_dataset
+from ripple_down_rules.utils import render_tree
+
+all_cases, targets = load_zoo_dataset()
+
+scrdr = SingleClassRDR()
+
+# Fit the SCRDR to the data
+scrdr.fit(all_cases, targets,
+          animate_tree=True, n_iter=10)
+
+# Render the tree to a file
+render_tree(scrdr.start_rule, use_dot_exporter=True, filename="scrdr")
+
+cat = scrdr.fit_case(all_cases[50], targets[50])
+assert cat == targets[50]
+```

ripple_down_rules-0.0.0/README.md

@@ -0,0 +1,42 @@
+# 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
+```
+
+## 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:
+
+```Python
+from ripple_down_rules.rdr import SingleClassRDR
+from ripple_down_rules.datasets import load_zoo_dataset
+from ripple_down_rules.utils import render_tree
+
+all_cases, targets = load_zoo_dataset()
+
+scrdr = SingleClassRDR()
+
+# Fit the SCRDR to the data
+scrdr.fit(all_cases, targets,
+          animate_tree=True, n_iter=10)
+
+# Render the tree to a file
+render_tree(scrdr.start_rule, use_dot_exporter=True, filename="scrdr")
+
+cat = scrdr.fit_case(all_cases[50], targets[50])
+assert cat == targets[50]
+```

ripple_down_rules-0.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+# pyproject.toml
+
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ripple_down_rules"
+version = "0.0.0"
+description = "Implements the various versions of Ripple Down Rules (RDR) for knowledge representation and reasoning."
+readme = "README.md"
+authors = [{ name = "Abdelrhman Bassiouny", email = "abassiou@uni-bremen.de" }]
+license = { file = "LICENSE" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+keywords = ["robotics", "knowledge", "reasoning", "representation"]
+dependencies = ["neem_pycram_interface==1.0.167",
+]
+requires-python = ">=3.8"
+
+[project.urls]
+Homepage = "https://github.com/AbdelrhmanBassiouny/ripple_down_rules"

ripple_down_rules-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ripple_down_rules-0.0.0/src/ripple_down_rules/datasets.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import os
+import pickle
+
+import sqlalchemy
+from sqlalchemy import ForeignKey
+from sqlalchemy.orm import MappedAsDataclass, Mapped, mapped_column, relationship
+from typing_extensions import Tuple, List, Set
+from ucimlrepo import fetch_ucirepo
+
+from .datastructures import Case, create_rows_from_dataframe, Category, Column
+
+
+def load_cached_dataset(cache_file):
+    """Loads the dataset from cache if it exists."""
+    dataset = {}
+    for key in ["features", "targets", "ids"]:
+        part_file = cache_file.replace(".pkl", f"_{key}.pkl")
+        if not os.path.exists(part_file):
+            return None
+        with open(part_file, "rb") as f:
+            dataset[key] = pickle.load(f)
+    return dataset
+
+
+def save_dataset_to_cache(dataset, cache_file):
+    """Saves only essential parts of the dataset to cache."""
+    dataset_to_cache = {
+        "features": dataset.data.features,
+        "targets": dataset.data.targets,
+        "ids": dataset.data.ids,
+    }
+
+    for key, value in dataset_to_cache.items():
+        with open(cache_file.replace(".pkl", f"_{key}.pkl"), "wb") as f:
+            pickle.dump(dataset_to_cache[key], f)
+    print("Dataset cached successfully.")
+
+
+def get_dataset(dataset_id, cache_file):
+    """Fetches dataset from cache or downloads it if not available."""
+    dataset = load_cached_dataset(cache_file)
+    if dataset is None:
+        print("Downloading dataset...")
+        dataset = fetch_ucirepo(id=dataset_id)
+
+        # Check if dataset is valid before caching
+        if dataset is None or not hasattr(dataset, "data"):
+            print("Error: Failed to fetch dataset.")
+            return None
+
+        save_dataset_to_cache(dataset, cache_file)
+
+    return dataset
+
+
+def load_zoo_dataset(cache_file: str) -> Tuple[List[Case], List[Species]]:
+    """
+    Load the zoo dataset.
+
+    :param cache_file: the cache file.
+    :return: all cases and targets.
+    """
+    # fetch dataset
+    zoo = get_dataset(111, cache_file)
+
+    # data (as pandas dataframes)
+    X = zoo['features']
+    y = zoo['targets']
+    # get ids as list of strings
+    ids = zoo['ids'].values.flatten()
+    all_cases = create_rows_from_dataframe(X, "Animal")
+
+    category_names = ["mammal", "bird", "reptile", "fish", "amphibian", "insect", "molusc"]
+    category_id_to_name = {i + 1: name for i, name in enumerate(category_names)}
+    targets = [getattr(SpeciesCol, category_id_to_name[i]) for i in y.values.flatten()]
+    return all_cases, targets
+
+
+class Species(Category):
+    mammal = "mammal"
+    bird = "bird"
+    reptile = "reptile"
+    fish = "fish"
+    amphibian = "amphibian"
+    insect = "insect"
+    molusc = "molusc"
+
+
+class Habitat(Category):
+    """
+    A habitat category is a category that represents the habitat of an animal.
+    """
+    land = "land"
+    water = "water"
+    air = "air"
+
+
+SpeciesCol = Column.create_from_enum(Species, mutually_exclusive=True)
+HabitatCol = Column.create_from_enum(Habitat, mutually_exclusive=False)
+
+
+class Base(sqlalchemy.orm.DeclarativeBase):
+    pass
+
+
+class HabitatTable(MappedAsDataclass, Base):
+    __tablename__ = "Habitat"
+
+    id: Mapped[int] = mapped_column(init=False, primary_key=True, autoincrement=True)
+    habitat: Mapped[Habitat]
+    animal_id = mapped_column(ForeignKey("Animal.id"), init=False)
+
+    def __hash__(self):
+        return hash(self.habitat)
+
+    def __str__(self):
+        return self.habitat.value
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class Animal(MappedAsDataclass, Base):
+    __tablename__ = "Animal"
+
+    id: Mapped[int] = mapped_column(init=False, primary_key=True, autoincrement=True)
+    name: Mapped[str]
+    hair: Mapped[bool]
+    feathers: Mapped[bool]
+    eggs: Mapped[bool]
+    milk: Mapped[bool]
+    airborne: Mapped[bool]
+    aquatic: Mapped[bool]
+    predator: Mapped[bool]
+    toothed: Mapped[bool]
+    backbone: Mapped[bool]
+    breathes: Mapped[bool]
+    venomous: Mapped[bool]
+    fins: Mapped[bool]
+    legs: Mapped[int]
+    tail: Mapped[bool]
+    domestic: Mapped[bool]
+    catsize: Mapped[bool]
+    species: Mapped[Species] = mapped_column(nullable=True)
+
+    habitats: Mapped[Set[HabitatTable]] = relationship(default_factory=set)

ripple_down_rules-0.0.0/src/ripple_down_rules/datastructures/__init__.py

@@ -0,0 +1,4 @@
+from .enums import *
+from .dataclasses import *
+from .callable_expression import *
+from .table import *

ripple_down_rules-0.0.0/src/ripple_down_rules/datastructures/callable_expression.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import ast
+import logging
+from _ast import AST
+
+from sqlalchemy.orm import Session
+from typing_extensions import Type, Optional, Any, List, Union, Tuple, Dict, Set
+
+from .table import create_row, Row
+from ..utils import SubclassJSONSerializer, get_full_class_name
+
+
+class VariableVisitor(ast.NodeVisitor):
+    """
+    A visitor to extract all variables and comparisons from a python expression represented as an AST tree.
+    """
+    compares: List[Tuple[Union[ast.Name, ast.Call], ast.cmpop, Union[ast.Name, ast.Call]]]
+    variables: Set[str]
+    all: List[ast.BoolOp]
+
+    def __init__(self):
+        self.variables = set()
+        self.attributes: Dict[ast.Name, ast.Attribute] = {}
+        self.compares = list()
+        self.binary_ops = list()
+        self.all = list()
+
+    def visit_Attribute(self, node):
+        self.all.append(node)
+        self.attributes[node.value] = node
+        self.generic_visit(node)
+
+    def visit_BinOp(self, node):
+        self.binary_ops.append(node)
+        self.all.append(node)
+        self.generic_visit(node)
+
+    def visit_BoolOp(self, node):
+        self.all.append(node)
+        self.generic_visit(node)
+
+    def visit_Compare(self, node):
+        self.all.append(node)
+        self.compares.append([node.left, node.ops[0], node.comparators[0]])
+        self.generic_visit(node)
+
+    def visit_Name(self, node):
+        if f"__{node.id}__" not in dir(__builtins__) and node not in self.attributes:
+            self.variables.add(node.id)
+        self.generic_visit(node)
+
+
+class CallableExpression(SubclassJSONSerializer):
+    """
+    A callable that is constructed from a string statement written by an expert.
+    """
+    conclusion_type: Type
+    """
+    The type of the output of the callable, used for assertion.
+    """
+    expression_tree: AST
+    """
+    The AST tree parsed from the user input.
+    """
+    user_input: str
+    """
+    The input given by the expert.
+    """
+    session: Optional[Session]
+    """
+    The sqlalchemy orm session.
+    """
+    visitor: VariableVisitor
+    """
+    A visitor to extract all variables and comparisons from a python expression represented as an AST tree.
+    """
+    code: Any
+    """
+    The code that was compiled from the expression tree
+    """
+    compares_column_offset: List[int]
+    """
+    The start and end indices of each comparison in the string of user input.
+    """
+
+    def __init__(self, user_input: str, conclusion_type: Optional[Type] = None, expression_tree: Optional[AST] = None,
+                 session: Optional[Session] = None):
+        """
+        Create a callable expression.
+
+        :param user_input: The input given by the expert.
+        :param conclusion_type: The type of the output of the callable.
+        :param expression_tree: The AST tree parsed from the user input.
+        :param session: The sqlalchemy orm session.
+        """
+        self.session = session
+        self.user_input: str = user_input
+        self.parsed_user_input = self.parse_user_input(user_input, session)
+        self.conclusion_type = conclusion_type
+        self.update_expression(self.parsed_user_input, expression_tree)
+
+    @staticmethod
+    def parse_user_input(user_input: str, session: Optional[Session] = None) -> str:
+        if ',' in user_input:
+            user_input = user_input.split(',')
+            user_input = [f"({u.strip()})" for u in user_input]
+            user_input = ' & '.join(user_input) if session else ' and '.join(user_input)
+        elif session:
+            user_input = user_input.replace(" and ", " & ")
+            user_input = user_input.replace(" or ", " | ")
+        return user_input
+
+    def update_expression(self, user_input: str, expression_tree: Optional[AST] = None):
+        if not expression_tree:
+            expression_tree = parse_string_to_expression(user_input)
+        self.expression_tree: AST = expression_tree
+        self.visitor = VariableVisitor()
+        self.visitor.visit(expression_tree)
+        variables_str = self.visitor.variables
+        attributes_str = get_attributes_str(self.visitor)
+        for v in variables_str | attributes_str:
+            if not v.startswith("case."):
+                self.parsed_user_input = self.parsed_user_input.replace(v, f"case.{v}")
+        self.expression_tree = parse_string_to_expression(self.parsed_user_input)
+        self.compares_column_offset = [(c[0].col_offset, c[2].end_col_offset) for c in self.visitor.compares]
+        self.code = compile_expression_to_code(self.expression_tree)
+
+    def __call__(self, case: Any, **kwargs) -> Any:
+        try:
+            if not isinstance(case, Row):
+                case = create_row(case, max_recursion_idx=3)
+            output = eval(self.code)
+            if self.conclusion_type:
+                assert isinstance(output, self.conclusion_type), (f"Expected output type {self.conclusion_type},"
+                                                                  f" got {type(output)}")
+            return output
+        except Exception as e:
+            raise ValueError(f"Error during evaluation: {e}")
+
+    def combine_with(self, other: 'CallableExpression') -> 'CallableExpression':
+        """
+        Combine this callable expression with another callable expression using the 'and' operator.
+        """
+        new_user_input = f"({self.user_input}) and ({other.user_input})"
+        return CallableExpression(new_user_input, conclusion_type=self.conclusion_type, session=self.session)
+
+    def __str__(self):
+        """
+        Return the user string where each compare is written in a line using compare column offset start and end.
+        """
+        user_input = self.parsed_user_input
+        binary_ops = sorted(self.visitor.binary_ops, key=lambda x: x.end_col_offset)
+        binary_ops_indices = [b.end_col_offset for b in binary_ops]
+        all_binary_ops = []
+        prev_e = 0
+        for i, e in enumerate(binary_ops_indices):
+            if i == 0:
+                all_binary_ops.append(user_input[:e])
+            else:
+                all_binary_ops.append(user_input[prev_e:e])
+            prev_e = e
+        return "\n".join(all_binary_ops) if len(all_binary_ops) > 0 else user_input
+
+    def to_json(self) -> Dict[str, Any]:
+        return {**SubclassJSONSerializer.to_json(self),
+                "user_input": self.user_input, "conclusion_type": get_full_class_name(self.conclusion_type)}
+
+    @classmethod
+    def _from_json(cls, data: Dict[str, Any]) -> CallableExpression:
+        return cls(user_input=data["user_input"], conclusion_type=data["conclusion_type"])
+
+
+def compile_expression_to_code(expression_tree: AST) -> Any:
+    """
+    Compile an expression tree that was parsed from string into code that can be executed using 'eval(code)'
+
+    :param expression_tree: The parsed expression tree.
+    :return: The code that was compiled from the expression tree.
+    """
+    return compile(expression_tree, filename="<string>", mode="eval")
+
+
+def assert_context_contains_needed_information(case: Any, context: Dict[str, Any],
+                                               visitor: VariableVisitor) -> Tuple[Set[str], Set[str]]:
+    """
+    Asserts that the variables mentioned in the expression visited by visitor are all in the given context.
+
+    :param case: The case to check the context for.
+    :param context: The context to check.
+    :param visitor: The visitor that visited the expression.
+    :return: The found variables and attributes.
+    """
+    found_variables = set()
+    for key in visitor.variables:
+        if key not in context:
+            raise ValueError(f"Variable {key} not found in the case {case}")
+        found_variables.add(key)
+
+    found_attributes = get_attributes_str(visitor)
+    for attr in found_attributes:
+        if attr not in context:
+            raise ValueError(f"Attribute {attr} not found in the case {case}")
+    return found_variables, found_attributes
+
+
+def get_attributes_str(visitor: VariableVisitor) -> Set[str]:
+    """
+    Get the string representation of the attributes in the given visitor.
+
+    :param visitor: The visitor that visited the expression.
+    :return: The string representation of the attributes.
+    """
+    found_attributes = set()
+    for key, ast_attr in visitor.attributes.items():
+        str_attr = ""
+        while isinstance(key, ast.Attribute):
+            if len(str_attr) > 0:
+                str_attr = f"{key.attr}.{str_attr}"
+            else:
+                str_attr = key.attr
+            key = key.value
+        str_attr = f"{key.id}.{str_attr}" if len(str_attr) > 0 else f"{key.id}.{ast_attr.attr}"
+        found_attributes.add(str_attr)
+    return found_attributes
+
+
+def parse_string_to_expression(expression_str: str) -> AST:
+    """
+    Parse a string statement into an AST expression.
+
+    :param expression_str: The string which will be parsed.
+    :return: The parsed expression.
+    """
+    tree = ast.parse(expression_str, mode='eval')
+    logging.debug(f"AST parsed successfully: {ast.dump(tree)}")
+    return tree

ripple_down_rules-0.0.0/src/ripple_down_rules/datastructures/dataclasses.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from copy import copy, deepcopy
+from dataclasses import dataclass
+
+from sqlalchemy.orm import DeclarativeBase as SQLTable
+from typing_extensions import Any, Optional, Type, Union
+
+from .table import create_row, Case
+from ..utils import get_attribute_name, copy_orm_instance_with_relationships, copy_case
+
+
+@dataclass
+class CaseQuery:
+    """
+    This is a dataclass that represents an attribute of an object and its target value. If attribute name is
+    not provided, it will be inferred from the attribute itself or from the attribute type or from the target value,
+    depending on what is provided.
+    """
+    case: Any
+    """
+    The case that the attribute belongs to.
+    """
+    attribute: Optional[Any] = None
+    """
+    The attribute itself.
+    """
+    targets: Optional[Any] = None
+    """
+    The target value of the attribute.
+    """
+    attribute_name: Optional[str] = None
+    """
+    The name of the attribute.
+    """
+    attribute_type: Optional[Type] = None
+    """
+    The type of the attribute.
+    """
+    relational_representation: Optional[str] = None
+    """
+    The representation of the target value in relational form.
+    """
+
+    def __init__(self, case: Any, attribute: Optional[Any] = None, target: Optional[Any] = None,
+                 attribute_name: Optional[str] = None, attribute_type: Optional[Type] = None,
+                 relational_representation: Optional[str] = None):
+
+        if attribute_name is None:
+            attribute_name = get_attribute_name(case, attribute, attribute_type, target)
+        self.attribute_name = attribute_name
+
+        if not isinstance(case, (Case, SQLTable)):
+            case = create_row(case, max_recursion_idx=3)
+        self.case = case
+
+        self.attribute = getattr(self.case, self.attribute_name) if self.attribute_name else None
+        self.attribute_type = type(self.attribute) if self.attribute else None
+        self.target = target
+        self.relational_representation = relational_representation
+
+    @property
+    def name(self):
+        return self.attribute_name if self.attribute_name else self.__class__.__name__
+
+    def __str__(self):
+        if self.relational_representation:
+            return f"{self.name} |= {self.relational_representation}"
+        else:
+            return f"{self.target}"
+
+    def __repr__(self):
+        return self.__str__()
+
+    def __copy__(self):
+        return CaseQuery(copy_case(self.case), attribute_name=self.attribute_name, target=self.target)