Expose default construction rules and fix relevant documentation

popescu-v · popescu-v · commit c2db9121d17a · 2025-10-10T14:11:14.000+02:00
- separate construction rules into:
  - rules applied by default (`DEFAULT_CONSTRUCTION_RULES`);
  - calendar-related rules (`CALENDRICAL_CONSTRUCTION_RULES`);
- document the construction rules;
- fix the `construction_rules` parameter documentation in the Core API;
- fix the `n_features` parameter documentation the Sklearn estimator API;
- update the `feature_importances_` attribute documentation in the
  Sklearn estimator API accordingly.
diff --git a/khiops/core/api.py b/khiops/core/api.py
@@ -31,18 +31,10 @@
 from khiops.core.internals.runner import get_runner
 from khiops.core.internals.task import get_task_registry
 
-# List of all available construction rules in the Khiops tool
-all_construction_rules = [
-    "Day",
-    "DecimalTime",
-    "DecimalWeekDay",
-    "DecimalYear",
-    "DecimalYearTS",
-    "GetDate",
-    "GetTime",
+# Construction rules
+DEFAULT_CONSTRUCTION_RULES = [
     "GetValue",
     "GetValueC",
-    "LocalTimestamp",
     "TableCount",
     "TableCountDistinct",
     "TableMax",
@@ -53,9 +45,37 @@
     "TableSelection",
     "TableStdDev",
     "TableSum",
+]
+"""List of construction rules that Khiops uses by default
+
+.. note::
+    These are all the multi-table rules.
+"""  # pylint: disable=pointless-string-statement
+
+CALENDRICAL_CONSTRUCTION_RULES = [
+    "Day",
+    "DecimalTime",
+    "DecimalWeekDay",
+    "DecimalYear",
+    "DecimalYearTS",
+    "GetDate",
+    "GetTime",
+    "LocalTimestamp",
     "WeekDay",
     "YearDay",
 ]
+"""List of calendrical construction rules
+
+These rules include: date, time and timestamp rules.
+
+.. note::
+    These rules are not enabled by default. The user needs to explicitly
+    select each of them via the ``construction_rules`` parameter of the
+    relevant Core API functions.
+"""  # pylint: disable=pointless-string-statement
+
+# List of all available construction rules in the Khiops tool
+ALL_CONSTRUCTION_RULES = DEFAULT_CONSTRUCTION_RULES + CALENDRICAL_CONSTRUCTION_RULES
 
 ##########################
 # Private module methods #
@@ -758,8 +778,9 @@ def train_predictor(
     max_constructed_variables : int, default 1000
         Maximum number of variables to construct.
     construction_rules : list of str, optional
-        Allowed rules for the automatic variable construction. If not set it uses all
-        possible rules.
+        Allowed rules for the automatic variable construction. If not set, Khiops
+        uses the multi-table construction rules listed in
+        `DEFAULT_CONSTRUCTION_RULES`.
     max_text_features : int, default 10000
         Maximum number of text features to construct.
     text_features : str, default "words"
@@ -1190,21 +1211,22 @@ def train_recoder(
     max_constructed_variables : int, default 100
         Maximum number of variables to construct.
     construction_rules : list of str, optional
-        Allowed rules for the automatic variable construction. If not set it uses all
-        possible rules.
+        Allowed rules for the automatic variable construction. If not set, Khiops
+        uses the multi-table construction rules listed in
+        `DEFAULT_CONSTRUCTION_RULES`.
     max_text_features : int, default 10000
         Maximum number of text features to construct.
     text_features : str, default "words"
         Type of the text features. Can be either one of:
 
-        - "words": sequences of non-space characters
-        - "ngrams": sequences of bytes
-        - "tokens": user-defined
+            - "words": sequences of non-space characters
+            - "ngrams": sequences of bytes
+            - "tokens": user-defined
 
     max_trees : int, default 10
         Maximum number of trees to construct.
     max_pairs : int, default 0
-        Maximum number of variables pairs to construct.
+        Maximum number of variable pairs to construct.
     specific_pairs : list of tuple, optional
         User-specified pairs as a list of 2-tuples of feature names. If a given tuple
         contains only one non-empty feature name, then it generates all the pairs
diff --git a/khiops/samples/samples.ipynb b/khiops/samples/samples.ipynb
@@ -503,7 +503,7 @@
    "metadata": {},
    "source": [
     "### `train_predictor_mt_with_specific_rules()`\n\n",
-    "Trains a multi-table predictor with specific construction rules\n\n    It is the same as `.train_predictor_mt` but with the specification of the allowed\n    variable construction rules. The list of available rules is found in the field\n    ``kh.all_construction_rules``\n    \n"
+    "Trains a multi-table predictor with specific construction rules\n\n    It is the same as `.train_predictor_mt` but with the specification of the allowed\n    variable construction rules. The list of available rules is found in the field\n    ``kh.ALL_CONSTRUCTION_RULES``\n    \n"
    ]
   },
   {
diff --git a/khiops/samples/samples.py b/khiops/samples/samples.py
@@ -432,7 +432,7 @@ def train_predictor_mt_with_specific_rules():
 
     It is the same as `.train_predictor_mt` but with the specification of the allowed
     variable construction rules. The list of available rules is found in the field
-    ``kh.all_construction_rules``
+    ``kh.ALL_CONSTRUCTION_RULES``
     """
     # Imports
     import os
diff --git a/khiops/sklearn/estimators.py b/khiops/sklearn/estimators.py
@@ -1704,8 +1704,9 @@ class KhiopsClassifier(ClassifierMixin, KhiopsPredictor):
     Parameters
     ----------
     n_features : int, default 100
-        *Multi-table only* : Maximum number of multi-table aggregate features to
-        construct. See :doc:`/multi_table_primer` for more details.
+        Maximum number of features to construct automatically. See
+        :doc:`/multi_table_primer` for more details on the multi-table-specific
+        features.
     n_pairs : int, default 0
         Maximum number of pair features to construct. These features are 2D grid
         partitions of univariate feature pairs. The grid is optimized such that in each
@@ -1740,8 +1741,9 @@ class KhiopsClassifier(ClassifierMixin, KhiopsPredictor):
         Pairs specified with ``specific_pairs`` have top priority: they are constructed
         first.
     construction_rules : list of str, optional
-        Allowed rules for the automatic feature construction. If not set, it uses all
-        possible rules.
+        Allowed rules for the automatic feature construction. If not set, Khiops
+        uses the multi-table construction rules listed in
+        `kh.DEFAULT_CONSTRUCTION_RULES <khiops.core.api.DEFAULT_CONSTRUCTION_RULES>`
     group_target_value : bool, default ``False``
         Allows grouping of the target values in classification. It can substantially
         increase the training time.
@@ -1794,7 +1796,7 @@ class KhiopsClassifier(ClassifierMixin, KhiopsPredictor):
             one must disable most AutoML capabilities of Khiops, namely:
 
              - the training dataset must be monotable;
-             - no timestamp column should be used in the training dataset;
+             - the ``n_features`` parameter must be set to 0;
              - the ``n_trees`` parameter must be set to 0;
              - the ``n_pairs`` parameter must be left to its default value, 0;
              - the ``n_text_features`` parameter must be set to 0.
@@ -2159,17 +2161,19 @@ class KhiopsRegressor(RegressorMixin, KhiopsPredictor):
     Parameters
     ----------
     n_features : int, default 100
-        *Multi-table only* : Maximum number of multi-table aggregate features to
-        construct. See :doc:`/multi_table_primer` for more details.
+        Maximum number of features to construct automatically. See
+        :doc:`/multi_table_primer` for more details on the multi-table-specific
+        features.
     n_selected_features : int, default 0
         Maximum number of features to be selected in the SNB predictor. If equal to
         0 it selects all the features kept in the training.
     n_evaluated_features : int, default 0
         Maximum number of features to be evaluated in the SNB predictor training. If
         equal to 0 it evaluates all informative features.
     construction_rules : list of str, optional
-        Allowed rules for the automatic feature construction. If not set, it uses all
-         possible rules.
+        Allowed rules for the automatic feature construction. If not set, Khiops
+        uses the multi-table construction rules listed in
+        `kh.DEFAULT_CONSTRUCTION_RULES <khiops.core.api.DEFAULT_CONSTRUCTION_RULES>`.
     verbose : bool, default ``False``
         If ``True`` it prints debug information and it does not erase temporary files
         when fitting, predicting or transforming.
@@ -2212,7 +2216,7 @@ class KhiopsRegressor(RegressorMixin, KhiopsPredictor):
             one must disable most AutoML capabilities of Khiops, namely:
 
              - the training dataset must be monotable;
-             - no timestamp column should be used in the training dataset;
+             - the ``n_features`` parameter must be set to 0;
              - the ``n_trees`` parameter must be set to 0;
              - the ``n_pairs`` parameter must be left to its default value, 0;
              - the ``n_text_features`` parameter must be set to 0.
@@ -2386,8 +2390,9 @@ class KhiopsEncoder(TransformerMixin, KhiopsSupervisedEstimator):
     categorical_target : bool, default ``True``
         ``True`` if the target column is categorical.
     n_features : int, default 100
-        *Multi-table only* : Maximum number of multi-table aggregate features to
-        construct. See :doc:`/multi_table_primer` for more details.
+        Maximum number of features to construct automatically. See
+        :doc:`/multi_table_primer` for more details on the multi-table-specific
+        features.
     n_pairs : int, default 0
         Maximum number of pair features to construct. These features are 2D grid
         partitions of univariate feature pairs. The grid is optimized such that in each
@@ -2415,8 +2420,9 @@ class KhiopsEncoder(TransformerMixin, KhiopsSupervisedEstimator):
         Pairs specified with ``specific_pairs`` have top priority: they are constructed
         first.
     construction_rules : list of str, optional
-        Allowed rules for the automatic feature construction. If not set, it uses all
-         possible rules.
+        Allowed rules for the automatic feature construction. If not set, Khiops
+        uses the multi-table construction rules listed in
+        `kh.DEFAULT_CONSTRUCTION_RULES <khiops.core.api.DEFAULT_CONSTRUCTION_RULES>`.
     informative_features_only : bool, default ``True``
         If ``True`` keeps only informative features.
     group_target_value : bool, default ``False``

Original file line number	Diff line number	Diff line change
`@@ -503,7 +503,7 @@`
`503`	`503`	`"metadata": {},`
`504`	`504`	`"source": [`
`505`	`505`	"### `train_predictor_mt_with_specific_rules()`\n\n",
`506`		- "Trains a multi-table predictor with specific construction rules\n\n It is the same as `.train_predictor_mt` but with the specification of the allowed\n variable construction rules. The list of available rules is found in the field\n ``kh.all_construction_rules``\n \n"
	`506`	+ "Trains a multi-table predictor with specific construction rules\n\n It is the same as `.train_predictor_mt` but with the specification of the allowed\n variable construction rules. The list of available rules is found in the field\n ``kh.ALL_CONSTRUCTION_RULES``\n \n"
`507`	`507`	`]`
`508`	`508`	`},`
`509`	`509`	`{`