ripple-down-rules 0.0.0__py3-none-any.whl

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/datastructures/__init__.py

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

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/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)

ripple_down_rules/datastructures/enums.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from enum import auto, Enum
+
+from typing_extensions import List
+
+
+class Category(str, Enum):
+
+    @classmethod
+    def from_str(cls, value: str) -> Category:
+        return getattr(cls, value)
+
+    @classmethod
+    def from_strs(cls, values: List[str]) -> List[Category]:
+        return [cls.from_str(value) for value in values]
+
+    @property
+    def as_dict(self):
+        return {self.__class__.__name__.lower(): self.value}
+
+
+class Stop(Category):
+    """
+    A stop category is a special category that represents the stopping of the classification to prevent a wrong
+    conclusion from being made.
+    """
+    stop = "stop"
+
+
+class ExpressionParser(Enum):
+    """
+    Parsers for expressions to evaluate and encapsulate the expression into a callable function.
+    """
+    ASTVisitor: int = auto()
+    """
+    Generic python Abstract Syntax Tree that detects variables, attributes, binary/boolean expressions , ...etc.
+    """
+    SQLAlchemy: int = auto()
+    """
+    Specific for SQLAlchemy expressions on ORM Tables.
+    """
+
+
+class PromptFor(Enum):
+    """
+    The reason of the prompt. (e.g. get conditions, or conclusions).
+    """
+    Conditions: str = "conditions"
+    """
+    Prompt for rule conditions about a case.
+    """
+    Conclusion: str = "conclusion"
+    """
+    Prompt for rule conclusion about a case.
+    """
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class CategoricalValue(Enum):
+    """
+    A categorical value is a value that is a category.
+    """
+
+    def __eq__(self, other):
+        if isinstance(other, CategoricalValue):
+            return self.name == other.name
+        elif isinstance(other, str):
+            return self.name == other
+        return self.name == other
+
+    def __hash__(self):
+        return hash(self.name)
+
+    @classmethod
+    def to_list(cls):
+        return list(cls._value2member_map_.keys())
+
+    @classmethod
+    def from_str(cls, category: str):
+        return cls[category.lower()]
+
+    @classmethod
+    def from_strs(cls, categories: List[str]):
+        return [cls.from_str(c) for c in categories]
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return self.__str__()
+
+
+class RDRMode(Enum):
+    Propositional = auto()
+    """
+    Propositional mode, the mode where the rules are propositional.
+    """
+    Relational = auto()
+    """
+    Relational mode, the mode where the rules are relational.
+    """
+
+
+class MCRDRMode(Enum):
+    """
+    The modes of the MultiClassRDR.
+    """
+    StopOnly = auto()
+    """
+    StopOnly mode, stop wrong conclusion from being made and does not add a new rule to make the correct conclusion.
+    """
+    StopPlusRule = auto()
+    """
+    StopPlusRule mode, stop wrong conclusion from being made and adds a new rule with same conditions as stopping rule
+     to make the correct conclusion.
+    """
+    StopPlusRuleCombined = auto()
+    """
+    StopPlusRuleCombined mode, stop wrong conclusion from being made and adds a new rule with combined conditions of
+    stopping rule and the rule that should have fired.
+    """
+
+
+class RDREdge(Enum):
+    Refinement = "except if"
+    """
+    Refinement edge, the edge that represents the refinement of an incorrectly fired rule.
+    """
+    Alternative = "else if"
+    """
+    Alternative edge, the edge that represents the alternative to the rule that has not fired.
+    """
+    Next = "next"
+    """
+    Next edge, the edge that represents the next rule to be evaluated.
+    """
+
+
+class ValueType(Enum):
+    Unary = auto()
+    """
+    Unary value type (eg. null).
+    """
+    Binary = auto()
+    """
+    Binary value type (eg. True, False).
+    """
+    Discrete = auto()
+    """
+    Discrete value type (eg. 1, 2, 3).
+    """
+    Continuous = auto()
+    """
+    Continuous value type (eg. 1.0, 2.5, 3.4).
+    """
+    Nominal = auto()
+    """
+    Nominal value type (eg. red, blue, green), categories where the values have no natural order.
+    """
+    Ordinal = auto()
+    """
+    Ordinal value type (eg. low, medium, high), categories where the values have a natural order.
+    """
+    Iterable = auto()
+    """
+    Iterable value type (eg. [1, 2, 3]).
+    """