API: factor out abstract base class ModelInspector from `LearnerIns…

…pector`, and introduce new `FunctionInspector` (#352)

* DOC: update installation instructions in README.rst

* BUILD: update code quality checker versions

* FIX: LearnerInspector.fit() argument is positional-only

* API: support new @fitted_only decorator introduced in pytools 2.1

* FIX: fix import statements for pytools.fit

* REFACTOR: separate ShapCalculator and LearnerShapCalculator

* REFACTOR: pull methods from LearnerInspector up to ModelInspector

* API: move SHAP calculators to packages .shap and .shap.learner

* API: rename facet.inspection.shap.learner to ….sklearndf

* API: add ShapCalculator.preprocess_features()

* API: push _calculate_shap() up to class ShapCalculator

* BUILD: require pytools~=2.1rc for mypy

* REFACTOR: pull up _convert_shap_tensors_to_list to ShapCalculator

* BUILD: require pytools >= 2.1rc

* REFACTOR: declare type aliases using TypeAlias

* DOC: add missing docstrings

* API: remove obsolete constants from ShapCalculator

* API: use generic type for arg model of ExplainerFactory.make_explainer()

* REFACTOR: replace T_LearnerDF with T_SupervisedLearnerDF in simulators

* API: remove dependence of ShapCalculator on class Sample

* API: implement new property output_names of class EstimatorDF

* FIX: restore support for sample weights in ShapGlobalExplainer

* REFACTOR: eliminate a redundant local variable

* API: require SupervisedLearnerPipelineDF for LearnerInspector

* BUILD: require sklearndf~=2.2.dev for mypy

* API: accept pandas series for arg X in fit, predict, …

* TEST: make OneHotEncoderDF sparse in simple_preproessor()

* IDE: use facet-base environment in all modules

* API: add _EstimatorPipelineDF.preprocess(); remove .feature_names_…

* API: adapt CandidateEstimatorDF for new ClassifierDF._get_classes()

* API: shift feature preprocessing from ShapCalculator to LearnerInspector

* API: pull _calculate_shap up to class ShapCalculator

* REFACTOR: change _get_shap(…) to _calculate_shap(…, _get_explainer(…))

* API: add method ShapCalculator.validate_features()

* API: add method ShapCalculator._reset_fit()

* API: remove ShapCalculator.features_

* API: remove ShapCalculator.get_feature_names()

* API: unify …output… methods to get_output_names()

* API: pull up get_shap…_values() and get_diagonals() to ShapCalculator

* API: change the ShapCalculator.get_… methods into properties

* API: eliminate classes Shap…ValuesCalculator

* API: eliminate classes (Classifier|Regressor)…ValuesCalculator

* API: support sklearn not sklearndf in shap calculators & expl. factory

* API: pull up LearnerInspector.fit() to ModelInspector

* API: rename ModelInspector.…names_ properties to …names, provide pre-fit

* API: remove obsolete Shap…Explainer classes

* API: rename _learner_inspector.py to _model_inspector.py

* API: move class LearnerInspector to new file _learner_inspector.py

* FIX: fix mypy checks

* FIX: make _get_classes() a method, not a property

* FIX: fix mypy checks

* BUILD: make conda environment creation more verbose

* BUILD: increase timeout for the pytest job

* BUILD: use more recent versions in environment.yml

* BUILD: update to latest conda before building the environment

* BUILD: use more specific versions in environment.yml

* BUILD: use more specific versions in environment.yml

* TEST: move from Boston to California dataset

* BUILD: downgrade scikit-learn to 1.1 to make unit tests work

* BUILD: remove debug logging from `conda env create`

* BUILD: don't update conda (not needed)

* BUILD: upgrade scikit-learn to 1.2

* API: only issue a warning if rv_frozen cannot be determined

* FIX: replace deprecated .iteritems() with .items()

* API: implement FunctionInspector; support exact & permutation explainers

* API: add full support for shap's old and new explainer APIs

* BULD: remove support for shap<0.36

* BULD: remove support for shap<0.39

* TEST: restore compatibility with min matrix test

* TEST: inline single use of function validate_linkage()

* FIX: remove contravariant from `T_Model` (#361)

* FIX: remove contravariant from T_Model

* REFACTOR: further simplify use of generic types in explainer factories

---------

Co-authored-by: j-ittner <ittner.jan@bcg.com>

* DOC: fix an outdated docstring

---------

Co-authored-by: Mateusz Sokół <mat646@gmail.com>
Co-authored-by: Mateusz Sokół <8431159+mtsokol@users.noreply.github.com>

README.rst

@@ -60,21 +60,37 @@ Installation
 ------------
 
 FACET supports both PyPI and Anaconda.
-
+We recommend to install FACET into a dedicated environment.
 
 Anaconda
 ~~~~~~~~
 
-.. code-block:: RST
+.. code-block:: sh
 
-    conda install gamma-facet -c bcg_gamma -c conda-forge
+    conda create -n facet
+    conda activate facet
+    conda install -c bcg_gamma -c conda-forge gamma-facet
 
 
 Pip
 ~~~
 
-.. code-block:: RST
+macOS and Linux:
+^^^^^^^^^^^^^^^^
+
+.. code-block:: sh
+
+    python -m venv facet
+    source facet/bin/activate
+    pip install gamma-facet
+
+Windows:
+^^^^^^^^
+
+.. code-block:: dosbatch
 
+    python -m venv facet
+    facet\Scripts\activate.bat
     pip install gamma-facet
 
 
@@ -163,7 +179,7 @@ hyperparameter configurations and even multiple learners with the `LearnerSelect
         cv=rkf_cv,
         n_jobs=-3,
         scoring="r2"
-    ).fit(sample=diabetes_sample)
+    ).fit(diabetes_sample)
 
     # get summary report
     selector.summary_report()
@@ -238,7 +254,7 @@ The key global metrics for each pair of features in a model are:
     inspector = LearnerInspector(
         pipeline=selector.best_estimator_,
         n_jobs=-3
-    ).fit(sample=diabetes_sample)
+    ).fit(diabetes_sample)
 
 **Synergy**
 

environment.yml

@@ -16,6 +16,7 @@ dependencies:
   - scipy             ~= 1.10
   - shap              ~= 0.41
   - sklearndf         >= 2.2rc, < 3a
+  - typing_extensions ~= 4.3
   # build/test
   - conda-build  ~= 3.23.3
   - conda-verify ~= 3.1.1

pyproject.toml

@@ -14,14 +14,15 @@ dist-name = "gamma-facet"
 license = "Apache Software License v2.0"
 
 requires = [
-    "gamma-pytools  >=2.1rc2,<3a",
-    "matplotlib     ~=3.0",
-    "numpy          >=1.21,<2a",  # cannot use ~= due to conda bug
-    "packaging      >=20",
-    "pandas         >=1.0",
-    "scipy          ~=1.2",
-    "shap           >=0.34,<0.42a",
-    "sklearndf      >=2.2rc,<3a",
+    "gamma-pytools     >=2.1rc2,<3a",
+    "matplotlib        ~=3.0",
+    "numpy             >=1.21,<2a",  # cannot use ~= due to conda bug
+    "packaging         >=20",
+    "pandas            >=1.0",
+    "scipy             ~=1.2",
+    "shap              >=0.39",
+    "sklearndf         >=2.2rc,<3a",
+    "typing_extensions ~=4.0",
 ]
 
 requires-python = ">=3.7,<4a"
@@ -71,49 +72,51 @@ no-binary.min = ["matplotlib", "shap"]
 
 [build.matrix.min]
 # direct requirements of gamma-facet
-gamma-pytools  = "~=2.1rc2"
-matplotlib     = "~=3.0.3"
-numpy          = "==1.21.6"  # cannot use ~= due to conda bug
-packaging      = "~=20.9"
-pandas         = "~=1.0.5"
-python         = ">=3.7.12,<3.8a"    # cannot use ~= due to conda bug
-scipy          = "~=1.4.1"
-shap           = "~=0.34.0"
-sklearndf      = "~=2.2rc"
+gamma-pytools     = "~=2.1rc2"
+matplotlib        = "~=3.0.3"
+numpy             = "==1.21.6"  # cannot use ~= due to conda bug
+packaging         = "~=20.9"
+pandas            = "~=1.0.5"
+python            = ">=3.7.12,<3.8a"    # cannot use ~= due to conda bug
+scipy             = "~=1.4.1"
+shap              = "~=0.39.0"
+sklearndf         = "~=2.2rc"
+typing_extensions = "~=4.0.0"
 # additional minimum requirements of sklearndf
-boruta         = "~=0.3.0"
-lightgbm       = "~=3.0.0"
+boruta            = "~=0.3.0"
+lightgbm          = "~=3.0.0"
 scikit-learn   = "~=0.24.2"
-xgboost        = "~=1.5"
+xgboost           = "~=1.5"
 # additional minimum requirements of gamma-pytools
-joblib         = "~=0.14.1"
-typing_inspect = "~=0.4.0"
+joblib            = "~=0.14.1"
+typing_inspect    = "~=0.4.0"
 # additional minimum requirements of shap
-ipython        = "==7.0"
-numba          = "~=0.55"  # required to support numpy 1.21
+ipython           = "==7.0"
+numba             = "~=0.55"  # required to support numpy 1.21
 
 [build.matrix.max]
 # direct requirements of gamma-facet
 gamma-pytools  = ">=2.1rc2,<3a"
 matplotlib     = "~=3.6"
 numpy          = ">=1.23,<2a"  # cannot use ~= due to conda bug
-packaging      = ">=20"
+packaging         = ">=20"
 pandas         = "~=2.0"
-python         = ">=3.9,<4a"   # cannot use ~= due to conda bug
+python            = ">=3.9,<4a"   # cannot use ~= due to conda bug
 scipy          = "~=1.10"
-shap           = "~=0.41"
-sklearndf      = ">=2.2rc,<3a"
+shap              = "~=0.41"
+sklearndf         = ">=2.2rc,<3a"
+typing_extensions = "~=4.3"
 # additional maximum requirements of sklearndf
-boruta         = "~=0.3"
-lightgbm       = "~=3.3"
-scikit-learn   = "~=1.1"
-xgboost        = "~=1.5"
+boruta            = "~=0.3"
+lightgbm          = "~=3.3"
+scikit-learn      = "~=1.1"
+xgboost           = "~=1.5"
 # additional maximum requirements of gamma-pytools
-joblib         = "~=1.1"
-typing_inspect = "~=0.7"
+joblib            = "~=1.1"
+typing_inspect    = "~=0.7"
 # additional maximum requirements of shap
-ipython        = ">=7"
-numba          = ">=0.55.2"  # required to support numpy 1.22
+ipython           = ">=7"
+numba             = ">=0.55.2"  # required to support numpy 1.22
 
 [tool.black]
 # quiet = "True"

sphinx/auxiliary/Diabetes_getting_started_example.ipynb

@@ -280,7 +280,7 @@
     "    cv=rkf_cv, \n",
     "    n_jobs=-3,\n",
     "    scoring=\"r2\"\n",
-    ").fit(sample=diabetes_sample)\n",
+    ").fit(diabetes_sample)\n",
     "\n",
     "# get summary report\n",
     "selector.summary_report()"
@@ -364,7 +364,7 @@
     "inspector = LearnerInspector(\n",
     "    pipeline=selector.best_estimator_,\n",
     "    n_jobs=-3\n",
-    ").fit(sample=diabetes_sample)"
+    ").fit(diabetes_sample)"
    ]
   },
   {

sphinx/source/tutorial/Classification_with_Facet.ipynb

@@ -1333,7 +1333,7 @@
     "    pipeline=clf_selector.best_estimator_,\n",
     "    n_jobs=-3,\n",
     "    verbose=False,\n",
-    ").fit(sample=prediab_initial_features)"
+    ").fit(prediab_initial_features)"
    ]
   },
   {
@@ -1909,7 +1909,7 @@
     "    pipeline=clf_selector.best_estimator_,\n",
     "    n_jobs=-3,\n",
     "    verbose=False,\n",
-    ").fit(sample=prediab_no_redundant_feat)"
+    ").fit(prediab_no_redundant_feat)"
    ]
   },
   {

src/facet/inspection/__init__.py

@@ -6,5 +6,7 @@
 of a learner pipeline which has been fitted using cross-validation.
 """
 from ._explainer import *
+from ._function_inspector import *
 from ._inspection import *
 from ._learner_inspector import *
+from ._model_inspector import *