Update interpret_predictor to the latest Core alpha 10.7.3-a.0

- drop lever variables
- reinstate max_variable_importances
- add global vs. individual variable importance computation suppport

Author: popescu-v

doc/samples/samples.rst

@@ -1064,7 +1064,7 @@ Samples
     dictionary_file_path = os.path.join(accidents_dir, "Accidents.kdic")
     accidents_table_path = os.path.join(accidents_dir, "Accidents.txt")
     vehicles_table_path = os.path.join(accidents_dir, "Vehicles.txt")
-    output_dir = os.path.join("kh_samples", "deploy_model_mt")
+    output_dir = os.path.join("kh_samples", "deploy_model_mt_with_interpretation")
     report_file_path = os.path.join(output_dir, "AnalysisResults.khj")
     interpretor_file_path = os.path.join(output_dir, "InterpretationModel.kdic")
     output_data_table_path = os.path.join(output_dir, "InterpretedAccidents.txt")
@@ -1088,7 +1088,8 @@ Samples
         model_dictionary_file_path,
         "SNB_Accident",
         interpretor_file_path,
-        reinforcement_target_value="NonLethal",
+        max_variable_importances=3,
+        importance_ranking="Individual",
     )
 
     # Deploy the interpretation model on the database

khiops/core/api.py

@@ -375,16 +375,6 @@ def _preprocess_task_arguments(task_args):
         if isinstance(task_args["selection_value"], (int, float)):
             task_args["selection_value"] = str(task_args["selection_value"])
 
-    # Discard the max_variable_importances interpretation parameters
-    if "max_variable_importances" in task_args:
-        if task_args["max_variable_importances"] is not None:
-            warnings.warn(
-                "The 'max_variable_importances' parameter of the "
-                "'khiops.core.api.interpret_predictor' function is not supported "
-                " yet. All model variables' importances are computed."
-            )
-        del task_args["max_variable_importances"]
-
     # Detect and replace deprecated data-path syntax on additional_data_tables
     # Mutate task_args in the process
     for data_path_task_arg_name in (
@@ -880,9 +870,8 @@ def interpret_predictor(
     dictionary_file_path_or_domain,
     predictor_dictionary_name,
     interpretor_file_path,
-    max_variable_importances=None,
-    reinforcement_target_value="",
-    reinforcement_lever_variables=None,
+    max_variable_importances=100,
+    importance_ranking="Global",
     log_file_path=None,
     output_scenario_path=None,
     task_file_path=None,
@@ -905,18 +894,17 @@ def interpret_predictor(
         Name of the predictor dictionary used while building the interpretation model.
     interpretor_file_path : str
         Path to the interpretor dictionary file.
-    max_variable_importances : int, optional
+    max_variable_importances : int, default 100
         Maximum number of variable importances to be selected in the interpretation
-        model. If not set, then all the variables in the prediction model are
-        considered.
-        ..note:: Not currently supported; not taken into account if set.
-    reinforcement_target_value : str, default ""
-        If this target value is specified, then its probability of occurrence is
-        tentatively increased.
-    reinforcement_lever_variables : list of str, optional
-        The names of variables to use as lever variables while building the
-        interpretation model. Min length: 0. Max length: the total number of variables
-        in the prediction model. If not specified, all variables are used.
+        model. If the predictor contains fewer variables than this number, then
+        all the variables of the predictor are considered.
+    importance_ranking : str, default "Global"
+        Ranking of the Shapley values produced by the interpretor. Ca be one of:
+
+        - "Global": predictor variables are ranked by decreasing global importance.
+
+        - "Individual": predictor variables are ranked by decreasing individual
+          Shapley value.
     ... :
         See :ref:`core-api-common-params`.
 
@@ -931,6 +919,7 @@ def interpret_predictor(
     --------
     See the following functions of the ``samples.py`` documentation script:
         - `samples.interpret_predictor()`
+        - `samples.deploy_model_mt_with_interpretation()`
     """
     # Save the task arguments
     # WARNING: Do not move this line, see the top of the "tasks" section for details

khiops/core/internals/tasks/interpret_predictor.py

@@ -6,7 +6,7 @@
 ######################################################################################
 """interpret_predictor task family"""
 from khiops.core.internals import task as tm
-from khiops.core.internals.types import ListType, StringLikeType
+from khiops.core.internals.types import IntType, StringLikeType
 
 # Disable long lines to have readable scenarios
 # pylint: disable=line-too-long
@@ -21,8 +21,8 @@
             ("interpretor_file_path", StringLikeType),
         ],
         [
-            ("reinforcement_target_value", StringLikeType, ""),
-            ("reinforcement_lever_variables", ListType(StringLikeType), None),
+            ("max_variable_importances", IntType, 100),
+            ("importance_ranking", StringLikeType, "Global"),
         ],
         ["dictionary_file_path", "interpretor_file_path"],
         # pylint: disable=line-too-long
@@ -38,14 +38,12 @@
 
         // Interpret model
         LearningTools.InterpretPredictor
-        HowParameter.HowClass __reinforcement_target_value__
 
-        __DICT__
-        __reinforcement_lever_variables__
-        HowParameter.leverVariablesSpecView.UnselectAll
-        HowParameter.leverVariablesSpecView.AttributeSpecs.List.Key
-        HowParameter.leverVariablesSpecView.AttributeSpecs.Used
-        __END_DICT__
+        // Number of predictor variables exploited in the interpretation model
+        ContributionAttributeNumber __max_variable_importances__
+
+        // Ranking of the Shapley value produced by the interpretation model
+        ShapleyValueRanking __importance_ranking__
 
         // Build interpretation dictionary
         BuildInterpretationClass

khiops/samples/samples.ipynb

@@ -1396,7 +1396,7 @@
    "metadata": {},
    "source": [
     "### `deploy_model_mt_with_interpretation()`\n\n",
-    "Deploys a multi-table interpretor in the simplest way possible\n\n    It is a call to `~.api.deploy_model` with additional parameters to handle\n    multi-table deployment.\n\n    In this example, a Selective Naive Bayes (SNB) interpretation model is\n    deployed by applying its associated dictionary to the input database.\n    The model variable importances are written to the output data table.\n    \n"
+    "Deploys a multi-table interpretor in the simplest way possible\n\n    It is a call to `~.api.deploy_model` with additional parameters related to\n    the variable importances.\n\n    In this example, a Selective Naive Bayes (SNB) interpretation model is\n    deployed by applying its associated dictionary to the input database.\n    The model variable importances are written to the output data table.\n    \n"
    ]
   },
   {
@@ -1414,7 +1414,7 @@
     "dictionary_file_path = os.path.join(accidents_dir, \"Accidents.kdic\")\n",
     "accidents_table_path = os.path.join(accidents_dir, \"Accidents.txt\")\n",
     "vehicles_table_path = os.path.join(accidents_dir, \"Vehicles.txt\")\n",
-    "output_dir = os.path.join(\"kh_samples\", \"deploy_model_mt\")\n",
+    "output_dir = os.path.join(\"kh_samples\", \"deploy_model_mt_with_interpretation\")\n",
     "report_file_path = os.path.join(output_dir, \"AnalysisResults.khj\")\n",
     "interpretor_file_path = os.path.join(output_dir, \"InterpretationModel.kdic\")\n",
     "output_data_table_path = os.path.join(output_dir, \"InterpretedAccidents.txt\")\n",
@@ -1438,7 +1438,8 @@
     "    model_dictionary_file_path,\n",
     "    \"SNB_Accident\",\n",
     "    interpretor_file_path,\n",
-    "    reinforcement_target_value=\"NonLethal\",\n",
+    "    max_variable_importances=3,\n",
+    "    importance_ranking=\"Individual\",\n",
     ")\n",
     "\n",
     "# Deploy the interpretation model on the database\n",

khiops/samples/samples.py

@@ -1184,8 +1184,8 @@ def deploy_model_mt():
 def deploy_model_mt_with_interpretation():
     """Deploys a multi-table interpretor in the simplest way possible
 
-    It is a call to `~.api.deploy_model` with additional parameters to handle
-    multi-table deployment.
+    It is a call to `~.api.deploy_model` with additional parameters related to
+    the variable importances.
 
     In this example, a Selective Naive Bayes (SNB) interpretation model is
     deployed by applying its associated dictionary to the input database.
@@ -1200,7 +1200,7 @@ def deploy_model_mt_with_interpretation():
     dictionary_file_path = os.path.join(accidents_dir, "Accidents.kdic")
     accidents_table_path = os.path.join(accidents_dir, "Accidents.txt")
     vehicles_table_path = os.path.join(accidents_dir, "Vehicles.txt")
-    output_dir = os.path.join("kh_samples", "deploy_model_mt")
+    output_dir = os.path.join("kh_samples", "deploy_model_mt_with_interpretation")
     report_file_path = os.path.join(output_dir, "AnalysisResults.khj")
     interpretor_file_path = os.path.join(output_dir, "InterpretationModel.kdic")
     output_data_table_path = os.path.join(output_dir, "InterpretedAccidents.txt")
@@ -1224,7 +1224,8 @@ def deploy_model_mt_with_interpretation():
         model_dictionary_file_path,
         "SNB_Accident",
         interpretor_file_path,
-        reinforcement_target_value="NonLethal",
+        max_variable_importances=3,
+        importance_ranking="Individual",
     )
 
     # Deploy the interpretation model on the database