19016: Adds auto ablation to Howso Engine, MAJOR

howso/client/base.py

@@ -99,7 +99,6 @@ def set_random_seed(self, trainee_id, seed):
     @abstractmethod
     def train(
         self, trainee_id, cases, features=None, *,
-        ablatement_params=None,
         accumulate_weight_feature=None,
         batch_size=None,
         derived_features=None,
@@ -406,6 +405,32 @@ def analyze(
     def auto_analyze(self, trainee_id):
         """Auto-analyze the trainee model."""
 
+    @abstractmethod
+    def set_auto_ablation_params(
+        self,
+        trainee_id,
+        auto_ablation_enabled=False,
+        *,
+        auto_ablation_weight_feature=".case_weight",
+        conviction_lower_threshold=None,
+        conviction_upper_threshold=None,
+        exact_prediction_features=None,
+        infleunce_weight_entropy_threshold=0.6,
+        minimum_model_size=1_000,
+        relative_prediction_threshold_map=None,
+        residual_prediction_features=None,
+        tolerance_prediction_threshold_map=None,
+        **kwargs
+    ):
+        """Set trainee parameters for auto ablation."""
+
+    @abstractmethod
+    def get_auto_ablation_params(
+        self,
+        trainee_id
+    ):
+        """Get trainee parameters for auto ablation set by :meth:`set_auto_ablation_params`."""
+
     @abstractmethod
     def set_auto_analyze_params(
         self,

howso/direct/client.py

@@ -1179,7 +1179,6 @@ def train(  # noqa: C901
         cases: Union[List[List[object]], DataFrame],
         features: Optional[Iterable[str]] = None,
         *,
-        ablatement_params: Optional[Dict[str, List[object]]] = None,
         accumulate_weight_feature: Optional[str] = None,
         batch_size: Optional[int] = None,
         derived_features: Optional[Iterable[str]] = None,
@@ -1208,20 +1207,6 @@ def train(  # noqa: C901
                    cases DataFrame.
                 c. You want to re-order the columns that are trained.
 
-        ablatement_params : dict of str to list of object, optional
-            Where keys are a feature name and values are threshold_type where
-            threshold_type is one of:
-
-                - ['exact']: Don't train if prediction matches exactly
-                - ['tolerance', MIN, MAX]: Don't train if ``prediction
-                  >= (case value - MIN) & prediction <= (case value + MAX)``
-                - ['relative', PERCENT]: Don't train if
-                  ``abs(prediction - case value) / prediction <= PERCENT``
-                - ['residual']: Don't train if
-                  ``abs(prediction - case value) <= feature residual``
-
-            >>> {'species': ['exact'], 'sepal_length': ['tolerance', 0.1, 0.25]}
-
         accumulate_weight_feature : str, optional
             Name of feature into which to accumulate neighbors'
             influences as weight for ablated cases. If unspecified, will not
@@ -1324,7 +1309,6 @@ def train(  # noqa: C901
                 end = progress.current_tick + batch_size
                 response = self.howso.train(
                     trainee_id,
-                    ablatement_params=ablatement_params,
                     accumulate_weight_feature=accumulate_weight_feature,
                     derived_features=derived_features,
                     features=features,
@@ -5060,9 +5044,8 @@ def set_auto_analyze_params(  # noqa: C901
         if kwargs:
             warn_params = ', '.join(kwargs)
             warnings.warn(
-                f'The following auto analyze parameter(s) "{warn_params}" '
-                'are not officially supported by analyze and may or may not '
-                'have an effect.', UserWarning)
+                f'The following auto ablate parameter(s) "{warn_params}" '
+                'are not officially supported or may not have an effect.', UserWarning)
 
         self.howso.auto_analyze_params(
             trainee_id=trainee_id,
@@ -5074,6 +5057,88 @@ def set_auto_analyze_params(  # noqa: C901
             **kwargs
         )
         self._auto_persist_trainee(trainee_id)
+
+    def get_auto_ablation_params(self, trainee_id: str):
+        """
+        Get parameters set by :meth:`set_auto_ablation_params`.
+        """
+        self._auto_resolve_trainee(trainee_id)
+        return self.howso.get_auto_ablation_params(trainee_id)
+
+    def set_auto_ablation_params(
+        self,
+        trainee_id: str,
+        auto_ablation_enabled: bool = False,
+        *,
+        auto_ablation_weight_feature: str = ".case_weight",
+        conviction_lower_threshold: Optional[float] = None,
+        conviction_upper_threshold: Optional[float] = None,
+        exact_prediction_features: Optional[List[str]] = None,
+        influence_weight_entropy_threshold: float = 0.6,
+        minimum_model_size: int = 1_000,
+        relative_prediction_threshold_map: Optional[Dict[str, float]] = None,
+        residual_prediction_features: Optional[List[str]] = None,
+        tolerance_prediction_threshold_map: Optional[Dict[str, Tuple[float, float]]] = None,
+        **kwargs
+    ):
+        """
+        Set trainee parameters for auto ablation.
+
+        .. note::
+            Auto-ablation is experimental and the API may change without deprecation.
+
+        Parameters
+        ----------
+        trainee_id : str
+            The ID of the Trainee to set auto ablation parameters for.
+        auto_ablation_enabled : bool, default False
+            When True, the :meth:`train` method will ablate cases that meet the set criteria.
+        auto_ablation_weight_feature : str, default ".case_weight"
+            The weight feature that should be accumulated to when cases are ablated.
+        minimum_model_size : int, default 1,000
+            The threshold of the minimum number of cases at which the model should auto-ablate.
+        influence_weight_entropy_threshold : float, default 0.6
+            The influence weight entropy quantile that a case must be beneath in order to be trained.
+        exact_prediction_features : Optional[List[str]], optional
+            For each of the features specified, will ablate a case if the prediction matches exactly.
+        residual_prediction_features : Optional[List[str]], optional
+            For each of the features specified, will ablate a case if
+            abs(prediction - case value) / prediction <= feature residual.
+        tolerance_prediction_threshold_map : Optional[Dict[str, Tuple[float, float]]], optional
+            For each of the features specified, will ablate a case if the prediction >= (case value - MIN)
+            and the prediction <= (case value + MAX).
+        relative_prediction_threshold_map : Optional[Dict[str, float]], optional
+            For each of the features specified, will ablate a case if
+            abs(prediction - case value) / prediction <= relative threshold
+        conviction_lower_threshold : Optional[float], optional
+            The conviction value above which cases will be ablated.
+        conviction_upper_threshold : Optional[float], optional
+            The conviction value below which cases will be ablated.
+        """
+        params = dict(
+            auto_ablation_enabled=auto_ablation_enabled,
+            auto_ablation_weight_feature=auto_ablation_weight_feature,
+            minimum_model_size=minimum_model_size,
+            influence_weight_entropy_threshold=influence_weight_entropy_threshold,
+            exact_prediction_features=exact_prediction_features,
+            residual_prediction_features=residual_prediction_features,
+            tolerance_prediction_threshold_map=tolerance_prediction_threshold_map,
+            relative_prediction_threshold_map=relative_prediction_threshold_map,
+            conviction_lower_threshold=conviction_lower_threshold,
+            conviction_upper_threshold=conviction_upper_threshold,
+        )
+        params.update(kwargs)
+        if kwargs:
+            warn_params = ", ".join(kwargs)
+            warnings.warn(
+                f'The following parameter(s) "{warn_params}" are '
+                'not officially supported by auto ablation and may or may not have an effect.',
+                UserWarning
+            )
+        self._auto_resolve_trainee(trainee_id)
+        self.howso.set_auto_ablation_params(
+            trainee_id, **params
+        )
 
     def optimize(self, *args, **kwargs):
         """

howso/direct/core.py

@@ -757,6 +757,81 @@ def get_num_training_cases(self, trainee_id: str) -> Dict:
         """
         return self._execute("get_num_training_cases", {"trainee": trainee_id})
 
+    def get_auto_ablation_params(self, trainee_id: str):
+        """
+        Get trainee parameters for auto ablation set by :meth:`set_auto_ablation_params`.
+        """
+        return self._execute(
+            "get_auto_ablation_params", {"trainee": trainee_id}
+        )
+
+    def set_auto_ablation_params(
+        self,
+        trainee_id: str,
+        auto_ablation_enabled: bool = False,
+        *,
+        auto_ablation_weight_feature: str = ".case_weight",
+        conviction_lower_threshold: Optional[float] = None,
+        conviction_upper_threshold: Optional[float] = None,
+        exact_prediction_features: Optional[List[str]] = None,
+        influence_weight_entropy_threshold: float = 0.6,
+        minimum_model_size: int = 1_000,
+        relative_prediction_threshold_map: Optional[Dict[str, float]] = None,
+        residual_prediction_features: Optional[List[str]] = None,
+        tolerance_prediction_threshold_map: Optional[Dict[str, Tuple[float, float]]] = None,
+        **kwargs
+    ):
+        """
+        Set trainee parameters for auto ablation.
+
+        .. note::
+            Auto-ablation is experimental and the API may change without deprecation.
+
+        Parameters
+        ----------
+        trainee_id : str
+            The ID of the Trainee to set auto ablation parameters for.
+        auto_ablation_enabled : bool, default False
+            When True, the :meth:`train` method will ablate cases that meet the set criteria.
+        auto_ablation_weight_feature : str, default ".case_weight"
+            The weight feature that should be accumulated to when cases are ablated.
+        minimum_model_size : int, default 1,000
+            The threshold ofr the minimum number of cases at which the model should auto-ablate.
+        influence_weight_entropy_threshold : float, default 0.6
+            The influence weight entropy quantile that a case must be beneath in order to be trained.
+        exact_prediction_features : Optional[List[str]], optional
+            For each of the features specified, will ablate a case if the prediction matches exactly.
+        residual_prediction_features : Optional[List[str]], optional
+            For each of the features specified, will ablate a case if
+            abs(prediction - case value) / prediction <= feature residual.
+        tolerance_prediction_threshold_map : Optional[Dict[str, Tuple[float, float]]], optional
+            For each of the features specified, will ablate a case if the prediction >= (case value - MIN)
+            and the prediction <= (case value + MAX).
+        relative_prediction_threshold_map : Optional[Dict[str, float]], optional
+            For each of the features specified, will ablate a case if
+            abs(prediction - case value) / prediction <= relative threshold
+        conviction_lower_threshold : Optional[float], optional
+            The conviction value above which cases will be ablated.
+        conviction_upper_threshold : Optional[float], optional
+            The conviction value below which cases will be ablated.
+        """
+        return self._execute(
+            "set_auto_ablation_params",
+            {
+                "trainee": trainee_id,
+                "auto_ablation_enabled": auto_ablation_enabled,
+                "auto_ablation_weight_feature": auto_ablation_weight_feature,
+                "minimum_model_size": minimum_model_size,
+                "influence_weight_entropy_threshold": influence_weight_entropy_threshold,
+                "exact_prediction_features": exact_prediction_features,
+                "residual_prediction_features": residual_prediction_features,
+                "tolerance_prediction_threshold_map": tolerance_prediction_threshold_map,
+                "relative_prediction_threshold_map": relative_prediction_threshold_map,
+                "conviction_lower_threshold": conviction_lower_threshold,
+                "conviction_upper_threshold": conviction_upper_threshold,
+            }
+        )
+
     def auto_analyze_params(
         self,
         trainee_id: str,
@@ -1050,7 +1125,6 @@ def train(
         input_cases: List[List[Any]],
         features: Optional[Iterable[str]] = None,
         *,
-        ablatement_params: Optional[Dict[str, List[Any]]] = None,
         accumulate_weight_feature: Optional[str] = None,
         derived_features: Optional[Iterable[str]] = None,
         input_is_substituted: bool = False,
@@ -1069,8 +1143,6 @@ def train(
             One or more cases to train into the model.
         features : iterable of str, optional
             An iterable of feature names corresponding to the input cases.
-        ablatement_params : dict of str to list of object, optional
-            Parameters describing how to ablate cases.
         accumulate_weight_feature : str, optional
             Name of feature into which to accumulate neighbors'
             influences as weight for ablated cases. If unspecified, will not
@@ -1099,13 +1171,12 @@ def train(
         return self._execute("train", {
             "trainee": trainee_id,
             "input_cases": input_cases,
-            "features": features,
+            "accumulate_weight_feature": accumulate_weight_feature,
             "derived_features": derived_features,
-            "session": session,
-            "ablatement_params": ablatement_params,
-            "series": series,
+            "features": features,
             "input_is_substituted": input_is_substituted,
-            "accumulate_weight_feature": accumulate_weight_feature,
+            "series": series,
+            "session": session,
             "train_weights_only": train_weights_only,
         })