Add Khiops dictionary rule API support

- add a `Rule` class
- add `{Variable,VariableBlock}.{get,set}_rule` methods
- add an `upper_scope` function which applies the upper-scope operand
  `.` to `Variable` and `Rule` instances and to upper-scoped instances
  of these.

Author: popescu-v

doc/samples/samples.rst

@@ -655,17 +655,23 @@ Samples
     fold_index_variable.name = "FoldIndex"
     fold_index_variable.type = "Numerical"
     fold_index_variable.used = False
-    fold_index_variable.rule = "Ceil(Product(" + str(fold_number) + ",  Random()))"
     dictionary.add_variable(fold_index_variable)
 
+    # Create fold indexing rule and set it on `fold_index_variable`
+    dictionary.get_variable(fold_index_variable.name).set_rule(
+        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
+    )
+
     # Add variables that indicate if the instance is in the train dataset:
     for fold_index in range(1, fold_number + 1):
         is_in_train_dataset_variable = kh.Variable()
         is_in_train_dataset_variable.name = "IsInTrainDataset" + str(fold_index)
         is_in_train_dataset_variable.type = "Numerical"
         is_in_train_dataset_variable.used = False
-        is_in_train_dataset_variable.rule = "NEQ(FoldIndex, " + str(fold_index) + ")"
         dictionary.add_variable(is_in_train_dataset_variable)
+        dictionary.get_variable(is_in_train_dataset_variable.name).set_rule(
+            kh.Rule("NEQ", fold_index_variable, fold_index),
+        )
 
     # Print dictionary with fold variables
     print("Dictionary file with fold variables")

khiops/core/dictionary.py

@@ -13,6 +13,7 @@
 
 """
 import io
+import math
 import os
 import re
 import warnings
@@ -989,8 +990,10 @@ class Variable:
     rule : str
         Derivation rule or external table reference. Set to "" if there is no
         rule associated to this variable. Examples:
+
             - standard rule: "Sum(Var1, Var2)"
             - reference rule: "[TableName]"
+
     variable_block : `VariableBlock`
         Block to which the variable belongs. Not set if the variable does not belong to
         a block.
@@ -1182,6 +1185,27 @@ def full_type(self):
             full_type += f"({self.structure_type})"
         return full_type
 
+    def get_rule(self):
+        """Gets `Rule` from a specified variable"""
+        return Rule(name=self.rule)
+
+    def set_rule(self, rule):
+        """Sets a rule on a specified variable in the dictionary
+
+        Parameters
+        ----------
+        rule : `Rule`
+            The rule to be set on the variable.
+
+        Raises
+        ------
+        `TypeError`
+            If ``rule`` is not of type `Rule`
+        """
+        if not isinstance(rule, Rule):
+            raise TypeError(type_error_message("rule", rule, Rule))
+        self.rule = repr(rule)
+
     def write(self, writer):
         """Writes the domain to a file writer in ``.kdic`` format
 
@@ -1357,6 +1381,27 @@ def get_value(self, key):
         """
         return self.meta_data.get_value(key)
 
+    def get_rule(self):
+        """Gets `Rule` from a specified variable block"""
+        return Rule(name=self.rule)
+
+    def set_rule(self, rule):
+        """Sets a rule on a specified variable block in the dictionary
+
+        Parameters
+        ----------
+        rule : `Rule`
+            The rule to be set on the variable block
+
+        Raises
+        ------
+        `TypeError`
+            If ``rule`` is not of type `Rule`
+        """
+        if not isinstance(rule, Rule):
+            raise TypeError(type_error_message("rule", rule, Rule))
+        self.rule = repr(rule)
+
     def write(self, writer):
         """Writes the variable block to a file writer in ``.kdic`` format
 
@@ -1409,6 +1454,222 @@ def write(self, writer):
         writer.writeln("")
 
 
+class Rule:
+    """A rule of a variable in a Khiops dictionary
+
+    Parameters
+    ----------
+    name : str or bytes
+        Name or verbatim of the rule. It is intepreted as the verbatim
+        representation of an entire rule if and only if:
+
+            - it starts with an UpperCamelCase string, followed by a
+              parenthesized block (...)
+            - ``operands`` is empty
+
+    operands : tuple of operands
+        Each operand can have one of the following types:
+
+            - str
+            - bytes
+            - int
+            - float
+            - `Variable`
+            - `Rule`
+            - upper-scoped `Variable`
+            - upper-scoped `Rule`
+
+    is_reference : bool, default ``False``
+        If set to ``True``, then the rule is serialized as a reference rule:
+        ``Rule(Operand1, Operand2, ...)`` is serialized as
+        ``[Operand1, Operand2, ...]``.
+
+    Attributes
+    ----------
+    name : str or bytes
+        Name of the rule.
+    operands : tuple of operands
+        Each operand has one of the following types:
+
+            - str
+            - bytes
+            - int
+            - float
+            - `Variable`
+            - `Rule`
+            - upper-scoped `Variable`
+            - upper-scoped `Rule`
+
+    is_reference : bool
+        The reference status of the rule.
+
+        .. note::
+            This attribute cannot be changed on a `Rule` instance.
+    """
+
+    def __init__(self, name, *operands, is_reference=False):
+        """See class docstring"""
+        # Check input parameters
+        if not is_string_like(name):
+            raise TypeError(type_error_message("name", name, "string-like"))
+        for operand in operands:
+            if not is_string_like(operand) and not isinstance(
+                operand, (int, float, Variable, Rule, _ScopedOperand)
+            ):
+                raise TypeError(
+                    type_error_message(
+                        f"Operand '{operand}'",
+                        operand,
+                        "string-like",
+                        int,
+                        float,
+                        Variable,
+                        Rule,
+                        "upper-scoped Variable",
+                        "upper-scoped Rule",
+                    )
+                )
+        if not isinstance(is_reference, bool):
+            raise TypeError(type_error_message("is_reference", is_reference, bool))
+        if not is_reference and not name:
+            raise ValueError("'name' must be a non-empty string")
+
+        # Initialize attributes
+        self.name = name
+        self.operands = operands
+        self._is_reference = is_reference
+
+    @property
+    def is_reference(self):
+        return self._is_reference
+
+    def __repr__(self):
+        stream = io.BytesIO()
+        writer = KhiopsOutputWriter(stream)
+        self.write(writer)
+        return str(stream.getvalue(), encoding="utf8", errors="replace")
+
+    def copy(self):
+        """Copies this rule instance
+
+        Returns
+        -------
+        `Rule`
+            A copy of this instance
+        """
+        return Rule(self.name, *self.operands)
+
+    def write(self, writer):
+        """Writes the rule to a file writer in the ``.kdic`` format
+
+        Parameters
+        ----------
+        writer : `.KhiopsOutputWriter`
+            Output writer.
+
+            .. note::
+                If ``self.is_reference`` is set, then ``self.name`` is not
+                included in the serialization.
+        """
+        # Check the type of the writer
+        if not isinstance(writer, KhiopsOutputWriter):
+            raise TypeError(type_error_message("writer", writer, KhiopsOutputWriter))
+
+        # Write standard rule
+        rule_pattern = r"^[A-Z]([a-zA-Z]*)\(?.*\)?$"
+        rule_regex = re.compile(rule_pattern)
+        bytes_rule_regex = re.compile(bytes(rule_pattern, encoding="ascii"))
+        if self.operands:
+            if self.is_reference:
+                writer.write("[")
+            else:
+                writer.write(_format_name(self.name))
+                writer.write("(")
+
+            # Write operand, according to its type
+            # Variable operands have their name written only
+            for i, operand in enumerate(self.operands):
+                if isinstance(operand, (Rule, _ScopedOperand)):
+                    operand.write(writer)
+                elif isinstance(operand, Variable):
+                    writer.write(_format_name(operand.name))
+                elif is_string_like(operand):
+                    writer.write(_quote_value(operand))
+                elif isinstance(operand, float) and not math.isfinite(operand):
+                    writer.write("#Missing")
+                # int or finite float cases
+                else:
+                    writer.write(str(operand))
+                if i < len(self.operands) - 1:
+                    writer.write(", ")
+            if self.is_reference:
+                writer.write("]")
+            else:
+                writer.write(")")
+        # Write verbatim-given rule
+        elif (
+            isinstance(self.name, str)
+            and rule_regex.match(self.name)
+            or isinstance(self.name, bytes)
+            and bytes_rule_regex.match(self.name)
+        ):
+            writer.write(self.name)
+
+
+class _ScopedOperand:
+    def __init__(self, operand):
+        assert type(operand) in (Variable, Rule, _ScopedOperand), type_error_message(
+            "operand", operand, Variable, Rule, "upper-scoped Variable or Rule"
+        )
+        self.operand = operand
+
+    def write(self, writer):
+        assert isinstance(writer, KhiopsOutputWriter), type_error_message(
+            "writer", writer, KhiopsOutputWriter
+        )
+        writer.write(".")
+        if isinstance(self.operand, Variable):
+            writer.write(_format_name(self.operand.name))
+        else:
+            self.operand.write(writer)
+
+    def __repr__(self):
+        stream = io.BytesIO()
+        writer = KhiopsOutputWriter(stream)
+        self.write(writer)
+        return str(stream.getvalue(), encoding="utf8", errors="replace")
+
+
+def upper_scope(operand):
+    """Applies the upper-scope operator ``.`` to an operand
+
+    Parameters
+    ----------
+    operand : `Variable`, `Rule`, upper-scoped `Variable` or upper-scoped `Rule`
+        Operand that is upper-scoped.
+
+    Raises
+    ------
+    `TypeError`
+        If the type of ``operand`` is not `Variable`, `Rule`, upper-scoped `Variable`
+        or upper-scoped `Rule`.
+
+    Returns
+    -------
+    upper-scoped operand
+        The upper-scoped operand, as if the upper-scope operator ``.`` were
+        applied to an operand in a rule in the ``.kdic`` dictionary language.
+
+    """
+    if not isinstance(operand, (Variable, Rule, _ScopedOperand)):
+        raise TypeError(
+            type_error_message(
+                "operand", operand, Variable, Rule, "upper-scoped Variable or Rule"
+            )
+        )
+    return _ScopedOperand(operand)
+
+
 class MetaData:
     """A metadata container for a dictionary, a variable or variable block
 

khiops/samples/samples.ipynb

@@ -875,17 +875,23 @@
     "fold_index_variable.name = \"FoldIndex\"\n",
     "fold_index_variable.type = \"Numerical\"\n",
     "fold_index_variable.used = False\n",
-    "fold_index_variable.rule = \"Ceil(Product(\" + str(fold_number) + \",  Random()))\"\n",
     "dictionary.add_variable(fold_index_variable)\n",
     "\n",
+    "# Create fold indexing rule and set it on `fold_index_variable`\n",
+    "dictionary.get_variable(fold_index_variable.name).set_rule(\n",
+    "    kh.Rule(\"Ceil\", kh.Rule(\"Product\", fold_number, kh.Rule(\"Random()\"))),\n",
+    ")\n",
+    "\n",
     "# Add variables that indicate if the instance is in the train dataset:\n",
     "for fold_index in range(1, fold_number + 1):\n",
     "    is_in_train_dataset_variable = kh.Variable()\n",
     "    is_in_train_dataset_variable.name = \"IsInTrainDataset\" + str(fold_index)\n",
     "    is_in_train_dataset_variable.type = \"Numerical\"\n",
     "    is_in_train_dataset_variable.used = False\n",
-    "    is_in_train_dataset_variable.rule = \"NEQ(FoldIndex, \" + str(fold_index) + \")\"\n",
     "    dictionary.add_variable(is_in_train_dataset_variable)\n",
+    "    dictionary.get_variable(is_in_train_dataset_variable.name).set_rule(\n",
+    "        kh.Rule(\"NEQ\", fold_index_variable, fold_index),\n",
+    "    )\n",
     "\n",
     "# Print dictionary with fold variables\n",
     "print(\"Dictionary file with fold variables\")\n",

khiops/samples/samples.py

@@ -728,17 +728,23 @@ def train_predictor_with_cross_validation():
     fold_index_variable.name = "FoldIndex"
     fold_index_variable.type = "Numerical"
     fold_index_variable.used = False
-    fold_index_variable.rule = "Ceil(Product(" + str(fold_number) + ",  Random()))"
     dictionary.add_variable(fold_index_variable)
 
+    # Create fold indexing rule and set it on `fold_index_variable`
+    dictionary.get_variable(fold_index_variable.name).set_rule(
+        kh.Rule("Ceil", kh.Rule("Product", fold_number, kh.Rule("Random()"))),
+    )
+
     # Add variables that indicate if the instance is in the train dataset:
     for fold_index in range(1, fold_number + 1):
         is_in_train_dataset_variable = kh.Variable()
         is_in_train_dataset_variable.name = "IsInTrainDataset" + str(fold_index)
         is_in_train_dataset_variable.type = "Numerical"
         is_in_train_dataset_variable.used = False
-        is_in_train_dataset_variable.rule = "NEQ(FoldIndex, " + str(fold_index) + ")"
         dictionary.add_variable(is_in_train_dataset_variable)
+        dictionary.get_variable(is_in_train_dataset_variable.name).set_rule(
+            kh.Rule("NEQ", fold_index_variable, fold_index),
+        )
 
     # Print dictionary with fold variables
     print("Dictionary file with fold variables")