22911: Renames Feature Influence detail keys and removes feature influence matrices, MAJOR (#361)

- Renames the supported keys
- Adds deprecation support for old key usage (both in and out)
- Adds test to ensure deprecated keys, if used, return the correct
details
- Removes the methods, trainee.get_mda_matrix,
trainee.get_contribution_matrix
- Removes the utility methods get_matrix_diff

NOTE: This won't pass tests until
howsoai/howso-engine#435 is merged.

---------

Co-authored-by: jack-xia-dp <[email protected]>

Author: mkoistinen

howso/client/base.py

@@ -9,6 +9,9 @@
 import numpy as np
 import pandas as pd
 
+from howso.utilities.constants import _RENAMED_DETAIL_KEYS  # type: ignore reportPrivateUsage
+
+
 __all__ = [
     "Reaction"
 ]
@@ -44,24 +47,57 @@ class Reaction(abc.MutableMapping):
 
     SPECIAL_KEYS = {"action_features", }
     KNOWN_KEYS = {
-        "case_directional_feature_contributions_full", "case_directional_feature_contributions_robust",
-        "directional_feature_contributions_full", "directional_feature_contributions_robust",
-        "boundary_cases_familiarity_convictions", "boundary_cases",
-        "boundary_values", "feature_case_contributions_full",
-        "feature_case_contributions_robust", "case_feature_contributions_full",
-        "case_feature_contributions_robust", "case_feature_residuals_robust", "case_feature_residuals_full",
-        "case_mda_full", "case_mda_robust", "categorical_action_probabilities", "context_values",
-        "derivation_parameters", "distance_contribution", "distance_ratio_parts", "distance_ratio",
-        "feature_contributions_full", "feature_contributions_robust", "feature_deviations",
-        "feature_mda_ex_post_full", "feature_mda_ex_post_robust", "feature_mda_robust", "feature_mda_full",
-        "feature_residuals_full", "feature_residuals_robust", "generate_attempts", "series_generate_attempts",
-        "hypothetical_values", "influential_cases_familiarity_convictions", "influential_cases_raw_weights",
-        "influential_cases", "case_feature_residual_convictions_full",
-        "case_feature_residual_convictions_robust", "most_similar_case_indices", "most_similar_cases",
-        "observational_errors", "prediction_stats", "outlying_feature_values", "robust_influences",
+        "boundary_cases",
+        "boundary_cases_familiarity_convictions",
+        "boundary_values",
+        "case_full_accuracy_contributions",
+        "case_full_prediction_contributions",
+        "case_robust_accuracy_contributions",
+        "case_robust_prediction_contributions",
+        "categorical_action_probabilities",
+        "context_values",
+        "derivation_parameters",
+        "distance_contribution",
+        "distance_ratio_parts",
+        "distance_ratio",
+        "feature_deviations",
+        "feature_full_accuracy_contributions_ex_post",
+        "feature_full_accuracy_contributions",
+        "feature_full_directional_prediction_contributions",
+        "feature_full_directional_prediction_contributions_for_case",
+        "feature_full_prediction_contributions_for_case",
+        "feature_full_prediction_contributions",
+        "feature_full_residual_convictions_for_case",
+        "feature_full_residuals_for_case",
+        "feature_full_residuals",
+        "feature_robust_accuracy_contributions_ex_post",
+        "feature_robust_accuracy_contributions",
+        "feature_robust_directional_prediction_contributions",
+        "feature_robust_directional_prediction_contributions_for_case",
+        "feature_robust_prediction_contributions_for_case",
+        "feature_robust_prediction_contributions",
+        "feature_robust_residual_convictions_for_case",
+        "feature_robust_residuals_for_case",
+        "feature_robust_residuals",
+        "generate_attempts",
+        "hypothetical_values",
+        "influential_cases_familiarity_convictions",
+        "influential_cases_raw_weights",
+        "influential_cases",
+        "most_similar_case_indices",
+        "most_similar_cases",
+        "observational_errors",
+        "outlying_feature_values",
+        "prediction_stats",
+        "robust_influences",
+        "series_generate_attempts",
         "similarity_conviction",
     }
 
+    # These detail keys are deprecated, but should be treated as KNOWN_KEYs
+    # during the deprecation period.
+    KNOWN_KEYS |= set(_RENAMED_DETAIL_KEYS.keys())
+
     def __init__(self,
                  action: t.Optional[pd.DataFrame | list | dict] = None,
                  details: t.Optional[abc.MutableMapping[str, t.Any]] = None

howso/client/schemas/reaction.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 import importlib.metadata
 import json
 import os
@@ -13,12 +14,18 @@
 
 import howso
 from howso.client import HowsoClient
-from howso.client.client import _check_isfile, get_configuration_path, get_howso_client_class, LEGACY_CONFIG_FILENAMES
+from howso.client.client import (
+    _check_isfile,  # type: ignore reportPrivateUsage
+    get_configuration_path,
+    get_howso_client_class,
+    LEGACY_CONFIG_FILENAMES
+)
 from howso.client.exceptions import HowsoApiError, HowsoConfigurationError, HowsoError
 from howso.client.protocols import ProjectClient
 from howso.client.schemas.reaction import Reaction
 from howso.direct import HowsoDirectClient
 from howso.utilities.testing import get_configurationless_test_client, get_test_options
+from howso.utilities.constants import _RENAMED_DETAIL_KEYS, _RENAMED_DETAIL_KEYS_EXTRA  # type: ignore reportPrivateUsage
 
 TEST_OPTIONS = get_test_options()
 
@@ -577,8 +584,8 @@ def test_a_la_cart_data(self, trainee):
                 ['similarity_conviction', ]
             ),
             (
-                {'feature_residuals_robust': True, },
-                ['feature_residuals_robust', ]
+                {'feature_robust_residuals': True, },
+                ['feature_robust_residuals', ]
             ),
         ]
         for audit_detail_set, keys_to_expect in details_sets:
@@ -590,6 +597,112 @@ def test_a_la_cart_data(self, trainee):
             details = response['details']
             assert (all(details[key] is not None for key in keys_to_expect))
 
+    @pytest.mark.parametrize('old_key,new_key', _RENAMED_DETAIL_KEYS.items())
+    def test_deprecated_detail_keys_react(self, trainee, old_key, new_key):
+        """Ensure using any of the deprecated keys raises a warning, but continues to work."""
+        # These keys shouldn't be tested like this:
+        if new_key in [
+            "feature_full_directional_prediction_contributions",
+            "feature_robust_directional_prediction_contributions",
+            "feature_full_accuracy_contributions_permutation",
+            "feature_robust_accuracy_contributions_permutation",
+        ]:
+            return True
+
+        with pytest.warns(DeprecationWarning) as record:
+            self.client.train(
+                trainee.id, [[1, 2], [1, 2], [1, 2]],
+                features=['penguin', 'play']
+            )
+            reaction = self.client.react(
+                trainee.id,
+                contexts=[['1']],
+                context_features=['penguin'],
+                action_features=['play'],
+                details={old_key: True}
+            )
+
+        # Check that the correct warning was raised.
+        assert len(record)
+        # There may be multiple warnings. Ensure at least one of them contains
+        # the deprecation message.
+        assert any([
+            f"'{old_key}' is deprecated" in str(r.message)
+            for r in record
+        ])
+
+        # We DO want the old_key to be present during the deprecation period.
+        assert old_key in reaction.get('details', {}).keys()
+
+        # We do NOT want the new_key present during the deprecation period.
+        assert new_key not in reaction.get('details', {}).keys()
+
+        # Some keys request multiple keys to be returned, these too should be
+        # converted to the old names if the old name was originally used.
+        if old_key in _RENAMED_DETAIL_KEYS_EXTRA.keys():
+            for old_extra_key, new_extra_key in _RENAMED_DETAIL_KEYS_EXTRA[old_key]["additional_keys"].items():
+                assert new_extra_key not in reaction.get('details', {}).keys()
+                assert old_extra_key in reaction.get('details', {}).keys()
+
+    @pytest.mark.parametrize('old_key,new_key', _RENAMED_DETAIL_KEYS.items())
+    def test_deprecated_detail_keys_react_aggregate(self, trainee, old_key, new_key):
+        """Ensure using any of the deprecated keys raises a warning, but continues to work."""
+        # These keys shouldn't be tested like this:
+        if new_key in {
+            "case_full_prediction_contributions",
+            "case_robust_prediction_contributions",
+            "feature_full_prediction_contributions_for_case",
+            "feature_robust_prediction_contributions_for_case",
+            "feature_full_residual_convictions_for_case",
+            "feature_robust_residual_convictions_for_case",
+            "feature_full_residuals_for_case",
+            "feature_robust_residuals_for_case",
+            "case_full_accuracy_contributions",
+            "case_robust_accuracy_contributions",
+            "feature_full_directional_prediction_contributions",
+            "feature_robust_directional_prediction_contributions",
+            "feature_full_accuracy_contributions_ex_post",
+            "feature_robust_accuracy_contributions_ex_post",
+        }:
+            return
+
+        with pytest.warns(DeprecationWarning) as record:
+            self.client.train(
+                trainee.id, [[1, 2], [1, 2], [1, 2]],
+                features=['penguin', 'play']
+            )
+            response = self.client.react_aggregate(
+                trainee.id,
+                action_feature='penguin',
+                num_samples=1,
+                details={old_key: True}
+            )
+
+        # Check that the correct warning was raised.
+        assert len(record)
+        # There may be multiple warnings. Ensure at least one of them contains
+        # the deprecation message.
+        assert any([
+            f"'{old_key}' is deprecated" in str(r.message)
+            for r in record
+        ])
+
+        # No point in testing further if we didn't get back a Mapping instance.
+        assert isinstance(response, Mapping), "react_aggregate did not return a Mapping."
+
+        # We DO want the old_key to be present during the deprecation period.
+        assert old_key in response.keys()
+
+        # We do NOT want the new_key present during the deprecation period.
+        assert new_key not in response.keys()
+
+        # Some keys request multiple keys to be returned, these too should be
+        # converted to the old names if the old name was originally used.
+        if old_key in _RENAMED_DETAIL_KEYS_EXTRA.keys():
+            for old_extra_key, new_extra_key in _RENAMED_DETAIL_KEYS_EXTRA[old_key]["additional_keys"].items():
+                assert new_extra_key not in response.keys()
+                assert old_extra_key in response.keys()
+
     def test_get_version(self):
         """Test get_version()."""
         version = self.client.get_version()

howso/client/tests/test_client.py

@@ -319,54 +319,6 @@ def test_delete_method_standalone_bad(self):
         ):
             delete_trainee(file_path=file_path)
 
-    def test_get_contribution_matrix(self, trainee):
-        """Test `get_contribution_matrix`."""
-        matrix = trainee.get_contribution_matrix(
-            normalize=True,
-            fill_diagonal=True
-        )
-        assert len(matrix) == 5
-        assert len(matrix.columns) == 5
-
-        # The raw matrix is saved in the trainee. This section
-        # tests to make sure the matrix processing parameters are
-        # passed through correctly.
-        saved_matrix = trainee.calculated_matrices
-        assert len(saved_matrix['contribution']) == 5
-        assert len(saved_matrix['contribution'].columns) == 5
-
-        saved_matrix = matrix_processing(
-            saved_matrix['contribution'],
-            normalize=True,
-            fill_diagonal=True
-        )
-
-        assert_frame_equal(matrix, saved_matrix)
-
-    def test_get_mda_matrix(self, trainee):
-        """Test `get_mda_matrix`."""
-        matrix = trainee.get_mda_matrix(
-            absolute=True,
-            fill_diagonal=True
-        )
-        assert len(matrix) == 5
-        assert len(matrix.columns) == 5
-
-        # The raw matrix is saved in the trainee. This section
-        # tests to make sure the matrix processing parameters are
-        # passed through correctly.
-        saved_matrix = trainee.calculated_matrices
-        assert len(saved_matrix['mda']) == 5
-        assert len(saved_matrix['mda'].columns) == 5
-
-        saved_matrix = matrix_processing(
-            saved_matrix['mda'],
-            absolute=True,
-            fill_diagonal=True
-        )
-
-        assert_frame_equal(matrix, saved_matrix)
-
     def test_reduce_data(self, trainee):
         """Test `reduce_data`."""
         pre_reduction_cases = trainee.get_cases()