{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"(ch3)=\n",
"# Gradient Descent: Part I"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"One cannot overstate the importance of 'Gradient descent' in the field of machine learning. It's an optimization technique that lies in the heart of machine learning algorithms ranging from regression to deep learning. This chapter aims to provide intuition behind the gradient descent algorithm and its variant. Similar to previous chapters, I work through examples and code to build a concrete understanding of the concept. \n",
"\n",
"## Finding Minimum Using Brute Force\n",
"Assume a two dimensional function $f(X)=x_0^2 + x_1^2$. Now let's assume we want to find the value of $X=(x_0, x_1)$ at which f(X) is minimum. The natural instinct would be to plot the function for some random range of X and observe the behavior of $f(X)$. Using plotly, below code snippet renders the above function. "
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"ExecuteTime": {
"end_time": "2020-05-19T23:26:32.026408Z",
"start_time": "2020-05-19T23:26:31.206213Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"
"
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"import random\n",
"import pandas as pd\n",
"import numpy as np\n",
"import math\n",
"from copy import copy\n",
"import itertools\n",
"\n",
"def func(x):\n",
" \"\"\"the function we are trying to minimize\"\"\"\n",
" return math.pow(x[0], 2) + math.pow(x[1],2)\n",
"\n",
"\n",
"def point_generator(choices, func):\n",
" \"\"\"Generates all possible combinations of X and returns X and f(x) values\"\"\"\n",
" \n",
" for pt in itertools.combinations(choices, 2):\n",
" pt = list(pt)\n",
" yield(pt + [func(pt)])\n",
" \n",
" pt.reverse()\n",
" yield(pt + [func(pt)])\n",
" \n",
" # generate diagonals\n",
" for x in choices:\n",
" pt = [x, x]\n",
" yield(pt + [func(pt)])\n",
" \n",
" \n",
"choices = np.array(range(-500, 500, 10))/10.\n",
"df = (\n",
" pd\n",
" .DataFrame(list(point_generator(choices, func)), columns=['x0', 'x1', 'fx'])\n",
")\n",
"display(df.head(4))\n",
"\n",
"from plotly.offline import download_plotlyjs, init_notebook_mode, iplot\n",
"import plotly.graph_objs as go\n",
"# init_notebook_mode(connected=False)\n",
"iplot([go.Scatter3d(x=df['x0'], y=df['x1'], z=df['fx'], opacity=0.5, mode='markers')], show_link=False)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"From the above plot, one can easily observe that $f(X)$ reaches a minimum value when $X = [0, 0]$ (i.e $x_1 = 0$ and $x_2 = 0$). \n",
"\n",
"As humans, we can do this naturally as long as we can visualize the function. However, a typical machine learning problem will involve hundreds of features. So let's think how did we so easily find the point X at which $f(X)$ is minimum. One possible explanation is that our eyes randomly picked a point on the above surface and followed in the direction where the slope is decreasing. Finally, when the slope starts increasing again, we know that we have crossed the minimum point. Let's try to transfer this idea into proper python code. The logical flow of the problem will be as follows:\n",
"\n",
"**Step 1:** Pick a random point $X = (x_0, x_1)$\n",
"\n",
"**Step 2:** Identify the next point $X'$ such as that $f(X') < f(X)$. However, one challenge is how do we find $X'$. Let's start with some brute force. Assume we look for neighboring points that are $\\eta$ distance away on a single dimension. For instance, as shown below figure (a), let's assume $X=[1,1]$ and $\\eta = 0.25$. Then, the neighboring points to explore are [1-0.25, 1], [1 + 0.25, 1], [1, 1-0.25], [1, 1 + 0.25]. Thus, if X is n-dimensional vector, then there will be $2^n$ neighbors to explore. If we relax the constraint that one can only move $\\eta$ distance along on one dimension at any given time, then we have additional four diagonal points as shown in the figure: [1-0.25, 1-0.25], [1+0.25, 1-0.25], [1-0.25, 1+0.25], [1+0.25, 1+0.25]. For n-dimensional space, then there will be $3^n$ neighboring points.\n",
"\n",
"\n",
"\n",
"Ignoring the scalability issue, let's assume we do use the above approach to generate possible neighboring candidates at which we need to evaluate $f(X)$.\n",
"\n",
"**Step 3:** Of all neighboring points at which $f(X') < f(X)$, pick the one with the maximum difference and set this new point around which we explore the space. \n",
"\n",
"**Step 4**: Repeat step 2 and 3 until one reaches the point where $f(X') > f(X)$ for all neighboring point. \n",
"\n",
"The python code below implements the above logic. It assumes $\\eta$ to be 0.03 "
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"ExecuteTime": {
"end_time": "2020-05-19T23:26:34.613123Z",
"start_time": "2020-05-19T23:26:34.535532Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"Optimal (0.00999999999696713, 0.00999999999696713)"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from collections import namedtuple\n",
"import math\n",
"from IPython.display import HTML\n",
"from itertools import product\n",
"import numpy as np\n",
"\n",
"# we will use Point class to store x and assocated y values\n",
"Point = namedtuple('Point', ['x', 'y'])\n",
"\n",
"\n",
"def func(x):\n",
" \"\"\"the function we are trying to minimize\"\"\"\n",
" return math.pow(x[0], 2) + math.pow(x[1],2)\n",
"\n",
"class Point(object):\n",
" \n",
" def __init__(self, X):\n",
" self._x = X\n",
" \n",
" @property\n",
" def x(self):\n",
" return self._x\n",
" \n",
" def neighbors(self, distance=0.25):\n",
" \"\"\"For a given point, generate all the neighbors \n",
" by walking delta distance along a single dimension only\n",
" \"\"\"\n",
" pts = [\n",
" np.array(self.x) - distance,\n",
" np.array(self.x) + distance\n",
" ]\n",
" return [Point(x2) for x2 in product(*np.transpose(pts).tolist())]\n",
" \n",
" def __repr__(self):\n",
" return str(self)\n",
" \n",
" def __str__(self):\n",
" return \"{}\".format(self.x)\n",
" \n",
" def __eq__(self, other):\n",
" return self.x == other.x\n",
" \n",
"\n",
"def minimize_v1(func, start_point, eta = 0.03, max_iterations = 1000, traceback = None):\n",
" \n",
" x1 = Point(start_point)\n",
" y1 = func(x1.x) \n",
" \n",
" for iter in range(max_iterations):\n",
" \n",
" if traceback:\n",
" traceback.append(x1.x)\n",
"\n",
"\n",
" # generate neighbors at distance of eta\n",
" neighbors = x1.neighbors(eta)\n",
" \n",
" # Identify next point where the f(x) is smallest\n",
" min_x = x1\n",
" min_y = y1 \n",
" \n",
" for x2 in neighbors: \n",
" y2 = func(x2.x)\n",
" if y2 < min_y:\n",
" min_x, min_y = x2, y2\n",
" \n",
" \n",
" # if x2 is same as x1 then we are at minimum\n",
" if x1 == min_x:\n",
" return x1.x\n",
" \n",
" x1, y1 = min_x, min_y\n",
" \n",
" # if we reached max iterations then return current point\n",
" return x1.x\n",
" \n",
"\n",
"minPt = minimize_v1(func, [100, 100], eta=0.03, max_iterations=5000)\n",
"display(HTML(\"Optimal {}\".format(minPt, iter)))\n"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"ExecuteTime": {
"end_time": "2020-05-19T23:26:39.780651Z",
"start_time": "2020-05-19T23:26:35.950925Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"47.1 ms ± 3.12 ms per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
]
}
],
"source": [
"%%timeit \n",
"minimize_v1(func, [100, 100], eta=0.03, max_iterations=5000)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Using Gradient Approach\n",
"Great, now we have a working function. But it's not scalable. If you have n-dimensional space, there are $3^n$ possible neighbors that we need to explore (this is assuming that we are taking $\\eta$ distance along each dimension). One way to solve the above scalability issue is use the concept of directional derivative and gradients. \n",
"\n",
"The main objective of step 2 is to find $X'$ for which $f(X')$ is smallest. This is exactly the kind of information that derivative provides. For instance, our function $f(X)=x_0^2 + x_1^2$ has two parameters: $x_0, x_1$. So partial derivative of our function $f(x)$, written as $\\Delta{f(X)}$ is given as:\n",
"\n",
"$$\\Delta{f(X)} = \\begin{bmatrix}\n",
"\\frac{\\partial{f}}{\\partial{x_0}}\\\\ \n",
"\\frac{\\partial{f}}{\\partial{x_1}}\n",
"\\end{bmatrix} = \\begin{bmatrix}\n",
"2x_0\\\\\n",
"2x_1\n",
"\\end{bmatrix}$$\n",
"\n",
"The partial derivative gives the direction of the steepest gradient. Since we are interested in minimization, we want to move opposite to the direction of the greatest gradient. Thus, rather than having to explore $3^n$ points, we can virtually find $X'$ using the below formula\n",
"\n",
"$$ X' = X - \\eta \\Delta{f(X)}$$\n",
"\n",
"\n",
"There are two things to note in the above equation:\n",
"\n",
"1. $\\Delta{f(X)}$ gives the direction of steepest gradient. Since we want to minimize, we want to go in the opposite direction of the steepest gradient and hence 'minus' sign. \n",
"2. $\\Delta{f(X)}$ is a unit vector. If we directly do $X - \\Delta{f(X)}$ then we are finding neighbors in the opposite direction of the steepest gradient that is at a distance of one unit from the current point X. A jump of one unit might be too much, and hence, we dampen it by multiplying by $\\eta$. Often **$\\eta$ is referred as the learning rate**.\n",
"\n",
"\n",
"Using the gradient approach, let's write the second version of the minimization method. Note that the `func` variable now doesn't refer to the original function ($x_0^2 + x_1^2$) but to it's derivative i.e. ($2x_0 + 2x1$).\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {
"ExecuteTime": {
"end_time": "2020-05-19T23:26:39.821255Z",
"start_time": "2020-05-19T23:26:39.782278Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"Optimal [4.35780706e-133 4.35780706e-133]"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from copy import copy\n",
"\n",
"def func_gradient(x):\n",
" assert len(x) == 2\n",
" return np.array([\n",
" 2. * x[0],\n",
" 2 * x[1]\n",
" ])\n",
"\n",
"\n",
"def minimize_v2(func, start_point, eta = 0.03, max_iterations = 1000, traceback = None):\n",
" \n",
" x1 = start_point\n",
" \n",
" for iter in range(max_iterations):\n",
" \n",
" if traceback is not None:\n",
" traceback.append(copy(x1))\n",
"\n",
" x1 -= eta * np.array(func(x1))\n",
" \n",
" # if we reached max iterations then return current point\n",
" return x1\n",
"\n",
"\n",
"\n",
"minPt = minimize_v2(func_gradient, [100, 100], eta=0.03, max_iterations=5000)\n",
"display(HTML(\"Optimal {}\".format(minPt, iter)))\n",
"\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {
"ExecuteTime": {
"end_time": "2019-12-06T15:34:23.743231Z",
"start_time": "2019-12-06T15:34:21.946313Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"18.8 ms ± 259 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)\n"
]
}
],
"source": [
"%%timeit \n",
"minPt = minimize_v2(func_gradient, [100, 100], eta=0.03, max_iterations=5000)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Stopping Criteria\n",
"\n",
"If you compare v1 and v2 implementation, you will notice that using the gradient approach significantly simplified our logic. But in theory, it should also make it much more scalable and faster. One crucial detail that I skipped and affects the performance of the gradient-based approach is **stopping criteria**. Currently, the only way `minimize_v2` can stop is when it reaches the maximum number of iterations. If you plot the traceback, as shown below, you will notice that the x2 doesn't change much after 500 iterations."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"ExecuteTime": {
"end_time": "2019-12-06T15:34:25.101324Z",
"start_time": "2019-12-06T15:34:25.067419Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Optimal point is [4.35780706e-133 4.35780706e-133]\n"
]
}
],
"source": [
"traceback = []\n",
"minPt = minimize_v2(func_gradient, [100, 100], eta=0.03, max_iterations=5000, traceback = traceback)\n",
"print (\"Optimal point is {}\".format(minPt))"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"ExecuteTime": {
"end_time": "2019-12-06T15:34:27.703432Z",
"start_time": "2019-12-06T15:34:25.641382Z"
}
},
"outputs": [
{
"data": {
"image/png": "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6623nvLn+Ku/+qscOnQohw4dys6dO4v6eHiX5l18SSqVSoZf2FV2FAAAAAAAYIYpvYR788038+CDD2bbtm3p6OjIZZddlptvvjn33HPPCefed9992bBhQz7+8Y+nra0tW7duzZNPPplXXnklSbJ9+/b09vZm8eLFWb58eb74xS+OX+fxxx9Po9HIl770pcydOzc33XRTVqxYkYcffjhJcu+992bTpk259NJLs2DBgmzdujXf+9730mg0kiR/8id/kj/+4z/O4sWLz9Enw3vVMmdO2lav9Vw4AAAAAADgnCu9hHvxxRfTbDazdu3a8dcuvfTS1Ov1E86t1+vp6ekZ/3rRokVZtmxZ6vV69u/fnz179hx3/J3Xqdfr6erqSktLyymPv/O9tVotx44dy0svvXTGP8s/+2f/LBdccEGuuuqq/M//+T/P+H1MnGqX58IBAAAAAADnXmvZAQ4dOpQFCxYc91pnZ2cOHjx40nMXLlx40nMPHTqUJMcdf+d1TvXeAwcOnPR4pVLJggULTprjZP7yL/8y69evT/LWXXUbNmzIwMBAPvShD532vQcOHMi+ffvO6Ptwdo59cHmO/nJPfvPKy5l13qKy4xRqdHQ0SdLaWvqvMdPE29vzQhHMKIpkPlE0M4oimVEUyXyiaGYURTKjKJL5dGpvdxZMD6XfCdfe3p6hoaHjXjtw4EA6OjrO6tz29vYkOe74O69zuu9zsuNDQ0MnzXEyH/vYx9LW1pa2trZ84QtfyGWXXZZHH330hPN27NiR6667Ltddd13uuOOOM7o2717L+96fls7OHH3+ubKjAAAAAAAAM0jp/23h4osvTqVSya5du7JmzZokybPPPptarXbCubVaLX19/2drwf3792dwcDC1Wi3nnXdeli5dmr6+vixduvSE69RqtXz961/P2NjY+JaUzz77bL7whS8cd+0bb7wxyVvbU86aNSurVq16Vz9XS0tLms3mCa9v3LgxGzduTJI888wzWb9+fRYuXJhFi6bXXVqTybHuy3Ls5y9n0T++ruwohfK/j5go5hFFMKOYCOYTRTGjmAhmFEUwn5goZhRFMKOYCObTiX53Rz+mttLvhJs/f34+/elPp7e3NwcPHkxfX1/uvffebNq06YRzb7rppjz66KN57LHHMjw8nM2bN+fKK6/MypUrkyQ333xztm3blr179+a1117L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AQAAAAAApohJUcK98cYb+cxnPpOOjo5ceOGFueuuu0557kMPPZSLLroo8+fPzzXXXJPdu3ePHzty5Eg+//nPp7OzMxdccEE2b9583Hvr9Xo++tGPplqtplar5Yknnjju+Le//e1ceOGF6ejoyA033JChoaHjjl1xxRWZO3duPvvZz56Q63TXZuqad/ElqbS0ZPj5XWVHAQAAAAAApohJUcLddtttGR0dzZ49e/LII4+kt7c3P/nJT0447/nnn8+mTZty9913Z+/evVm1alVuvPHG8eNbtmxJf39/Xn755Tz11FO5//77s3379iTJ0aNHc9111+X666/P/v378+Uvfzmf+tSnsn///iTJj3/843zta1/LD3/4w+zevTsjIyO5/fbbx6+9dOnSfOUrX8mtt956Qq7TXZuprWXOnLStXmNLSgAAAAAA4IyVXsK9+eabefDBB7Nt27Z0dHTksssuy80335x77rnnhHPvu+++bNiwIR//+MfT1taWrVu35sknn8wrr7ySJNm+fXt6e3uzePHiLF++PF/84hfHr/P444+n0WjkS1/6UubOnZubbropK1asyMMPP5wkuffee7Np06ZceumlWbBgQbZu3Zrvfe97aTQaSZI/+ZM/yR//8R9n8eLFJ+Q63bWZ+qq1njTq/WXHAAAAAAAApojSS7gXX3wxzWYza9euHX/t0ksvTb1eP+Hcer2enp6e8a8XLVqUZcuWpV6vZ//+/dmzZ89xx995nXq9nq6urrS0tJzy+DvfW6vVcuzYsbz00kun/RlOd22mvmpXT47+ck+O/nZv2VEAAAAAAIApoLXsAIcOHcqCBQuOe62zszMHDx486bkLFy486bmHDh1KkuOOv/M6p3rvgQMHTnq8UqlkwYIFJ81xprnevvbpHDhwIPv27TujcylHc+68tHR25jc/ezLzrvxY2XGSJKOjo0mS1tbSf42ZJmyhS5HMKIpkPlE0M4oimVEUyXyiaGYURTKjKJL5dGpn2iswNZQ+Mdvb2zM0NHTcawcOHEhHR8dZndve3p4kGRoaGv/zO69zuu9zsuNDQ0MnzfFefoYdO3Zkx44d4+cwNVQqlcxevTZHX9g1aUo4AAAAAABg8iq9hLv44otTqVSya9eurFmzJkny7LPPplarnXBurVZLX1/f+Nf79+/P4OBgarVazjvvvCxdujR9fX1ZunTpCdep1Wr5+te/nrGxsfFtI5999tl84QtfOO7aN954Y5K3tpicNWtWVq1addqf4XTXfqeNGzdm48aNSZJnnnkm69evz8KFC7No0aIz+8AozZz1H8mvt9+d8xYuTGXWrLLj+N9HTBjziCKYUUwE84mimFFMBDOKIphPTBQziiKYUUwE8+lEv7vrHlNb6c+Emz9/fj796U+nt7c3Bw8eTF9fX+69995s2rTphHNvuummPProo3nssccyPDyczZs358orr8zKlSuTJDfffHO2bduWvXv35rXXXss3v/nNfO5zn0uSXHXVVZk3b16+8Y1vZCeoumUAACAASURBVGRkJA888EBeffXVXH/99ePv3b59e/r7+3Pw4MH09vbmhhtuSLVaTfLWPzKHDx/O6OhoxsbGcvjw4Rw9evSMrs300LaulrHDwzn86stlRwEAAAAAACa50ku4JPnOd76TSqWSJUuWZMOGDdmyZUuuvvrqDA4Opr29PYODg0mSNWvW5Lvf/W5uueWWnH/++XnhhRfywAMPjF/nq1/9amq1WlauXJkrrrgiGzduHC/zZs+enR/84Ad56KGH0tnZmTvvvDPf//73x5v2T3ziE+nt7c21116bJUuWZPbs2fnWt741fu1t27alra0td955Zx588MG0tbXl1ltvPaNrMz3Mmt+euRd9OI16f9lRAAAAAACASa7SbDabZYeYqd7ejvLpp5/O5ZdfXnYczsBv/+rBNAb68sHN28qOYgsACrdv374ktgGgGGYURTKfKJoZRZHMKIpkPlE0M4oimVEUyXw6Nb3B9DIp7oSDqaLa1ZORn7+SY4cOlR0FAAAAAACYxJRwcBbmrViZlrZqhp+rlx0FAAAAAACYxJRwcBYqs2albW0tjXpf2VEAAAAAAIBJTAkHZ6na1ZNGvS8epwgAAAAAAJyKEg7OUrXWndF9+3J0z+6yowAAAAAAAJOUEg7O0uzzF2f2kqW2pAQAAAAAAE5JCQfvQrXWk8ZAf9kxAAAAAACASUoJB+9Ctas7wy88l7EjR8qOAgAAAAAATEJKOHgX2lavTZrJ4Rd3lR0FAAAAAACYhJRw8C60zJ2beasvsSUlAAAAAABwUko4eJeqte406n1lxwAAAAAAACYhJRy8S9VaT47s/kVG9+8rOwoAAAAAADDJKOHgXZrzgQ9mVud5adRtSQkAAAAAABxPCQfvUqVSeWtLygFbUgIAAAAAAMdTwsF7UK11p7FzIM2xsbKjAAAAAAAAk4gSDt6D6rqujDXezMhrr5YdBQAAAAAAmESUcPAezOpYkLnLV9iSEgAAAAAAOI4SDt6jaq0njXp/2TEAAAAAAIBJRAkH71G11p3Dr7yUY41G2VEAAAAAAIBJQgkH79G8latSmTM3w8/Vy44CAAAAAABMEko4eI8qra2prq3ZkhIAAAAAABinhIMCVGvdadT70mw2y44CAAAAAABMAko4KEC1qyeje3+To7/6ZdlRAAAAAACASUAJBwWYfcEfZPb73p/GgC0pAQAAAAAAJRwU5u0tKQEAAAAAAJRwUJBqrSfDu55L8+jRsqMAAAAAAAAlU8JBQdrWrEvz2GiGX3qh7CgAAAAAAEDJWssOQDI6OprR0dGyY/BetbZm3ocvzqH+ZzPn4ksm/NtZMxTt7TVlbVEE64gimU8UzVqiSGYURbKOKJoZRZGsI4pkPp2az2R6cSdcSXbs2JE77rij7BgUbN66rgzv7C87BgAAAAAAUDJ3wpVk48aNWb16ddavX5/W1ta0tvqrmA46ei7LGw//t+TQobR2dp6T72ntUJS315I1RZGsJ4pgPjFRrCmKYEYxEawnimJGMRGsJ4pgPp2az2R6cSccFGjOBz+UWQsWpuFuOAAAAAAAmNGUcFCgSktLquu60qgr4QAAAAAAYCZTwkHBql09Ga73pzk2VnYUAAAAAACgJEo4KFjbuq4cOziUkcHXy44CAAAAAACURAkHBWtd2Jk5y5anUe8rOwoAAAAAAFASJRxMgGqtO40BJRwAAAAAAMxUSjiYANWunhx++cWMDQ+XHQUAAAAAACiBEg4mQNuq1am0tmb4+Z1lRwEAAAAAAEqghIMJUGltTdsl69IY6C87CgAAAAAAUAIlHEyQald3GjuVcAAAAAAAMBMp4WCCVGs9Ofqrv8/RX/+q7CgAAAAAAMA5poSDCTL7fe9P6wV/kEa9r+woAAAAAADAOaaEgwlSqVRSrXV7LhwAAAAAAMxASjiYQNVadxq7dqY5Olp2FAAAAAAA4BxSwsEEaltTS/PISA6/8lLZUQAAAAAAgHNICQcTaFa1mnkfXpXGgOfCAQAAAADATKKEgwlWrfWkUfdcOAAAAAAAmEmUcDDBqrWejLz+8xwbGio7CgAAAAAAcI4o4WCCzV2+Ii3z29PY6W44AAAAAACYKZRwMMEqLS2pruuyJSUAAAAAAMwgSjg4B6q17jR2DqTZbJYdBQAAAAAAOAeUcHAOVGvdOfbG/hz5xWDZUQAAAAAAgHNACQfnQOt5izLnA8vSGLAlJQAAAAAAzARKODhHqrWuNOp9ZccAAAAAAADOASUcnCPVWk+GX3w+YyOHy44CAAAAAABMMCUcnCPzLr4klZaWDD+/q+woAAAAAADABJsUJdwbb7yRz3zmM+no6MiFF16Yu+6665TnPvTQQ7nooosyf/78XHPNNdm9e/f4sSNHjuTzn/98Ojs7c8EFF2Tz5s3Hvbder+ejH/1oqtVqarVannjiieOOf/vb386FF16Yjo6O3HDDDRkaGjrjjJVKJfPnz097e3va29uzYcOG9/KRMA21zJmTttVrbEkJAAAAAAAzwKQo4W677baMjo5mz549eeSRR9Lb25uf/OQnJ5z3/PPPZ9OmTbn77ruzd+/erFq1KjfeeOP48S1btqS/vz8vv/xynnrqqdx///3Zvn17kuTo0aO57rrrcv3112f//v358pe/nE996lPZv39/kuTHP/5xvva1r+WHP/xhdu/enZGRkdx+++1nlfHpp5/OoUOHcujQoTz66KMT8VExxVVrPWkM9JcdAwAAAAAAmGCll3BvvvlmHnzwwWzbti0dHR257LLLcvPNN+eee+454dz77rsvGzZsyMc//vG0tbVl69atefLJJ/PKK68kSbZv357e3t4sXrw4y5cvzxe/+MXx6zz++ONpNBr50pe+lLlz5+amm27KihUr8vDDDydJ7r333mzatCmXXnppFixYkK1bt+Z73/teGo3GWWWE36fa1ZOjf78nR/f+puwoAAAAAADABGotO8CLL76YZrOZtWvXjr926aWX5k//9E9POLder+cjH/nI+NeLFi3KsmXLUq/Xs2jRouzZsyc9PT3HXeftLSnr9Xq6urrS0tJy3PF6vT5+/JOf/OT4sVqtlmPHjuWll17K2NjYGWW8+uqrc+zYsVxxxRX5+te/nnXr1p3RZ3DgwIHs27fvjM5lamvOnZeWzvPym//3p5l35cfe07VGR0eTJK2tpf8aM028fWcwFMGMokjmE0UzoyiSGUWRzCeKZkZRJDOKIplPp3bgwIGyI1Cg0ifmoUOHsmDBguNe6+zszMGDB0967sKFC096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n6W5uTlHHHFEzjrrrFx11VX50z/901rHY4Rp2HdyRk3YOz0rlqdxnxfXOg4AAAAAAMPQO97xjpx77rm5/vrrc9555w28/q1vfSvVajXvfve78+///u95zWtekw984ANpbGzM//2//zfvfe97U61W8573vGeb9ebNm5fTTz895557burqdnwf2OrVqzNt2rScdtppaW5uzj333JOLL744GzduzIIFC7Y596//+q9z3HHH5Z//+Z+zbNmyLFiwIKNHj84nP/nJnX5Pf/EXf5GvfvWr+Zu/+Zu88pWvzJ133pmLLrooTU1N+cAHPvA8flq7TwlXkIceeijVajXTp08feO3www/PZz7zmWd974YNG7J27drBjMcIVPeyQ7L+jn9PT1dXraMwQnT3dCdJepvKNU7CSPDU31za2f9swe4wnyiaGUWRzCiKZD5RNDOKIplRFKm7pztpPbzWMYakDRs2vKCf19LSkre85S1ZunTpNiXc0qVL88Y3vjGTJk3KKaecMvB6tVrNa1/72vzmN7/JP/7jP25Xwp1wwgnPWJAlyRvf+Ma88Y1vHFjv6KOPTnd3d77whS9sV8IdfPDBWbx4cZLkTW96U7q7u/OZz3wmF110Ufbaa6/t1n7kkUfyhS98If/4j/+Y97///UmSY445Jl1dXfn4xz+e97///S/oHFPCFaSrqystLS3bvDZ+/Ph0dnZu89rSpUuzdOnSJC/8LxMjS8OsV6T3pm9l0/+7s9ZRGCn6tiZJNtXvmQ9JpVjVajVJUiqVapyEEcF8omBmFIUyoyiQ+UThzCgKZEZRqL6tycv2zGeEDUVz5szJSSedlFWrVmXKlCn57W9/mzvuuGOg/Fq3bl0uvvjifPe7383q1auzdeuT/33Ze++9t1vrLW95y7N+Xm9vb/7u7/4u1157bVatWpUtW7YMHOvq6kqlUhn4+sQTT9zmve94xzuyaNGi3HvvvXnta1+73do//OEPkyTvfOc7t9m28o1vfGP+/u//Pr/+9a+z//77P2vGoijhClKpVNLR0bHNaxs2bEhzc/M2r82ZMydz5sxJkixbtiyzZs0a2MsUdkffrD9JZv1J6uv9GlOMp+7INY8owlP/k2NGUQTziaKZURTJjKJI5hNFM6MokhlFkcynnRs3btwL/plve9vb0tzcnG9+85v5q7/6q1x33XUZPXp03v72tydJzjrrrNx5551ZsGBBDjvssLS0tOSLX/xirrvuuu3WetGLXvSsn3fRRRflK1/5Si6++OLMmjUr48ePz3e/+90sWrQovb2925Rwf7zeU18//vjjO1x7zZo1qVarmThx4g6PK+GGqUMOOSSlUin3339/Dj300CTJPffck9bW1honAwAAAAAA2LHGxsa8/e1vHyjhvvnNb+atb31rWlpa0tvbm1tuuSWf/vSnc/755w+856ktav/Yrtwte/3112fevHm56KKLBl675ZZbdnju7373ux1+ve++++7w/AkTJqRUKuUnP/lJRo8evd3xadNe2DswbeBbkLFjx+Zd73pX5s+fn87OzrS3t+fqq6/O3Llzax0NAAAAAABgp+bMmZOf/exn+d73vpf/+q//yqmnnpok2bRpU7Zu3bpNodXZ2ZmbbrrpOX9WT0/PNutt3bo13/zmN3d47re//e1tvr7xxhtTLpczY8aMHZ7/1LPmfv/73+eoo47a7p8/3r1wsLkTrkBXXHFFzjnnnOy7775paWnJwoUL84Y3vKHWsQAAAAAAAHbqmGOOyaRJk3L22WenpaVl4Nlu48aNy5/8yZ/kk5/8ZCZNmpT6+vp88pOfzLhx47a7S21XHXvssfnKV76S6dOnZ9KkSbniiiuyadOmHZ77yCOPZO7cuTnllFOybNmyfOpTn8oFF1yQvfbaa4fnH3LIIfngBz+YM844IxdeeGFe+cpXZsuWLXnooYdy22235Tvf+c5zyvxcPecS7he/+EXuuuuu/PrXv86ZZ56ZffbZJ48++mgmTZq0zX6de5Lx48fn+uuvr3UMAAAAAACAXVZfX593v/vdufLKK3PmmWemsbFx4NiSJUvy/ve/P2eeeWb23nvvfOhDH0pXV1cuv/zy5/RZn//85/OBD3wg559/fsrlcs4666yceOKJOeecc7Y799JLL83tt9+ed7/73Rk1alT+/M//PJdeeukzrv+5z30u06ZNy5e+9KUsXLgwY8eOzbRp03LSSSc9p7zPR6larVZ35w09PT2ZN29elixZkv7+/pRKpfz0pz/NkUcemXe+85152ctelk996lODlXdEWbZsWWbNmpW77747Rx55ZK3jMMx4GC5F80BcimRGUSTziaKZURTJjKJI5hNFM6MokhlFkcynndMbjCy7/Uy4Cy+8MN/73vfy7W9/Oxs2bMjTO7y3vvWt+bd/+7dCAwIAAAAAAMBws9t/beGf//mf86lPfSp/9md/lq1bt25z7IADDsjKlSuLygYAAAAAAADD0m7fCdfV1ZWXvOQlOzzW09OT3dzdEgAAAAAAAEac3b4TbsaMGbnxxhtz7LHHbnfsX//1XzNr1qxCggEAAAAAADB4WltbC1/ztNNOy8c+9rHC1x2OdruE+5u/+ZuceOKJ6e3tzbvf/e6USqXcfffduf766/PVr341//Iv/zIYOQEAAAAAACjQfffdl46OjkLXbGhoKHS94Wy3S7jjjz8+S5YsyYUXXph/+qd/SpLMmzcv++67b77+9a/nuOOOKzwkAAAAAAAADCe7XcIlycknn5yTTjop999/f9asWZMJEyZk+vTpqavb7UfMkeT++++vdQSGob6+viRJff1z+jWG7WzYsCFJMm7cuBonYSQwoyiS+UTRzCiKZEZRJPOJoplRFMmMokjm087pC0aWUrVardY6xJ5q1apVOfTQQ9Pd3V3rKAAAAAAAwBBQLpdz//33Z8qUKYP+WaVSaVC2o2xsbCx0zeFqt0u4T3ziE8+8YKnkgXu7YdWqVVmzZk2tYzBMffjDH84//MM/1DoGwA6ZUcBQZkYBQ5X5BAxlZhS8MCZOnPiCFHCJEm6w7XYJ19TUtN1rmzZtSvLkD3bUqFHu7IIXyNKlSzNnzpxaxwDYITMKGMrMKGCoMp+AocyMgpFHCTe4CtmOsqenJ9///vdz8cUX59prr81hhx1WRDYAAAAAAAAGyVAo4W677bYsXLgwy5YtS1NTU377298WmqeW6opYpKmpKSeccELOO++8zJs3r4glAQAAAAAAGOHGjh2bs88+O5/5zGdqHaVwhZRwT9l///3zs5/9rMglAQAAAAAAGMZWrlyZCRMm5Cc/+UmSZP369ZkyZUqWLl2aV7ziFTnjjDNy8MEH1zhl8eqLWujXv/51Lrvsshx00EFFLblHWLVqVdasWVPrGAAAAAAAwBAwceLETJky5QX5rF+ceXKeOP+cQtesvPFNefEZc7d57YADDsjnPve5nHHGGWlvb8+5556b1772tSP+OZO7XcLttddeKZVK27y2efPm9PT0pLGxMTfeeGNh4Ua6VatWZdq0aent7a11FAAAAAAAYAhobGzMgw8++IIVcS+U008/PbfeemuOPvrodHR0pL29vdaRBt1ul3Af/OAHtyvhGhsb85KXvCRvfetbM3HixMLCjXRr1qxRwAEAAAAAAAN6e3uzZs2aEVfCJcm8efPyute9LpdeemnGjRtX6ziDbrdLuEWLFg1GDgAAAAAAAF5AU//punR0dBS6ZkNDww5f7+3tzbnnnpv3vve9ufzyy3Paaadl//33L/Szh5rCngkHAAAAAAAAO/KRj3wkBx54YL761a9m0qRJOeOMM3L77bcnefKxZ5s3b07yZFlXKpUyZsyYGqYtxi6VcEceeeQuL1gqlXL33Xc/50AAAAAAAACMHLfeemu+9a1vDTwHbuHChXn1q1+dT33qU3n1q1+dP/3TPx04t6mpKfvvv39WrlxZo7TF2aUSbvr06ds9Bw4AAIBifOQjH8kZZ5yRAw44IBs2bMjXv/71LFiwIP39/bWOBgAA8LzNnj07jz/++MDXDQ0Nueuuuwa+rlartYg1vvm8OwAAIABJREFU6HaphPvGN74x2DkAAAD2WHV1dTn77LPT3t6eyZMn56abbkpHR0cuu+yyWkcDAADgOaqrdQAAAIA9wf7775/f//73ec1rXpMkGTduXH71q1/llFNOyWWXXZa77747fX19WbVqVa699tocffTRNU4MAADA87FLd8L9sWq1mjvuuCMPPfRQent7tzv+oQ996HkHAwAAGEl+9atf5UMf+lCuueaatLW15Ytf/GL+4z/+I9/85je3O/d1r3tdli9fXoOUAAAAFGW3S7gnnngib3jDG3L//fenVCoN7NP59GfGKeEAAAC2d+2112b27Nn5yU9+kpaWlrS1tW13znnnnZcZM2bkPe95Tw0SAgAAUJTd3o7yf//v/52WlpY8+uijqVarufPOO/Pwww/n4osvztSpU/PAAw8MRk4AAIAR4Utf+lJmzpyZL3/5y+no6Njm2GmnnZaPfexjOe6447J27doaJQQAAKAIu30n3B133JHPfvazeelLX5rkyQeIH3TQQVmwYEFKpVIuuOCC3HLLLYUHBQAAGO7GjBmTL37xi/nqV7+aj3zkI7n22muzatWqJMmcOXNy+eWX55hjjsmDDz5Y46QAAMCeYNmyZXn44YcLXXPSpEl5yUteUuiaw9Vul3Dr16/Pi170otTV1aWlpSW/+93vBo695jWvyWWXXVZoQAAAgJHi8ssvz6OPPppzzjkn//M//5Nrrrkmr3/963PyySfn//yf/5Pjjjsu9913X61jAgAAe4gjjjii1hFGtN3ejvLAAw/M448/niSZPn16rr322oFjN910U8aPH19cOgAAgBHizW9+c975znfm7LPPTpIsWLAg5XI5F110UT7xiU9k/Pjx+fGPf5zOzs50dnbmX//1X2ucGAAAgOejVK1Wq7vzhr/6q7/KmjVrctVVV+Xmm2/OiSeemIkTJ6ahoSGrV6/OJz7xiVx00UWDlXdEWbZsWWbNmlXrGAAAAAAAwBBy991358gjjxz0zymVSoWvef755+dzn/tc4esOR7u0HeXDDz+cl73sZUmyzXaTb3vb2/KTn/wkN954Y3p6enLsscfmz/7szwYnKQAAAAAAAIXq6OgodL2GhoZC1xvOdqmEO+SQQ/KKV7wip512Wk466aTss88+A8de+cpX5pWvfOWgBQQAAAAAAIDhZpeeCXfFFVdk9OjRueCCC/KSl7wkb3rTm3LNNdekq6trsPMBAAAAAADAsLNLJdy5556b//iP/8jKlSuzaNGiPPHEEznzzDOzzz775JRTTsm//Mu/pK+vb7CzAgAAAAAAwLCwSyXcU1760pfmoosuyj333JOf//zn+fCHP5y77rorJ5xwQvbZZ5/Mmzcvd9xxx2BlHXE2bdpU6wgAAAAAAMAQoz8YGUrVarX6fBf57//+73zlK1/J4sWLUyqV3BW3i5YtW5ZZs2blkksuyYEHHljrOAwzW7duTZKMGjWqxkkYKZ7aYrhSqdQ4CSOBGUWRzCeKZkZRJDOKIplPFM2MokhmFEUyn3bu0Ucfzfz583P33XfnyCOPHPTPK5VK6ejoKHTNhoaGNDY27vL5f//3f59rrrkmK1euzLhx4/Ke97wnCxcuHBHzpv75vLmvry//9m//lqVLl+a73/1uqtVqjjjiiKKy7THe8pa3vCC/TIwsT5Xd9fXP69cYBqxduzZJMmHChBonYSQwoyiS+UTRzCiKZEZRJPOJoplRFMmMokjm084tW7Ys8+fPr3WMF1R/f3+uuuqqtLW15bHHHsvxxx+flpaWXHTRRbWO9rzt1naUT7n99tszb968vPjFL87xxx+f//7v/85f/uVf5v77789dd91VdEYAAAAAAACGqZUrV2bChAn5yU9+kiRZv359pkyZkqVLl+aiiy7KUUcdlYaGhuy///457bTTBs4b7nb5ry3cfffdWbJkSa677ro8/vjjmTRpUk499dScdtppeeUrXzmYGQEAAAAAABimDjjggHzuc5/LGWeckfb29px77rl57Wtfmzlz5mx37h133JGZM2fWIGXxdqmEO+SQQ/LII49k7Nixefvb357TTjstxxxzzIjYjxMAAAAAAGBPdPK9v8g5v3qi0DXfNK6SuS998Xavn3766bn11ltz9NFHp6OjI+3t7dud8/nPfz733ntvvv71rxeaqVZ2qYR7+ctfnksuuSTHH398mpqaBjsTAAAAAAAAI8y8efPyute9LpdeemnGjRu3zbFvfOMb+bu/+7v86Ec/yt57712jhMXapRLupptuGuwcAAAAAAAAjFC9vb0599xz8973vjeXX355TjvttOy///5JkiVLluQjH/lIfvjDH+blL395jZMWZ5efCQcAAAAAAMDIcd2Mqeno6Ch0zYaGhh2+/pGPfCQHHnhgvvrVr2bSpEk544wzcvvtt+e6667LX/zFX+T73/9+WltbC81Sa3W1DgAAAAAAAMDIdeutt+Zb3/pWrrrqqiTJwoUL093dnU996lP567/+66xfvz7/63/9r1QqlVQqlcyePbvGiYvhTjgAAAAAAAAGzezZs/P4448PfN3Q0JC77rorSfKxj32sVrEGnTvhAAAAAAAAoGBKOAAAAAAAACiYEo4hp7e/P6t6N9U6BgAAAAAAwHM2JEq49evX56STTkpzc3P222+/XHnllTs994YbbshBBx2UsWPH5rjjjsvq1asHjm3evDnz5s3L+PHjM2nSpCxYsGCb965YsSKvetWrUi6X09ramh//+MfbHP/CF76Q/fbbL83NzTn55JPT0dGRJNm0aVPe97735cADD0xzc3MOO+ywXHvttbu1NrvuzvWd+eTKx1KtVmsdBQAAAAAA4DkZEiXceeedl76+vjz22GO5+eabM3/+/Nx2223bnffAAw9k7ty5+fKXv5w1a9Zk6tSpOfXUUweOL1y4MMuXL8/DDz+cn/70p7n22muzePHiJMmWLVty/PHH58QTT8y6devy0Y9+NCeccELWrVuXJPnBD36Qj3/847nllluyevXqbNq0Keeff36SpK+vL5MnT86///u/Z8OGDfnSl76UP//zP89//ud/7tLa7J6ZlXLW9m3NbzZtrnUUAAAAAACA56TmJdzGjRtz/fXXZ9GiRWlubs4RRxyRs846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\n",
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/plain": [
""
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# convert traceback into a data frame for plotting purpose\n",
"df = pd.DataFrame(traceback, columns=['x1', 'x2'])\n",
"df['iteration'] = list(range(1, df.shape[0]+1))\n",
"df = df.melt(id_vars='iteration', value_vars=['x1', 'x2'])\n",
"\n",
"from plotnine import *\n",
"%matplotlib inline\n",
"(\n",
" ggplot(df[df['iteration'] % 250 == 0], aes(x='iteration', y='value'))\n",
" + geom_line(aes(group='variable', color='variable'))\n",
" + facet_wrap(\"~variable\", nrow=2)\n",
" + xlab(\"Iteration Number\")\n",
" + ylab(\"Value\")\n",
" + theme_linedraw()\n",
" + theme(figure_size=(20, 8))\n",
")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Thus, one way to speed up things is to introduce a stopping criteria. Let's assume we stop as soon as the euclidean distance between x1 and x2 is less than some threshold, say 1e-6. Minimize V3 adds this stopping criteria. "
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"ExecuteTime": {
"end_time": "2019-12-06T15:34:27.724286Z",
"start_time": "2019-12-06T15:34:27.705328Z"
}
},
"outputs": [
{
"data": {
"text/html": [
"Optimal [1.09676626e-05 1.09676626e-05]"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/html": [
"Total Number of Iterations: 259"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"from copy import copy\n",
"from scipy.spatial import distance\n",
"\n",
"def func_gradient(x):\n",
" assert len(x) == 2\n",
" return np.array([\n",
" 2. * x[0],\n",
" 2 * x[1]\n",
" ])\n",
"\n",
"\n",
"def minimize_v3(func, start_point, eta = 0.03, max_iterations = 1000, traceback = None, stopping_threshold = 1.0e-6):\n",
" \n",
" x1 = start_point\n",
" \n",
" for iter in range(max_iterations):\n",
" \n",
" if traceback is not None:\n",
" traceback.append(copy(x1))\n",
"\n",
" x2 = x1 - eta * np.array(func(x1))\n",
" \n",
" # check if we reached stopping criteria threshold\n",
" if distance.euclidean(x2, x1) < stopping_threshold:\n",
" return x2\n",
" else:\n",
" x1 = x2\n",
" \n",
" # if we reached max iterations then return current point\n",
" return x1\n",
"\n",
"\n",
"traceback = []\n",
"minPt = minimize_v3(func_gradient, [100, 100], eta=0.03, max_iterations=5000, traceback=traceback, stopping_threshold=1.0e-6)\n",
"display(HTML(\"Optimal {}\".format(minPt, iter)))\n",
"display(HTML(\"Total Number of Iterations: {}\".format(len(traceback))))\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {
"ExecuteTime": {
"end_time": "2019-12-06T15:34:32.631899Z",
"start_time": "2019-12-06T15:34:28.423883Z"
}
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"3.88 ms ± 274 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)\n"
]
}
],
"source": [
"%%timeit \n",
"minPt = minimize_v3(func_gradient, [100, 100], eta=0.03, max_iterations=5000)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can notice above, we reached reasonably close to the optimal point (0, 0) in just 259 iterations, and the performance increased 5x. The mean time reduced from 23 ms to 5 ms in my runs.\n",
"\n",
"## More things to consider\n",
"Gradient descent algorithm is still an active area of research. There are many aspects of the algorithm that influences its performance both in terms of running time and accuracy. For instance, I didn't talk much about the impact of the learning rate on the performance and accuracy of the gradient descent approach. A small learning rate increases running time but improves accuracy and vice-versa. However, the learning rate doesn't have to be constant. There are many variants of the gradient descent algorithm where the learning rate is dynamically modified based on the number of iteration, steepness of the gradient, etc. Hence, I would recommend thinking about the following things:\n",
"\n",
"1. Different types of stopping criteria\n",
"2. Impact of learning rate on performance and accuracy. \n",
"3. How to make learning rate auto-adjust (search for 'Momentum' gradient descent)\n",
"4. Automatically deriving partial derivative of a given function (checkout 'autograd' library)\n",
"\n",
"In the next chapter, I will show this idea of gradient descent is used in linear regression.\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": []
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"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.7.6"
},
"toc": {
"base_numbering": 1,
"nav_menu": {},
"number_sections": true,
"sideBar": true,
"skip_h1_title": false,
"title_cell": "Table of Contents",
"title_sidebar": "Contents",
"toc_cell": false,
"toc_position": {
"height": "calc(100% - 180px)",
"left": "10px",
"top": "150px",
"width": "384px"
},
"toc_section_display": true,
"toc_window_display": true
},
"varInspector": {
"cols": {
"lenName": 16,
"lenType": 16,
"lenVar": 40
},
"kernels_config": {
"python": {
"delete_cmd_postfix": "",
"delete_cmd_prefix": "del ",
"library": "var_list.py",
"varRefreshCmd": "print(var_dic_list())"
},
"r": {
"delete_cmd_postfix": ") ",
"delete_cmd_prefix": "rm(",
"library": "var_list.r",
"varRefreshCmd": "cat(var_dic_list()) "
}
},
"types_to_exclude": [
"module",
"function",
"builtin_function_or_method",
"instance",
"_Feature"
],
"window_display": false
}
},
"nbformat": 4,
"nbformat_minor": 4
}