Merge pull request #311 from KhiopsML/243-improve-specific_pairs-documentation

Author: folmos-at-orange

doc/conf.py

@@ -92,12 +92,11 @@
         "color-admonition-title-background--note": "#CC6100",
         "font-stack": "Helvetica Neue, Helvetica, sans-serif",
     },
-    "source_repository": "https://github.com/khiopsml/khiops/",
     # Sets the Github Icon (the SVG is embedded, copied from furo's repo)
     "footer_icons": [
         {
             "name": "GitHub",
-            "url": "https://github.com/khiopsml/khiops",
+            "url": "https://github.com/khiopsml/khiops-python",
             "html": """
                 <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
                     <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>

khiops/core/api.py

@@ -748,12 +748,14 @@ def train_predictor(
     max_pairs : int, default 0
         Maximum number of variables pairs to construct.
     specific_pairs : list of tuple, optional
-        User-specified pairs as a list of 2-tuples of variable names. If a given tuple
-        contains only one non-empty variable name, then it generates all the pairs
-        containing it (within the limit ``max_pairs``).
+        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
+        containing it (within the maximum limit ``max_pairs``). These pairs have top
+        priority: they are constructed first.
     all_possible_pairs : bool, default ``True``
         If ``True`` tries to create all possible pairs within the limit ``max_pairs``.
-        The pairs and variables given in ``specific_pairs`` have priority.
+        Pairs specified with ``specific_pairs`` have top priority: they are constructed
+        first.
     only_pairs_with : str, default ""
         Constructs only pairs with the specifed variable name. If equal to the empty
         string "" it considers all variables to make pairs.
@@ -1072,12 +1074,14 @@ def train_recoder(
     max_pairs : int, default 0
         Maximum number of variables pairs to construct.
     specific_pairs : list of tuple, optional
-        User-specified pairs as a list of 2-tuples of variable names. If a given tuple
-        contains only one non-empty variable name, then it generates all the pairs
-        containing it (within the limit ``max_pairs``).
+        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
+        containing it (within the maximum limit ``max_pairs``). These pairs have top
+        priority: they are constructed first.
     all_possible_pairs : bool, default ``True``
         If ``True`` tries to create all possible pairs within the limit ``max_pairs``.
-        The pairs and variables given in ``specific_pairs`` have priority.
+        Pairs specified with ``specific_pairs`` have top priority: they are constructed
+        first.
     only_pairs_with : str, default ""
         Constructs only pairs with the specifed variable name. If equal to the empty
         string "" it considers all variables to make pairs.

khiops/sklearn/estimators.py

@@ -1926,11 +1926,11 @@ class KhiopsClassifier(ClassifierMixin, KhiopsPredictor):
         *Multi-table only* : Maximum number of multi-table aggregate features to
         construct. See :doc:`/multi_table_primer` for more details.
     n_pairs : int, default 0
-        Maximum number of pair features to construct. These features represent a 2D grid
-        partition of the domain of a pair of features in which is optimized in a way
-        that the cells are the purest possible with respect to the target. Only pairs
-        which jointly are more informative that its univariate components may be taken
-        into account in the classifier.
+        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
+        cell the target distribution is well approximated by a constant histogram. Only
+        pairs that are jointly more informative than their marginals may be taken into
+        account in the classifier.
     n_trees : int, default 10
         Maximum number of decision tree features to construct. The constructed trees
         combine other features, either native or constructed. These features usually
@@ -1945,13 +1945,15 @@ class KhiopsClassifier(ClassifierMixin, KhiopsPredictor):
     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
-        containing it (within the maximum limit n_pairs).
-    all_possible_pairs : bool, default True
-        If True tries to create all possible pairs within the limit max_pairs.
-        The pairs and features given in specific_pairs have priority.
+        containing it (within the maximum limit ``n_pairs``). These pairs have top
+        priority: they are constructed first.
+    all_possible_pairs : bool, default ``True``
+        If ``True`` tries to create all possible pairs within the limit ``n_pairs``.
+        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.
+        possible rules.
     group_target_value : bool, default ``False``
         Allows grouping of the target values in classification. It can substantially
         increase the training time.
@@ -2405,11 +2407,11 @@ class KhiopsRegressor(RegressorMixin, KhiopsPredictor):
         *Multi-table only* : Maximum number of multi-table aggregate features to
         construct. See :doc:`/multi_table_primer` for more details.
     n_pairs : int, default 0
-        Maximum number of pair features to construct. These features represent a 2D grid
-        partition of the domain of a pair of features in which is optimized in a way
-        that the cells are the purest possible with respect to the target. Only pairs
-        which jointly are more informative that its univariate components may be taken
-        into account in the regressor.
+        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
+        cell the target distribution is well approximated by a constant histogram. Only
+        pairs that are jointly more informative than their marginals may be taken into
+        account in the regressor.
     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.
@@ -2419,10 +2421,12 @@ class KhiopsRegressor(RegressorMixin, KhiopsPredictor):
     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
-        containing it (within the maximum limit n_pairs).
-    all_possible_pairs : bool, default True
-        If True tries to create all possible pairs within the limit max_pairs.
-        The pairs and features given in specific_pairs have priority.
+        containing it (within the maximum limit ``n_pairs``). These pairs have top
+        priority: they are constructed first.
+    all_possible_pairs : bool, default ``True``
+        If ``True`` tries to create all possible pairs within the limit ``n_pairs``.
+        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.
@@ -2678,20 +2682,24 @@ class KhiopsEncoder(TransformerMixin, KhiopsSupervisedEstimator):
         *Multi-table only* : Maximum number of multi-table aggregate features to
         construct. See :doc:`/multi_table_primer` for more details.
     n_pairs : int, default 0
-        Maximum number of pair features to construct. These features represent a 2D grid
-        partition of the domain of a pair of features in which is optimized in a way
-        that the cells are the purest possible with respect to the target.
+        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
+        cell the target distribution is well approximated by a constant histogram. Only
+        pairs that are jointly more informative than their marginals may be taken into
+        account in the encoder.
     n_trees : int, default 10
         Maximum number of decision tree features to construct. The constructed trees
         combine other features, either native or constructed. These features usually
         improve a predictor's performance at the cost of interpretability of the model.
     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
-        containing it (within the maximum limit n_pairs).
-    all_possible_pairs : bool, default True
-        If True tries to create all possible pairs within the limit max_pairs.
-        The pairs and features given in specific_pairs have priority.
+        containing it (within the maximum limit ``n_pairs``). These pairs have top
+        priority: they are constructed first.
+    all_possible_pairs : bool, default ``True``
+        If ``True`` tries to create all possible pairs within the limit ``n_pairs``.
+        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.