ripple-down-rules 0.5.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

ripple_down_rules/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 import logging
 logger = logging.Logger("rdr")

ripple_down_rules/datastructures/callable_expression.py

@@ -92,7 +92,8 @@ class CallableExpression(SubclassJSONSerializer):
     """
     A callable that is constructed from a string statement written by an expert.
     """
-    encapsulating_function: str = "def _get_value(case):"
+    encapsulating_function_name: str = "_get_value"
+    encapsulating_function: str = f"def {encapsulating_function_name}(case):"
 
     def __init__(self, user_input: Optional[str] = None,
                  conclusion_type: Optional[Tuple[Type]] = None,

ripple_down_rules/experts.py

@@ -4,6 +4,7 @@ import ast
 import json
 import logging
 import os
+import uuid
 from abc import ABC, abstractmethod
 
 from typing_extensions import Optional, TYPE_CHECKING, List
@@ -145,7 +146,8 @@ class Expert(ABC):
                 else:
                     imports = ''
                 if func_source is not None:
-                    func_source = encapsulate_user_input(func_source, CallableExpression.encapsulating_function)
+                    uid = uuid.uuid4().hex
+                    func_source = encapsulate_user_input(func_source, CallableExpression.encapsulating_function + f'_{uid}')
                 else:
                     func_source = 'pass  # No user input provided for this case.\n'
                 f.write(imports + func_source + '\n' + '\n\n\n\'===New Answer===\'\n\n\n')
@@ -185,14 +187,17 @@ class Expert(ABC):
         """
         file_path = path + '.py'
         with open(file_path, "r") as f:
-            all_answers = f.read().split('\n\n\n\'===New Answer===\'\n\n\n')
-        for answer in all_answers:
+            all_answers = f.read().split('\n\n\n\'===New Answer===\'\n\n\n')[:-1]
+        all_function_sources = list(extract_function_source(file_path, []).values())
+        all_function_sources_names = list(extract_function_source(file_path, []).keys())
+        for i, answer in enumerate(all_answers):
             answer = answer.strip('\n').strip()
             if 'def ' not in answer and 'pass' in answer:
                 self.all_expert_answers.append(({}, None))
             scope = extract_imports(tree=ast.parse(answer))
-            func_source = list(extract_function_source(file_path, []).values())[0]
-            self.all_expert_answers.append((scope, func_source))
+            function_source = all_function_sources[i].replace(all_function_sources_names[i],
+                                                              CallableExpression.encapsulating_function_name)
+            self.all_expert_answers.append((scope, function_source))
 
 
 class Human(Expert):
@@ -212,7 +217,7 @@ class Human(Expert):
     def ask_for_conditions(self, case_query: CaseQuery,
                            last_evaluated_rule: Optional[Rule] = None) \
             -> CallableExpression:
-        if not self.use_loaded_answers and self.user_prompt.viewer is None:
+        if (not self.use_loaded_answers or len(self.all_expert_answers) == 0) and self.user_prompt.viewer is None:
             show_current_and_corner_cases(case_query.case, {case_query.attribute_name: case_query.target_value},
                                           last_evaluated_rule=last_evaluated_rule)
         return self._get_conditions(case_query)

ripple_down_rules/rdr.py

@@ -191,8 +191,8 @@ class RippleDownRules(SubclassJSONSerializer, ABC):
                 match = is_matching(self.classify, case_query, pred_cat)
                 if not match:
                     print(f"Predicted: {pred_cat} but expected: {target}")
-                if animate_tree and self.start_rule.size > num_rules:
-                    num_rules = self.start_rule.size
+                if animate_tree and len(self.start_rule.descendants) > num_rules:
+                    num_rules = len(self.start_rule.descendants)
                     self.update_figures()
             i += 1
             all_predictions = [1 if is_matching(self.classify, case_query) else 0 for case_query in case_queries
@@ -241,6 +241,8 @@ class RippleDownRules(SubclassJSONSerializer, ABC):
         self.case_type = case_query.case_type if self.case_type is None else self.case_type
         self.case_name = case_query.case_name if self.case_name is None else self.case_name
 
+        expert = expert or Human(answers_save_path=self.save_dir + '/expert_answers' if self.save_dir else None)
+
         if case_query.target is None:
             case_query_cp = copy(case_query)
             conclusions = self.classify(case_query_cp.case, modify_case=True)

ripple_down_rules/utils.py

@@ -186,7 +186,7 @@ def extract_function_source(file_path: str,
                 func_lines = func_lines[1:]
             line_numbers.append((node.lineno, node.end_lineno))
             functions_source[node.name] = dedent("\n".join(func_lines)) if join_lines else func_lines
-            if len(functions_source) >= len(function_names):
+            if (len(functions_source) >= len(function_names)) and (not len(function_names) == 0):
                 break
     if len(functions_source) < len(function_names):
         raise ValueError(f"Could not find all functions in {file_path}: {function_names} not found,"

{ripple_down_rules-0.5.1.dist-info → ripple_down_rules-0.5.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.5.1
+Version: 0.5.2
 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.1.dist-info → ripple_down_rules-0.5.2.dist-info}/RECORD

@@ -1,14 +1,14 @@
-ripple_down_rules/__init__.py,sha256=eaqN_CQPn7hOrKpan5PYhltW0v7z_ySJ5iHY-x4gzZQ,99
-ripple_down_rules/experts.py,sha256=9Vc3vx0uhDPy3YlNjwKuWJLl_A-kubRPUU6bMvQhaAg,13237
+ripple_down_rules/__init__.py,sha256=K8GayszN_Ydn9s_OsfTRq83trUr2_x64cQwQX9gwF-E,99
+ripple_down_rules/experts.py,sha256=tjCq_T_d2qc_DhyBlxfqoT3oHk6-HmKFZFqGZAdXUb0,13660
 ripple_down_rules/failures.py,sha256=E6ajDUsw3Blom8eVLbA7d_Qnov2conhtZ0UmpQ9ZtSE,302
 ripple_down_rules/helpers.py,sha256=TvTJU0BA3dPcAyzvZFvAu7jZqsp8Lu0HAAwvuizlGjg,2018
-ripple_down_rules/rdr.py,sha256=E1OiiZClQyAfGjL64ID-MWYFO4-h8iUAX-Vm9qrOoeQ,48727
+ripple_down_rules/rdr.py,sha256=FJYuRXgpUYSSK1pYrp2yeXb_ZZ2xjPED31tzxofokL4,48865
 ripple_down_rules/rdr_decorators.py,sha256=pYCKLgMKgQ6x_252WQtF2t4ZNjWPBxnaWtJ6TpGdcc0,7820
 ripple_down_rules/rules.py,sha256=TPNVMqW9T-_46BS4WemrspLg5uG8kP6tsPvWWBAzJxg,17515
 ripple_down_rules/start-code-server.sh,sha256=otClk7VmDgBOX2TS_cjws6K0UwvgAUJhoA0ugkPCLqQ,949
-ripple_down_rules/utils.py,sha256=uS38KcFceRMzT_470DCL1M0LzETdP5RLwE7cCmfo7eI,51086
+ripple_down_rules/utils.py,sha256=cv40XBj-tp11aRYcAPhPtkrYatMvAKk_1d5P7PB1-tw,51123
 ripple_down_rules/datastructures/__init__.py,sha256=V2aNgf5C96Y5-IGghra3n9uiefpoIm_QdT7cc_C8cxQ,111
-ripple_down_rules/datastructures/callable_expression.py,sha256=3EucsD3jWzekhjyzL2y0dyUsucd-aqC9glmgPL0Ubb4,12425
+ripple_down_rules/datastructures/callable_expression.py,sha256=D2KD1RdShzxYZPAERgywZ5ZPE4ar8WmMtXINqvYo_Tc,12497
 ripple_down_rules/datastructures/case.py,sha256=r8kjL9xP_wk84ThXusspgPMrAoed2bGQmKi54fzhmH8,15258
 ripple_down_rules/datastructures/dataclasses.py,sha256=PuD-7zWqWT2p4FnGvnihHvZlZKg9A1ctnFgVYf2cs-8,8554
 ripple_down_rules/datastructures/enums.py,sha256=ce7tqS0otfSTNAOwsnXlhsvIn4iW_Y_N3TNebF3YoZs,5700
@@ -18,8 +18,8 @@ ripple_down_rules/user_interface/ipython_custom_shell.py,sha256=24MIFwqnAhC6ofOb
 ripple_down_rules/user_interface/object_diagram.py,sha256=tsB6iuLNEbHxp5lR2WjyejjWbnAX_nHF9xS8jNPOQVk,4548
 ripple_down_rules/user_interface/prompt.py,sha256=AkkltdDIaioN43lkRKDPKSjJcmdSSGZDMYz7AL7X9lE,8082
 ripple_down_rules/user_interface/template_file_creator.py,sha256=ycCbddy_BJP8d0Q2Sj21UzamhGtqGZuK_e73VTJqznY,13766
-ripple_down_rules-0.5.1.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
-ripple_down_rules-0.5.1.dist-info/METADATA,sha256=BWKLHm71B9jCeEi-Ro14s4hBNEcZqKvLQJNe2pij22w,43313
-ripple_down_rules-0.5.1.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-ripple_down_rules-0.5.1.dist-info/top_level.txt,sha256=VeoLhEhyK46M1OHwoPbCQLI1EifLjChqGzhQ6WEUqeM,18
-ripple_down_rules-0.5.1.dist-info/RECORD,,
+ripple_down_rules-0.5.2.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+ripple_down_rules-0.5.2.dist-info/METADATA,sha256=O3NmfxnYkTpT9dNAkJ3nOEsG-oau7PMotx37fFSwnqQ,47688
+ripple_down_rules-0.5.2.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+ripple_down_rules-0.5.2.dist-info/top_level.txt,sha256=VeoLhEhyK46M1OHwoPbCQLI1EifLjChqGzhQ6WEUqeM,18
+ripple_down_rules-0.5.2.dist-info/RECORD,,