FAI-886: Unified input/output types, conversion functions, and docstrings (#116)

* unified input/output types, conversion functions, and docstrings

* fixed many-x conversions for 1d arrays, added more test cases

* fixing input -> output typo

* fixed randozm -> random typo

* added feature domains into data conversions

* fixed missing feature_domains != none check in many_inputs conversion

* linting

* Removed double simple pred import

Author: RobGeada

docs/api.rst

@@ -35,8 +35,6 @@ Data Objects
 .. autosummary::
 	:toctree: generated/
 
-	simple_prediction
-	counterfactual_prediction
 	Dataset
 
 Model Classes

src/trustyai/explainers/counterfactuals.py

@@ -1,11 +1,10 @@
 """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, List, Union
+from typing import Optional
 import matplotlib.pyplot as plt
 import matplotlib as mpl
 import pandas as pd
-import numpy as np
 import uuid as _uuid
 
 from trustyai import _default_initializer  # pylint: disable=unused-import
@@ -17,10 +16,17 @@
 
 from trustyai.model import (
     counterfactual_prediction,
-    Dataset,
     PredictionInput,
 )
 
+from trustyai.utils.data_conversions import (
+    prediction_object_to_numpy,
+    prediction_object_to_pandas,
+    OneInputUnionType,
+    OneOutputUnionType,
+    data_conversion_docstring,
+)
+
 from org.kie.trustyai.explainability.local.counterfactual import (
     CounterfactualExplainer as _CounterfactualExplainer,
     CounterfactualResult as _CounterfactualResult,
@@ -29,9 +35,6 @@
 )
 from org.kie.trustyai.explainability.model import (
     DataDistribution,
-    Feature,
-    Output,
-    PredictionOutput,
     PredictionProvider,
 )
 from org.optaplanner.core.config.solver.termination import TerminationConfig
@@ -57,7 +60,7 @@ def proposed_features_array(self):
         """Return the proposed feature values found from the counterfactual explanation
         as a Numpy array.
         """
-        return Dataset.prediction_object_to_numpy(
+        return prediction_object_to_numpy(
             [PredictionInput([entity.as_feature() for entity in self._result.entities])]
         )
 
@@ -66,7 +69,7 @@ def proposed_features_dataframe(self):
         """Return the proposed feature values found from the counterfactual explanation
         as a Pandas DataFrame.
         """
-        return Dataset.prediction_object_to_pandas(
+        return prediction_object_to_pandas(
             [PredictionInput([entity.as_feature() for entity in self._result.entities])]
         )
 
@@ -171,10 +174,11 @@ def __init__(self, steps=10_000):
         self._explainer = _CounterfactualExplainer(self._cf_config)
 
     # pylint: disable=too-many-arguments
+    @data_conversion_docstring("one_input", "one_output")
     def explain(
         self,
-        inputs: Union[np.ndarray, pd.DataFrame, List[Feature], PredictionInput],
-        goal: Union[np.ndarray, pd.DataFrame, List[Output], PredictionOutput],
+        inputs: OneInputUnionType,
+        goal: OneOutputUnionType,
         model: PredictionProvider,
         data_distribution: Optional[DataDistribution] = None,
         uuid: Optional[_uuid.UUID] = None,
@@ -185,27 +189,14 @@ def explain(
 
         Parameters
         ----------
-        inputs : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Feature`], or :class:`PredictionInput`
-            List of input features, as a:
-
-            * Numpy array of shape ``[1, n_features]``
-            * Pandas DataFrame with 1 row and ``n_features`` columns
-            * A List of TrustyAI :class:`Feature`, as created by the :func:`~feature` function
-            * A TrustyAI :class:`PredictionInput`
-
-        goal : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Output`], or :class:`PredictionOutput`
+        inputs : {}
+            List of input features, as a: {}
+        goal : {}
             The desired model outputs to be searched for in the counterfactual explanation.
-            These can take the form of a:
-
-            * Numpy array of shape ``[1, n_outputs]``
-            * Pandas DataFrame with 1 row and ``n_outputs`` columns
-            * A List of TrustyAI :class:`Output`, as created by the :func:`~output` function
-            * A TrustyAI :class:`PredictionOutput`
-
+            These can take the form of a: {}
         model : :obj:`~trustyai.model.PredictionProvider`
             The TrustyAI PredictionProvider, as generated by :class:`~trustyai.model.Model` or
              :class:`~trustyai.model.ArrowModel`.
-
         data_distribution : Optional[:class:`DataDistribution`]
             The :class:`DataDistribution` to use when sampling the inputs.
         uuid : Optional[:class:`_uuid.UUID`]

src/trustyai/explainers/lime.py

@@ -19,8 +19,14 @@
     output_html,
     feature_html,
 )
+
+from trustyai.utils.data_conversions import (
+    OneInputUnionType,
+    data_conversion_docstring,
+    OneOutputUnionType,
+)
 from .explanation_results import SaliencyResults
-from trustyai.model import simple_prediction, PredUnionType
+from trustyai.model import simple_prediction
 
 from org.kie.trustyai.explainability.local.lime import (
     LimeConfig as _LimeConfig,
@@ -230,6 +236,7 @@ def __init__(self, samples=10, **kwargs):
                 process.
             * trackCounterfactuals : bool
                 (default=False) Keep track of produced byproduct counterfactuals during LIME run.
+
         """
         self._jrandom = Random()
         self._jrandom.setSeed(kwargs.get("seed", 0))
@@ -250,30 +257,22 @@ def __init__(self, samples=10, **kwargs):
 
         self._explainer = _LimeExplainer(self._lime_config)
 
+    @data_conversion_docstring("one_input", "one_output")
     def explain(
-        self, inputs: PredUnionType, outputs: PredUnionType, model: PredictionProvider
+        self,
+        inputs: OneInputUnionType,
+        outputs: OneOutputUnionType,
+        model: PredictionProvider,
     ) -> LimeResults:
         """Produce a LIME explanation.
 
         Parameters
         ----------
-        inputs : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Feature`], or :class:`PredictionInput`
-            The input features to the model, as a:
-
-            * Numpy array of shape ``[1, n_features]``
-            * Pandas DataFrame with 1 row and ``n_features`` columns
-            * A List of TrustyAI :class:`Feature`, as created by the :func:`~feature` function
-            * A TrustyAI :class:`PredictionInput`
-
-        outputs : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Output`], or :class:`PredictionOutput`
+        inputs : {}
+            The input features to the model, as a: {}
+        outputs : {}
             The corresponding model outputs for the provided features, that is,
-            ``outputs = model(input_features)``. These can take the form of a:
-
-            * Numpy array of shape ``[1, n_outputs]``
-            * Pandas DataFrame with 1 row and ``n_outputs`` columns
-            * A List of TrustyAI :class:`Output`, as created by the :func:`~output` function
-            * A TrustyAI :class:`PredictionOutput`
-
+            ``outputs = model(input_features)``. These can take the form of a: {}
         model : :obj:`~trustyai.model.PredictionProvider`
             The TrustyAI PredictionProvider, as generated by :class:`~trustyai.model.Model`
             or :class:`~trustyai.model.ArrowModel`.

src/trustyai/explainers/shap.py

@@ -1,7 +1,7 @@
 """Explainers.shap module"""
 # pylint: disable = import-error, too-few-public-methods, wrong-import-order, line-too-long,
 # pylint: disable = unused-argument, consider-using-f-string, invalid-name
-from typing import Dict, Optional, List, Union
+from typing import Dict, Optional
 import matplotlib.pyplot as plt
 import matplotlib as mpl
 from bokeh.models import ColumnDataSource, HoverTool
@@ -21,13 +21,15 @@
     output_html,
     feature_html,
 )
-
 from trustyai.model import (
-    feature,
-    Dataset,
-    PredictionInput,
     simple_prediction,
-    PredUnionType,
+)
+from trustyai.utils.data_conversions import (
+    OneInputUnionType,
+    OneOutputUnionType,
+    ManyInputsUnionType,
+    many_inputs_convert,
+    data_conversion_docstring,
 )
 
 from org.kie.trustyai.explainability.local.shap import (
@@ -434,20 +436,19 @@ class SHAPExplainer:
     the outputs, as compared to the background inputs?*
     """
 
+    @data_conversion_docstring("many_inputs")
     def __init__(
         self,
-        background: Union[np.ndarray, pd.DataFrame, List[PredictionInput]],
+        background: ManyInputsUnionType,
         link_type: Optional[_ShapConfig.LinkType] = None,
         **kwargs,
     ):
         r"""Initialize the :class:`SHAPxplainer`.
 
         Parameters
         ----------
-        background : :class:`numpy.array`, :class:`Pandas.DataFrame`
-        or List[:class:`PredictionInput]
-            The set of background datapoints as an array, dataframe of shape
-            ``[n_datapoints, n_features]``, or list of TrustyAI PredictionInputs.
+        background : {}
+            The set of background datapoints as a: {}
         link_type : :obj:`~_ShapConfig.LinkType`
             A choice of either ``trustyai.explainers._ShapConfig.LinkType.IDENTITY``
             or ``trustyai.explainers._ShapConfig.LinkType.LOGIT``. If the model output is a
@@ -464,10 +465,11 @@ def __init__(
                 (default=20) The number of batches passed to the PredictionProvider at once.
                 When uusing :class:`~Model` with `arrow=False` this parameter has no effect.
                 If `arrow=True`, `batch_sizes` of around
-                :math:`\frac{2000}{\mathtt{len(background)}}` can produce significant
+                :math:`\frac{{2000}}{{\mathtt{{len(background)}}}}` can produce significant
                 performance gains.
             * trackCounterfactuals : bool
                 (default=False) Keep track of produced byproduct counterfactuals during SHAP run.
+
         Returns
         -------
         :class:`~SHAPResults`
@@ -477,19 +479,9 @@ def __init__(
             link_type = _ShapConfig.LinkType.IDENTITY
         self._jrandom = Random()
         self._jrandom.setSeed(kwargs.get("seed", 0))
+        self.background = many_inputs_convert(background)
         perturbation_context = PerturbationContext(self._jrandom, 0)
 
-        if isinstance(background, np.ndarray):
-            self.background = Dataset.numpy_to_prediction_object(background, feature)
-        elif isinstance(background, pd.DataFrame):
-            self.background = Dataset.df_to_prediction_object(background, feature)
-        elif isinstance(background[0], PredictionInput):
-            self.background = background
-        else:
-            raise AttributeError(
-                "Unsupported background type: {}".format(type(background))
-            )
-
         self._configbuilder = (
             _ShapConfig.builder()
             .withLink(link_type)
@@ -503,32 +495,22 @@ def __init__(
         self._config = self._configbuilder.build()
         self._explainer = _ShapKernelExplainer(self._config)
 
+    @data_conversion_docstring("one_input", "one_output")
     def explain(
-        self, inputs: PredUnionType, outputs: PredUnionType, model: PredictionProvider
+        self,
+        inputs: OneInputUnionType,
+        outputs: OneOutputUnionType,
+        model: PredictionProvider,
     ) -> SHAPResults:
         """Produce a SHAP explanation.
 
         Parameters
         ----------
-        inputs : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Feature`], or :class:`PredictionInput`
-            The input features to the model, as a:
-
-            * Numpy array of shape ``[1, n_features]``
-            * Pandas DataFrame with 1 row and ``n_features`` columns
-            * A List of TrustyAI :class:`Feature`, as created by the :func:`~feature` function
-            * A TrustyAI :class:`PredictionInput`
-
-        outputs : :class:`numpy.ndarray`, :class:`pandas.DataFrame`, List[:class:`Output`], or :class:`PredictionOutput`
+        inputs : {}
+            The input features to the model, as a: {}
+        outputs : {}
             The corresponding model outputs for the provided features, that is,
-            ``outputs = model(input_features)``. These can take the form of a:
-
-            * Numpy array of shape ``[1, n_outputs]``
-            * Pandas DataFrame with 1 row and ``n_outputs`` columns
-            * A List of TrustyAI :class:`Output`, as created by the :func:`~output` function
-            * A TrustyAI :class:`PredictionOutput`
-        model : :obj:`~trustyai.model.PredictionProvider`
-            The TrustyAI PredictionProvider, as generated by :class:`~trustyai.model.Model` or
-            :class:`~trustyai.model.ArrowModel`.
+            ``outputs = model(input_features)``. These can take the form of a: {}
 
         Returns
         -------