FAI-900: Added feature domain argument to counterfactuals (#128)

* Added feature domain argument to cfs

* fixed incorrect imports in cf test

Author: RobGeada

src/trustyai/explainers/counterfactuals.py

@@ -1,7 +1,7 @@
 """Explainers.countefactual module"""
 # pylint: disable = import-error, too-few-public-methods, wrong-import-order, line-too-long,
 # pylint: disable = unused-argument
-from typing import Optional, Union
+from typing import Optional, Union, List
 import matplotlib.pyplot as plt
 import matplotlib as mpl
 import pandas as pd
@@ -20,12 +20,14 @@
     Model,
 )
 
+
 from trustyai.utils.data_conversions import (
     prediction_object_to_numpy,
     prediction_object_to_pandas,
     OneInputUnionType,
     OneOutputUnionType,
     data_conversion_docstring,
+    one_input_convert,
 )
 
 from org.kie.trustyai.explainability.local.counterfactual import (
@@ -38,6 +40,9 @@
     DataDistribution,
     PredictionProvider,
 )
+
+from org.kie.trustyai.explainability.model.domain import FeatureDomain
+
 from org.optaplanner.core.config.solver.termination import TerminationConfig
 from java.lang import Long
 
@@ -181,11 +186,12 @@ def explain(
         inputs: OneInputUnionType,
         goal: OneOutputUnionType,
         model: Union[PredictionProvider, Model],
+        feature_domains: List[FeatureDomain] = None,
         data_distribution: Optional[DataDistribution] = None,
         uuid: Optional[_uuid.UUID] = None,
         timeout: Optional[float] = None,
     ) -> CounterfactualResult:
-        """Request for a counterfactual explanation given a list of features, goals and a
+        r"""Request for a counterfactual explanation given a list of features, goals and a
         :class:`~PredictionProvider`
 
         Parameters
@@ -197,6 +203,15 @@ def explain(
             These can take the form of a: {}
         model : :obj:`~trustyai.model.PredictionProvider`
             The TrustyAI model as generated by :class:`~trustyai.model.Model` or a Java :class:`PredictionProvider`
+        feature_domains : List[:class:`FeatureDomain`]
+            A list of feature domains (each created by :func:`~trustyai.model.feature_domain()`)
+            that define the valid domain of the input features. The ith element of the list defines
+            the domain of the ith input feature. If the ith element of this list is ``None``, the
+            no domain information will be added to the ith feature. If the ith feature had no
+            previously-supplied domain information, it will be taken to be constrained and
+            non-variable. If ``feature_domains=None``, no domain information will be added to any
+            of the features, thus preserving existing domains if they've been manually added
+            previously or holding undomained features constrained.
         data_distribution : Optional[:class:`DataDistribution`]
             The :class:`DataDistribution` to use when sampling the inputs.
         uuid : Optional[:class:`_uuid.UUID`]
@@ -210,7 +225,7 @@ def explain(
             Object containing the results of the counterfactual explanation.
         """
         _prediction = counterfactual_prediction(
-            input_features=inputs,
+            input_features=one_input_convert(inputs, feature_domains=feature_domains),
             outputs=goal,
             data_distribution=data_distribution,
             uuid=uuid,

src/trustyai/utils/data_conversions.py

@@ -1,7 +1,7 @@
 """Data Converters between Python and Java"""
 # pylint: disable = import-error, line-too-long, trailing-whitespace, unused-import, cyclic-import
 # pylint: disable = consider-using-f-string, invalid-name, wrong-import-order
-
+import warnings
 from typing import Union, List
 
 import trustyai.model
@@ -12,7 +12,10 @@
     PredictionInput,
     PredictionOutput,
 )
-from org.kie.trustyai.explainability.model.domain import FeatureDomain
+from org.kie.trustyai.explainability.model.domain import (
+    FeatureDomain,
+    EmptyFeatureDomain,
+)
 
 import pandas as pd
 import numpy as np
@@ -146,17 +149,29 @@ def domain_insertion(
 ):
     """Given a PredictionInput and a corresponding list of feature domains, where
     `len(feature_domains) == len(PredictionInput.getFeatures()`, return a PredictionInput
-    where the ith feature has the ith domain. If the ith domain is `None`, the feature
-    is constrained."""
-    assert len(undomained_input.getFeatures()) == len(feature_domains)
+    where the ith feature has the ith domain. If the ith domain is `None`, no new domain
+    information will be added to the feature, thus keeping previous domain information or
+    keeping it fixed if none has been supplied"""
+    assert len(undomained_input.getFeatures()) == len(
+        feature_domains
+    ), "input has {} features, but {} feature domains were passed".format(
+        len(undomained_input.getFeatures()), len(feature_domains)
+    )
 
     domained_features = []
     for i, f in enumerate(undomained_input.getFeatures()):
         if feature_domains[i] is None:
             domained_features.append(
-                Feature(f.getName(), f.getType(), f.getValue(), True, None)
+                Feature(f.getName(), f.getType(), f.getValue(), True, f.getDomain())
             )
         else:
+            if not isinstance(f.getDomain(), EmptyFeatureDomain):
+                warning_msg = (
+                    "The supplied feature domain at position {} is specifying a new "
+                    "domain to previously domain'ed {}, this will overwrite the "
+                    "previous domain with the new one.".format(i, f.toString())
+                )
+                warnings.warn(warning_msg)
             domained_features.append(
                 Feature(
                     f.getName(), f.getType(), f.getValue(), False, feature_domains[i]

tests/general/test_counterfactualexplainer.py

@@ -12,6 +12,8 @@
     output, Model, feature,
 )
 from trustyai.utils import TestModels
+from trustyai.model.domain import feature_domain
+from trustyai.utils.data_conversions import one_input_convert
 
 jrandom = Random()
 jrandom.setSeed(0)
@@ -140,3 +142,41 @@ def test_counterfactual_v2():
     result_output = model(explanation.proposed_features_dataframe)
     assert result_output < .01
     assert result_output > -.01
+
+
+def test_counterfactual_with_domain_argument():
+    """Test passing domains to counterfactuals"""
+    np.random.seed(0)
+    data = np.random.rand(1, 5)
+    model_weights = np.random.rand(5)
+    model = Model(lambda x: np.dot(x, model_weights))
+    explainer = CounterfactualExplainer(steps=10_000)
+    explanation = explainer.explain(
+        inputs=data,
+        goal=np.array([0]),
+        feature_domains=[feature_domain((-10, 10)) for _ in range(5)],
+        model=model)
+    result_output = model(explanation.proposed_features_dataframe)
+    assert result_output < .01
+    assert result_output > -.01
+
+
+def test_counterfactual_with_domain_argument_overwrite():
+    """Test that passing domains to counterfactuals with already-domained features throws
+     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)])
+    model_weights = np.random.rand(5)
+    model = Model(lambda x: np.dot(x, model_weights))
+    explainer = CounterfactualExplainer(steps=10_000)
+
+    with pytest.warns(UserWarning):
+        explainer.explain(
+            inputs=domained_inputs,
+            goal=np.array([0]),
+            feature_domains=[feature_domain((-10, 10)) for _ in range(5)],
+            model=model
+        )
+
+