diff --git a/README.md b/README.md index 462acdd..970256e 100644 --- a/README.md +++ b/README.md @@ -45,12 +45,13 @@ The mandatory dependencies of this library are: Optional dependencies are: +* matplotlib and [seaborn](https://seaborn.pydata.org/), for plotting functions * [mpmath](https://mpmath.org/), for *beta_ratio* and *beta_oddsratio* * [PyCryptodome](https://www.pycryptodome.org/), for *pickle_write_encrypted* and *pickle_read_encrypted* * [rpy2](https://rpy2.github.io/), with R packages: * [BFpack](https://cran.r-project.org/web/packages/BFpack/index.html), for *bayesfactor_afbf* (*RegressionResult.bayesfactor_beta_zero*) * [logistf](https://cran.r-project.org/web/packages/logistf/index.html), for *PenalisedLogit* -* matplotlib and [seaborn](https://seaborn.pydata.org/), for plotting functions +* [shap](https://shap.readthedocs.io/en/latest/), for *RegressionResult.shap* ## Functions diff --git a/docs/regress.rst b/docs/regress.rst index f5ab50e..3f70a78 100644 --- a/docs/regress.rst +++ b/docs/regress.rst @@ -30,6 +30,9 @@ Result classes .. autoclass:: yli.regress.RegressionResult :members: +.. autoclass:: yli.shap.ShapResult + :members: + Model terms ----------- diff --git a/yli/regress.py b/yli/regress.py index a259a36..0930922 100644 --- a/yli/regress.py +++ b/yli/regress.py @@ -464,7 +464,17 @@ class RegressionResult: ) def shap(self, **kwargs): - # TODO: Documentation + """ + Compute SHAP values for the model + + Uses the Python *shap* library. + + :param kwargs: Keyword arguments to pass to *shap.LinearExplainer* + + :rtype: :class:`yli.shap.ShapResult` + + **Reference:** Lundberg SM, Lee SI. A unified approach to interpreting model predictions. In: Guyon I, Von Luxburg U, Bengio S, et al., editors. *Advances in Neural Information Processing Systems*; 2017 Dec 4–9; Long Beach, CA. https://proceedings.neurips.cc/paper/2017/hash/8a20a8621978632d76c43dfd28b67767-Abstract.html + """ import shap diff --git a/yli/shap.py b/yli/shap.py index 96692ee..c59ba89 100644 --- a/yli/shap.py +++ b/yli/shap.py @@ -4,7 +4,11 @@ import patsy from .utils import as_numeric, check_nan, cols_for_formula, convert_pandas_nullable class ShapResult: - # TODO: Documentation + """ + SHAP values for a regression model + + See :meth:`yli.regress.RegressionResult.shap`. + """ def __init__(self, model, shap_values, features): self.model = model @@ -37,9 +41,23 @@ class ShapResult: return xdata def mean(self): + """ + Compute the mean absolute SHAP value for each parameter + + :rtype: Series + """ + return pd.Series(abs(self.shap_values).mean(axis=0), index=self.features) def plot(self, **kwargs): + """ + Generate a scatterplot of the SHAP values + + Uses the Python *matplotlib* library. + + :rtype: (Figure, Axes) + """ + import matplotlib.pyplot as plt import shap