Add optional dependency management

.github/workflows/ci.yml

@@ -54,7 +54,7 @@ jobs:
           if [ "$RUNNER_OS" != "Windows" ] && [ ${{ matrix.python }} < '3.10' ]; then  # Skip Prophet tests on Windows as installation complex. Skip on Python 3.10 as not supported.
             python -m pip install --upgrade --upgrade-strategy eager -e .[prophet]
           fi
-          python -m pip install --upgrade --upgrade-strategy eager -e .[torch]
+          python -m pip install --upgrade --upgrade-strategy eager -e .[tensorflow,torch]
           python -m pip freeze
 
       - name: Lint with flake8

CONTRIBUTING.md

@@ -45,3 +45,63 @@ the docs will be built under `doc/_build/html`.
 
 ## CI
 All PRs triger a Github Actions  build to run linting, type checking, tests, and build docs.
+
+## Optional Dependencies
+
+Alibi-detect uses optional dependencies to allow users to avoid installing large or challenging to install dependencies. 
+Alibi-detect manages modularity of components that depend on optional dependencies using the `import_optional` function 
+defined in `alibi_detect/utils/missing_optional_dependency.py`. This replaces the dependency with a dummy object that 
+raises an error when called. If you are working on public functionality that is dependent on an optional dependency you 
+should expose the functionality via the relevant `__init__.py` file by importing it there using the `optional_import` 
+function. Currently, optional dependencies are tested by importing all the public functionality and checking that the 
+correct errors are raised dependent on the environment. Developers can run these tests using `tox`. These tests are in 
+`alibi_detect/tests/test_dep_mangement.py`. If implementing functionality that is dependent on a new optional dependency
+then you will need to:
+
+1. Add it to `extras_require` in `setup.py`.
+2. Create a new `tox` environment in `setup.cfg` with the new dependency.
+3. Add a new dependency mapping to `ERROR_TYPES` in `alibi_detect/utils/missing_optional_dependency.py`. 
+4. Make sure any public functionality is protected by the `import_optional` function.
+5. Make sure the new dependency is tested in `alibi_detect/tests/test_dep_mangement.py`.
+
+Note that subcomponents can be dependent on optional dependencies too. In this case the user should be able to import 
+and use the relevant parent component. The user should only get an error message if: 
+1. They don't have the optional dependency installed and,
+2. They configure the parent component in such as way that it uses the subcomponent functionality.
+
+Developers should implement this by importing the subcomponent into the source code defining the parent component using 
+the `optional_import` function. The general layout of a subpackage with optional dependencies should look like: 
+
+```
+alibi_detect/subpackage/
+  __init__.py  # expose public API with optional import guards
+  defaults.py  # private implementations requiring only core deps
+  optional_dep.py # private implementations requiring an optional dependency (or several?)
+```
+
+any public functionality that is dependent on an optional dependency should be imported into `__init__.py` using the 
+`import_optional` function. 
+
+#### Note:
+- The `import_optional` function returns an instance of a class and if this is passed to type-checking constructs, such 
+as Union, it will raise errors. Thus, in order to do type-checking, we need to 1. Conditionally import the true object 
+dependent on `TYPE_CHECKING` and 2. Use forward referencing when passing to typing constructs such as `Union`. We use 
+forward referencing because in a user environment the optional dependency may not be installed in which case it'll be 
+replaced with an instance of the MissingDependency class. For example: 
+  ```py
+  from typing import TYPE_CHECKING, Union
+
+  if TYPE_CHECKING:
+    # Import for type checking. This will be type `UsefulClass`. Note import is from implementation file.
+    from alibi_detect.utils.useful_classes import UsefulClass
+  else:
+    # Import is from `__init__` public API file. Class will be protected by optional_import function and so this will 
+    # be type any.
+    from alibi.utils import UsefulClass
+
+  # The following will not throw an error because of the forward reference but mypy will still work.
+  def example_function(useful_class: Union['UsefulClass', str]) -> None:
+    ...
+  ```
+- Developers can use `make repl tox-env=<tox-env-name>` to run a python REPL with the specified optional dependency 
+installed. This is to allow manual testing.

Makefile

@@ -60,4 +60,7 @@ licenses:
 check_licenses:
 	git --no-pager diff --exit-code ./licenses/license_info.no_versions.csv
 
-
+.PHONY: repl
+tox-env=default
+repl:
+	env COMMAND="python" tox -e $(tox-env)

README.md

@@ -117,7 +117,7 @@ We will use the [VAE outlier detector](https://docs.seldon.io/projects/alibi-det
 
 ```python
 from alibi_detect.od import OutlierVAE
-from alibi_detect.utils import save_detector, load_detector
+from alibi_detect.utils.saving import save_detector, load_detector
 
 # initialize and fit detector
 od = OutlierVAE(threshold=0.1, encoder_net=encoder_net, decoder_net=decoder_net, latent_dim=1024)

alibi_detect/ad/__init__.py

@@ -1,5 +1,7 @@
-from .adversarialae import AdversarialAE
-from .model_distillation import ModelDistillation
+from alibi_detect.utils.missing_optional_dependency import import_optional
+
+AdversarialAE = import_optional('alibi_detect.ad.adversarialae', names=['AdversarialAE'])
+ModelDistillation = import_optional('alibi_detect.ad.model_distillation', names=['ModelDistillation'])
 
 __all__ = [
     "AdversarialAE",

alibi_detect/cd/classifier.py

@@ -1,11 +1,12 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, has_sklearn
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, \
+    BackendValidator
 from alibi_detect.base import DriftConfigMixin
 
-if has_sklearn:
-    from sklearn.base import ClassifierMixin
-    from alibi_detect.cd.sklearn.classifier import ClassifierDriftSklearn
+
+from sklearn.base import ClassifierMixin
+from alibi_detect.cd.sklearn.classifier import ClassifierDriftSklearn
 
 if has_pytorch:
     from torch.utils.data import DataLoader
@@ -147,12 +148,12 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if (backend == 'tensorflow' and not has_tensorflow) or (backend == 'pytorch' and not has_pytorch) or \
-                (backend == 'sklearn' and not has_sklearn):
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'ClassifierDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch', 'sklearn']:
-            raise NotImplementedError(f"{backend} not implemented. Use 'tensorflow', 'pytorch' or 'sklearn' instead.")
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch'],
+                             'sklearn': ['sklearn']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['model']]

alibi_detect/cd/context_aware.py

@@ -1,7 +1,7 @@
 import logging
 import numpy as np
 from typing import Callable, Dict, Optional, Union, Tuple
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -92,11 +92,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'ContextMMMDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['c_ref']]

alibi_detect/cd/learned_kernel.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -121,11 +121,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'LearnedKernel detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['kernel']]

alibi_detect/cd/lsdd.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union, Tuple
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -81,11 +81,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'LSDDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref']]

alibi_detect/cd/lsdd_online.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Any, Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.base import DriftConfigMixin
 if has_pytorch:
     from alibi_detect.cd.pytorch.lsdd_online import LSDDDriftOnlineTorch
@@ -82,11 +82,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'MMDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['ert'], kwargs['window_size']]

alibi_detect/cd/mmd.py

@@ -1,7 +1,7 @@
 import logging
 import numpy as np
 from typing import Callable, Dict, Optional, Union, Tuple
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.utils.warnings import deprecated_alias
 from alibi_detect.base import DriftConfigMixin
 
@@ -80,11 +80,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'MMDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref']]

alibi_detect/cd/mmd_online.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Any, Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.base import DriftConfigMixin
 
 if has_pytorch:
@@ -75,11 +75,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'MMDDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
 
         kwargs = locals()
         args = [kwargs['x_ref'], kwargs['ert'], kwargs['window_size']]

alibi_detect/cd/model_uncertainty.py

@@ -6,7 +6,7 @@
 from alibi_detect.cd.chisquare import ChiSquareDrift
 from alibi_detect.cd.preprocess import classifier_uncertainty, regressor_uncertainty
 from alibi_detect.cd.utils import encompass_batching, encompass_shuffling_and_batch_filling
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import BackendValidator
 from alibi_detect.base import DriftConfigMixin
 
 logger = logging.getLogger(__name__)
@@ -83,9 +83,12 @@ def __init__(
         # Set config
         self._set_config(locals())
 
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'ClassifierUncertaintyDrift detector with {backend} backend.')
+        if backend:
+            backend = backend.lower()
+        BackendValidator(backend_options={'tensorflow': ['tensorflow'],
+                                          'pytorch': ['pytorch'],
+                                          None: []},
+                         construct_name=self.__class__.__name__).verify_backend(backend)
 
         if backend is None:
             if device not in [None, 'cpu']:
@@ -233,9 +236,12 @@ def __init__(
         # Set config
         self._set_config(locals())
 
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'RegressorUncertaintyDrift detector with {backend} backend.')
+        if backend:
+            backend = backend.lower()
+        BackendValidator(backend_options={'tensorflow': ['tensorflow'],
+                                          'pytorch': ['pytorch'],
+                                          None: []},
+                         construct_name=self.__class__.__name__).verify_backend(backend)
 
         if backend is None:
             model_fn = model

alibi_detect/cd/pytorch/__init__.py

@@ -1,4 +1,8 @@
-from .preprocess import HiddenOutput, preprocess_drift
+from alibi_detect.utils.missing_optional_dependency import import_optional
+
+HiddenOutput, preprocess_drift = import_optional(
+    'alibi_detect.cd.pytorch.preprocess',
+    names=['HiddenOutput', 'preprocess_drift'])
 
 __all__ = [
     "HiddenOutput",

alibi_detect/cd/pytorch/context_aware.py

@@ -274,5 +274,5 @@ def _sigma_median_diag(x: torch.Tensor, y: torch.Tensor, dist: torch.Tensor) ->
     The computed bandwidth, `sigma`.
     """
     n_median = np.prod(dist.shape) // 2
-    sigma = (.5 * dist.flatten().sort().values[n_median].unsqueeze(dim=-1)) ** .5
+    sigma = (.5 * dist.flatten().sort().values[int(n_median)].unsqueeze(dim=-1)) ** .5
     return sigma

alibi_detect/cd/spot_the_diff.py

@@ -1,6 +1,6 @@
 import numpy as np
 from typing import Callable, Dict, Optional, Union
-from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow
+from alibi_detect.utils.frameworks import has_pytorch, has_tensorflow, BackendValidator
 from alibi_detect.base import DriftConfigMixin
 
 if has_pytorch:
@@ -126,12 +126,11 @@ def __init__(
         self._set_config(locals())
 
         backend = backend.lower()
-        if backend == 'tensorflow' and not has_tensorflow or backend == 'pytorch' and not has_pytorch:
-            raise ImportError(f'{backend} not installed. Cannot initialize and run the '
-                              f'SpotTheDiffDrift detector with {backend} backend.')
-        elif backend not in ['tensorflow', 'pytorch']:
-            raise NotImplementedError(f'{backend} not implemented. Use tensorflow or pytorch instead.')
-
+        BackendValidator(
+            backend_options={'tensorflow': ['tensorflow'],
+                             'pytorch': ['pytorch']},
+            construct_name=self.__class__.__name__
+        ).verify_backend(backend)
         kwargs = locals()
         args = [kwargs['x_ref']]
         pop_kwargs = ['self', 'x_ref',  'backend', '__class__']

alibi_detect/cd/tensorflow/__init__.py

@@ -1,4 +1,9 @@
-from .preprocess import HiddenOutput, UAE, preprocess_drift
+from alibi_detect.utils.missing_optional_dependency import import_optional
+
+HiddenOutput, UAE, preprocess_drift = import_optional(
+    'alibi_detect.cd.tensorflow.preprocess',
+    names=['HiddenOutput', 'UAE', 'preprocess_drift']
+)
 
 __all__ = [
     "HiddenOutput",

alibi_detect/datasets.py

@@ -9,7 +9,7 @@
 import pandas as pd
 import requests
 from alibi_detect.utils.data import Bunch
-from alibi_detect.utils.fetching import _join_url
+from alibi_detect.utils.url import _join_url
 from requests import RequestException
 from scipy.io import arff
 from sklearn.datasets import fetch_kddcup99