FAI-825: Add feature and output name specification to models (#130)

* Added feature and output name specification to models, all python models will now map these names

* Unified as_df and as_html methods between SHAP and LIME

* linting, black, and merging

Author: RobGeada

src/trustyai/explainers/counterfactuals.py

@@ -224,9 +224,15 @@ def explain(
         :class:`~CounterfactualResult`
             Object containing the results of the counterfactual explanation.
         """
+        feature_names = model.feature_names if isinstance(model, Model) else None
+        output_names = model.output_names if isinstance(model, Model) else None
         _prediction = counterfactual_prediction(
-            input_features=one_input_convert(inputs, feature_domains=feature_domains),
+            input_features=one_input_convert(
+                inputs, feature_names=feature_names, feature_domains=feature_domains
+            ),
             outputs=goal,
+            feature_names=feature_names,
+            output_names=output_names,
             data_distribution=data_distribution,
             uuid=uuid,
             timeout=timeout,

src/trustyai/explainers/lime.py

@@ -153,7 +153,7 @@ def _matplotlib_plot(self, output_name: str, block=True) -> None:
                 else ds["positive_primary_colour"]
                 for i in dictionary.values()
             ]
-            plt.title(f"LIME explanation of {output_name}")
+            plt.title(f"LIME: Feature Importances to {output_name}")
             plt.barh(
                 range(len(dictionary)),
                 dictionary.values(),
@@ -306,7 +306,9 @@ def explain(
         :class:`~LimeResults`
             Object containing the results of the LIME explanation.
         """
-        _prediction = simple_prediction(inputs, outputs)
+        feature_names = model.feature_names if isinstance(model, Model) else None
+        output_names = model.output_names if isinstance(model, Model) else None
+        _prediction = simple_prediction(inputs, outputs, feature_names, output_names)
 
         with Model.ArrowTransmission(model, inputs):
             return LimeResults(self._explainer.explainAsync(_prediction, model).get())

src/trustyai/explainers/shap.py

@@ -254,7 +254,7 @@ def _matplotlib_plot(self, output_name, block=True) -> None:
             plt.xticks(np.arange(len(feature_names)), feature_names)
             plt.ylabel(self.saliency_map()[output_name].getOutput().getName())
             plt.xlabel("Feature SHAP Value")
-            plt.title(f"Explanation of {output_name}")
+            plt.title(f"SHAP: Feature Contributions to {output_name}")
             plt.show(block=block)
 
     def _get_bokeh_plot(self, output_name):
@@ -424,7 +424,9 @@ def __init__(self, datapoints: ManyInputsUnionType, feature_domains=None, seed=0
         seed : int
             The random seed to use in the sampling/generation method
         """
-        self.datapoints = many_inputs_convert(datapoints, feature_domains)
+        self.datapoints = many_inputs_convert(
+            datapoints, feature_domains=feature_domains
+        )
         self.feature_domains = feature_domains
         self.seed = 0
         self._jrandom = Random()
@@ -620,21 +622,18 @@ def __init__(
             link_type = _ShapConfig.LinkType.IDENTITY
         self._jrandom = Random()
         self._jrandom.setSeed(kwargs.get("seed", 0))
-        self.background = many_inputs_convert(background)
+        self._raw_background = background
         perturbation_context = PerturbationContext(self._jrandom, 0)
 
         self._configbuilder = (
             _ShapConfig.builder()
             .withLink(link_type)
             .withBatchSize(kwargs.get("batch_size", 20))
             .withPC(perturbation_context)
-            .withBackground(self.background)
             .withTrackCounterfactuals(kwargs.get("track_counterfactuals", False))
         )
         if kwargs.get("samples") is not None:
             self._configbuilder.withNSamples(JInt(kwargs["samples"]))
-        self._config = self._configbuilder.build()
-        self._explainer = _ShapKernelExplainer(self._config)
 
     @data_conversion_docstring("one_input", "one_output")
     def explain(
@@ -660,9 +659,14 @@ def explain(
         :class:`~SHAPResults`
             Object containing the results of the SHAP explanation.
         """
-        _prediction = simple_prediction(inputs, outputs)
 
+        feature_names = model.feature_names if isinstance(model, Model) else None
+        output_names = model.output_names if isinstance(model, Model) else None
+        _prediction = simple_prediction(inputs, outputs, feature_names, output_names)
+        _background = many_inputs_convert(self._raw_background, feature_names)
+        config = self._configbuilder.withBackground(_background).build()
+        explainer = _ShapKernelExplainer(config)
         with Model.ArrowTransmission(model, inputs):
             return SHAPResults(
-                self._explainer.explainAsync(_prediction, model).get(), self.background
+                explainer.explainAsync(_prediction, model).get(), _background
             )

src/trustyai/model/__init__.py

@@ -294,9 +294,7 @@ class Model:
     predictive model to interface with the TrustyAI Java library.
     """
 
-    def __init__(
-        self, predict_fun, dataframe_input=False, output_names=None, disable_arrow=False
-    ):
+    def __init__(self, predict_fun, **kwargs):
         """
         Wrap the model as a TrustyAI :obj:`PredictionProvider` Java class.
 
@@ -306,20 +304,26 @@ def __init__(
             A function that takes in a Numpy array or Pandas DataFrame as input and outputs a
             Pandas DataFrame or Numpy array. In general, the ``model.predict`` functions of
             sklearn-style models meet this requirement.
-        dataframe_input: bool
-            Whether `predict_fun` expects a :class:`pandas.DataFrame` as input.
-        output_names : List[String]:
-            If the model outputs a numpy array, you can specify the names of the model outputs
-            here.
-        disable_arrow: bool
-            If true, Apache Arrow will not be used to accelerate data transfer between Java
-            and Python. If false, Arrow will be automatically used in situations where it is
-            advantageous to do so.
+
+        Keyword Arguments:
+            * dataframe_input: bool
+                (default= ``False``) Whether `predict_fun` expects a :class:`pandas.DataFrame`
+                as input.
+            * feature_names : List[String]:
+                (default= ``None`) If the model receives a non-pandas input, you can specify the
+                names of the model input features here, with the ith element of the list
+                corresponding to the name of the ith feature.
+            * output_names : List[String]:
+                (default= ``None`) If the model outputs a non-pandas object, you can specify the
+                names of the model outputs here, with the ith element of the list corresponding to
+                the name of the ith output.
+            * disable_arrow: bool
+                (default= ``False`) If true, Apache Arrow will not be used to accelerate data
+                transfer between Java and Python. If false, Arrow will be automatically used in
+                situations where it is advantageous to do so.
         """
-        self.disable_arrow = disable_arrow
         self.predict_fun = predict_fun
-        self.output_names = output_names
-        self.dataframe_input = dataframe_input
+        self.kwargs = kwargs
 
         self.prediction_provider_arrow = None
         self.prediction_provider_normal = None
@@ -328,6 +332,26 @@ def __init__(
         # set model to use non-arrow by default, as this requires no dataset information
         self._set_nonarrow()
 
+    @property
+    def dataframe_input(self):
+        """Get dataframe_input kwarg value"""
+        return self.kwargs.get("dataframe_input")
+
+    @property
+    def feature_names(self):
+        """Get feature_names kwarg value"""
+        return self.kwargs.get("feature_names")
+
+    @property
+    def output_names(self):
+        """Get output_names kwarg value"""
+        return self.kwargs.get("output_names")
+
+    @property
+    def disable_arrow(self):
+        """Get disable_arrow kwarg value"""
+        return self.kwargs.get("disable_arrow")
+
     def _set_arrow(self, paradigm_input: PredictionInput):
         """
         Ready the model for arrow-based prediction communication.
@@ -825,7 +849,10 @@ def feature(
 # pylint: disable=line-too-long
 @data_conversion_docstring("one_input", "one_output")
 def simple_prediction(
-    input_features: OneInputUnionType, outputs: OneOutputUnionType
+    input_features: OneInputUnionType,
+    outputs: OneOutputUnionType,
+    feature_names: Optional[List[str]] = None,
+    output_names: Optional[List[str]] = None,
 ) -> SimplePrediction:
     """Wrap features and outputs into a SimplePrediction. Given a list of features and outputs,
     this function will bundle them into Prediction objects for use with the LIME and SHAP
@@ -838,10 +865,15 @@ def simple_prediction(
     outputs : {}
         The desired model outputs to be searched for in the counterfactual explanation.
         These can take the form of a: {}
+    feature_names: Optional[List[str]]
+        The names of the features, in the case where the feature object does not contain them
+    output_names: Optional[List[str]]
+        The names of the outputs, in the case where the outputobject does not contain them
     """
 
     return SimplePrediction(
-        one_input_convert(input_features), one_output_convert(outputs)
+        one_input_convert(input_features, feature_names),
+        one_output_convert(outputs, output_names),
     )
 
 
@@ -850,6 +882,8 @@ def simple_prediction(
 def counterfactual_prediction(
     input_features: OneInputUnionType,
     outputs: OneOutputUnionType,
+    feature_names: Optional[List[str]] = None,
+    output_names: Optional[List[str]] = None,
     data_distribution: Optional[DataDistribution] = None,
     uuid: Optional[_uuid.UUID] = None,
     timeout: Optional[float] = None,
@@ -865,6 +899,10 @@ def counterfactual_prediction(
     outputs : {}
         The desired model outputs to be searched for in the counterfactual explanation.
         These can take the form of a: {}
+    feature_names: Optional[List[str]]
+        The names of the features, in the case where the feature object does not contain them
+    output_names: Optional[List[str]]
+        The names of the outputs, in the case where the outputobject does not contain them
     data_distribution : Optional[:class:`DataDistribution`]
         The :class:`DataDistribution` to use when sampling the inputs.
     uuid : Optional[:class:`_uuid.UUID`]
@@ -878,8 +916,8 @@ def counterfactual_prediction(
         timeout = Long(timeout)
 
     return CounterfactualPrediction(
-        one_input_convert(input_features),
-        one_output_convert(outputs),
+        one_input_convert(input_features, feature_names),
+        one_output_convert(outputs, output_names),
         data_distribution,
         uuid,
         timeout,

src/trustyai/utils/data_conversions.py

@@ -6,7 +6,6 @@
 from itertools import filterfalse
 
 import trustyai.model
-from trustyai.model.domain import feature_domain
 from org.kie.trustyai.explainability.model import (
     Dataframe,
     Feature,
@@ -184,21 +183,29 @@ def domain_insertion(
 
 # === input functions ==============================================================================
 def one_input_convert(
-    python_inputs: OneInputUnionType, feature_domains: FeatureDomain = None
+    python_inputs: OneInputUnionType,
+    feature_names: Optional[List[str]] = None,
+    feature_domains: Optional[List[FeatureDomain]] = None,
 ) -> PredictionInput:
     """Convert an object of OneInputUnionType into a PredictionInput."""
     if isinstance(python_inputs, (int, float, np.number)):
         python_inputs = np.array([[python_inputs]])
-        pi = numpy_to_prediction_object(python_inputs, trustyai.model.feature)[0]
+        pi = numpy_to_prediction_object(
+            python_inputs, trustyai.model.feature, names=feature_names
+        )[0]
     elif isinstance(python_inputs, list) and all(
         (isinstance(x, (int, float, np.number)) for x in python_inputs)
     ):
         python_inputs = np.array(python_inputs).reshape(1, -1)
-        pi = numpy_to_prediction_object(python_inputs, trustyai.model.feature)[0]
+        pi = numpy_to_prediction_object(
+            python_inputs, trustyai.model.feature, names=feature_names
+        )[0]
     elif isinstance(python_inputs, np.ndarray):
         if len(python_inputs.shape) == 1:
             python_inputs = python_inputs.reshape(1, -1)
-        pi = numpy_to_prediction_object(python_inputs, trustyai.model.feature)[0]
+        pi = numpy_to_prediction_object(
+            python_inputs, trustyai.model.feature, names=feature_names
+        )[0]
     elif isinstance(python_inputs, pd.DataFrame):
         pi = df_to_prediction_object(python_inputs, trustyai.model.feature)[0]
     elif isinstance(python_inputs, pd.Series):
@@ -217,13 +224,17 @@ def one_input_convert(
 
 
 def many_inputs_convert(
-    python_inputs: ManyInputsUnionType, feature_domains: List[FeatureDomain] = None
+    python_inputs: ManyInputsUnionType,
+    feature_names: Optional[List[str]] = None,
+    feature_domains: Optional[List[FeatureDomain]] = None,
 ) -> List[PredictionInput]:
     """Convert an object of ManyInputsUnionType into a List[PredictionInput]"""
     if isinstance(python_inputs, np.ndarray):
         if len(python_inputs.shape) == 1:
             python_inputs = python_inputs.reshape(1, -1)
-        pis = numpy_to_prediction_object(python_inputs, trustyai.model.feature)
+        pis = numpy_to_prediction_object(
+            python_inputs, trustyai.model.feature, names=feature_names
+        )
     elif isinstance(python_inputs, pd.DataFrame):
         pis = df_to_prediction_object(python_inputs, trustyai.model.feature)
     else:
@@ -236,20 +247,28 @@ def many_inputs_convert(
 
 
 # === output functions =============================================================================
-def one_output_convert(python_outputs: OneOutputUnionType) -> PredictionOutput:
+def one_output_convert(
+    python_outputs: OneOutputUnionType, names: Optional[List[str]] = None
+) -> PredictionOutput:
     """Convert an object of OneOutputUnionType into a PredictionOutput"""
     if isinstance(python_outputs, (int, np.integer, float, np.inexact)):
         python_outputs = np.array([[python_outputs]])
-        po = numpy_to_prediction_object(python_outputs, trustyai.model.output)[0]
+        po = numpy_to_prediction_object(
+            python_outputs, trustyai.model.output, names=names
+        )[0]
     elif isinstance(python_outputs, list) and all(
         (isinstance(x, (int, float, np.number)) for x in python_outputs)
     ):
         python_outputs = np.array(python_outputs).reshape(1, -1)
-        po = numpy_to_prediction_object(python_outputs, trustyai.model.output)[0]
+        po = numpy_to_prediction_object(
+            python_outputs, trustyai.model.output, names=names
+        )[0]
     elif isinstance(python_outputs, np.ndarray):
         if len(python_outputs.shape) == 1:
             python_outputs = python_outputs.reshape(1, -1)
-        po = numpy_to_prediction_object(python_outputs, trustyai.model.output)[0]
+        po = numpy_to_prediction_object(
+            python_outputs, trustyai.model.output, names=names
+        )[0]
     elif isinstance(python_outputs, pd.DataFrame):
         po = df_to_prediction_object(python_outputs, trustyai.model.output)[0]
     elif isinstance(python_outputs, pd.Series):
@@ -265,13 +284,15 @@ def one_output_convert(python_outputs: OneOutputUnionType) -> PredictionOutput:
 
 
 def many_outputs_convert(
-    python_outputs: ManyOutputsUnionType,
+    python_outputs: ManyOutputsUnionType, names: Optional[List[str]] = None
 ) -> List[PredictionOutput]:
     """Convert an object of ManyOutputsUnionType into a List[PredictionOutput]"""
     if isinstance(python_outputs, np.ndarray):
         if len(python_outputs.shape) == 1:
             python_outputs = python_outputs.reshape(1, -1)
-        return numpy_to_prediction_object(python_outputs, trustyai.model.output)
+        return numpy_to_prediction_object(
+            python_outputs, trustyai.model.output, names=names
+        )
     if isinstance(python_outputs, pd.DataFrame):
         return df_to_prediction_object(python_outputs, trustyai.model.output)
     # fallback case is List[PredictionOutput]

tests/general/test_counterfactualexplainer.py

@@ -166,7 +166,7 @@ def test_counterfactual_with_domain_argument_overwrite():
      a warning"""
     np.random.seed(0)
     data = np.random.rand(1, 5)
-    domained_inputs = one_input_convert(data, [feature_domain((-10, 10)) for _ in range(5)])
+    domained_inputs = one_input_convert(data, feature_domains=[feature_domain((-10, 10)) for _ in range(5)])
     model_weights = np.random.rand(5)
     model = Model(lambda x: np.dot(x, model_weights))
     explainer = CounterfactualExplainer(steps=10_000)

tests/general/test_limeexplainer.py

@@ -165,3 +165,29 @@ def test_lime_as_html():
     explainer = LimeExplainer()
     explainer.explain(inputs=data, outputs=model(data), model=model)
     assert True
+
+    explanation = explainer.explain(inputs=data, outputs=model(data), model=model)
+    for score in explanation.as_dataframe()["output-0"]['Saliency']:
+        assert score != 0
+
+
+def test_lime_numpy():
+    np.random.seed(0)
+    data = np.random.rand(101, 5)
+    model_weights = np.random.rand(5)
+    predict_function = lambda x: np.stack([np.dot(x, model_weights), 2 * np.dot(x, model_weights)], -1)
+    fnames = ['f{}'.format(x) for x in "abcde"]
+    onames = ['o{}'.format(x) for x in "12"]
+    model = Model(predict_function,
+                  feature_names=fnames,
+                  output_names=onames
+                  )
+
+    explainer = LimeExplainer()
+    explanation = explainer.explain(inputs=data[0], outputs=model(data[0]), model=model)
+
+    for oname in onames:
+        assert oname in explanation.as_dataframe().keys()
+        for fname in fnames:
+            assert fname in explanation.as_dataframe()[oname]['Feature'].values
+