chore: import upstream snapshot with attribution

notebooks/api_examples/migrating-to-new-api.ipynb

@@ -0,0 +1,163 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Migrating to the new \"Explanation\" API\n",
+    "\n",
+    "This notebook demonstrates some of the changes to the shap API that were introduced in shap `v0.36.0`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# An example dataset and model\n",
+    "import xgboost\n",
+    "\n",
+    "import shap\n",
+    "\n",
+    "X, y = shap.datasets.adult(n_points=100)\n",
+    "model = xgboost.XGBClassifier().fit(X, y)\n",
+    "explainer = shap.TreeExplainer(model, X)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To summarise the main change in the API:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "shap_values = explainer.shap_values(X)  # Old style\n",
+    "explanation = explainer(X)  # New style"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Calculating explanations\n",
+    "\n",
+    "### Old style\n",
+    "\n",
+    "In versions of shap before `v0.36.0`, explanations are represented as simple numpy arrays and calculated using the `.shap_values()` method of an explainer:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "array([[-0.54854601,  0.01639348, -0.46476041,  0.85896822, -1.36168788,\n",
+       "        -0.64692199,  0.0254638 , -0.58422904, -0.02344483,  0.        ,\n",
+       "         0.1224989 ,  0.01079906],\n",
+       "       [-0.83802091,  0.01562196,  0.78349799, -1.10456323, -0.68524691,\n",
+       "        -0.84828204,  0.03734176, -0.86151311, -0.02564897,  0.        ,\n",
+       "        -0.56183428,  0.00415988]])"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "shap_values = explainer.shap_values(X)\n",
+    "shap_values[:2]  # a numpy array"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Similarly, legacy plotting functions like `shap.summary_plot` expected the `shap_values` as a numpy array."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### New style\n",
+    "\n",
+    "As of shap `v0.36.0`, explanations are now represented with the `Explanation` object, and are created by calling the explainer directly as a function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       ".values =\n",
+       "array([[-0.54854601,  0.01639348, -0.46476041,  0.85896822, -1.36168788,\n",
+       "        -0.64692199,  0.0254638 , -0.58422904, -0.02344483,  0.        ,\n",
+       "         0.1224989 ,  0.01079906],\n",
+       "       [-0.83802091,  0.01562196,  0.78349799, -1.10456323, -0.68524691,\n",
+       "        -0.84828204,  0.03734176, -0.86151311, -0.02564897,  0.        ,\n",
+       "        -0.56183428,  0.00415988]])\n",
+       "\n",
+       ".base_values =\n",
+       "array([-2.70354599, -2.70354599])\n",
+       "\n",
+       ".data =\n",
+       "array([[27.,  4., 10.,  0.,  1.,  1.,  4.,  0.,  0.,  0., 44., 39.],\n",
+       "       [27.,  4., 13.,  4., 10.,  0.,  4.,  0.,  0.,  0., 40., 39.]])"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "explanation = explainer(X)\n",
+    "explanation[:2]  # a shap.Explanation object"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `shap.Explanation` object is a much richer representation that includes the shap values (accessible with the `.values` attribute) as well as supporting contextual information such as the background dataset and the feature names.\n",
+    "\n",
+    "The new-style plotting functions like `shap.plot.bar` and `shap.plots.beeswarm` accept these `Explanation` objections rather than numpy arrays."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "shap",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}