Add documentation for SHAP

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
 

docs/regress.rst

@@ -30,6 +30,9 @@ Result classes
 .. autoclass:: yli.regress.RegressionResult
 	:members:
 
+.. autoclass:: yli.shap.ShapResult
+	:members:
+
 Model terms
 -----------
 

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
 		

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