{
"cells": [
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"tags": [
"remove-cell"
]
},
"outputs": [],
"source": [
"%matplotlib inline\n",
"import matplotlib.pyplot as plt\n",
"plt.style.use('seaborn-whitegrid')\n",
"import pandas as pd\n",
"import numpy as np\n",
"from collections import defaultdict\n",
"\n",
"# Some useful utilities\n",
"\n",
"def laplace_mech(v, sensitivity, epsilon):\n",
" return v + np.random.laplace(loc=0, scale=sensitivity / epsilon)\n",
"\n",
"def gaussian_mech(v, sensitivity, epsilon, delta):\n",
" return v + np.random.normal(loc=0, scale=sensitivity * np.sqrt(2*np.log(1.25/delta)) / epsilon)\n",
"\n",
"def gaussian_mech_vec(v, sensitivity, epsilon, delta):\n",
" return v + np.random.normal(loc=0, scale=sensitivity * np.sqrt(2*np.log(1.25/delta)) / epsilon, size=len(v))\n",
"\n",
"def pct_error(orig, priv):\n",
" return np.abs(orig - priv)/orig * 100.0\n",
"\n",
"def z_clip(xs, b):\n",
" return [min(x, b) for x in xs]\n",
"\n",
"def g_clip(v):\n",
" n = np.linalg.norm(v, ord=2)\n",
" if n > 1:\n",
" return v / n\n",
" else:\n",
" return v"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Machine Learning\n",
"\n",
"```{admonition} Learning Objectives\n",
"After reading this chapter, you will be able to:\n",
"- Describe and implement the basic algorithm for gradient descent\n",
"- Use the Gaussian mechanism to implement differentially private gradient descent\n",
"- Clip gradients to enforce differential privacy for arbitrary loss functions\n",
"- Describe the effect of noise on the training process\n",
"```\n",
"\n",
"In this chapter, we're going to explore building differentially private machine learning classifiers. We'll focus on a kind of *supervised learning* problem: given a set of *labeled training examples* $\\{(x_1, y_1), \\dots, (x_n, y_n)\\}$, in which $x_i$ is called the *feature vector* and $y_i$ is called the *label*, train a *model* $\\theta$ which can *predict* the label for a new feature vector which was not present in the training set. Each $x_i$ is typically a vector of real numbers which describe the features of a training example, and the $y_i$s are drawn from a predefined set of *classes* (usually expressed as integers) that examples can be drawn from. A *binary* classifier has two classes (usually either 1 and 0, or 1 and -1)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Logistic Regression with Scikit-Learn"
]
},
{
"cell_type": "markdown",
"metadata": {
"tags": [
"remove-cell"
]
},
"source": [
"The dataset files you'll need are available here:\n",
"\n",
"- [`adult_processed_x`](https://github.com/uvm-plaid/programming-dp/raw/master/notebooks/adult_processed_x.npy)\n",
"- [`adult_processed_y`](https://github.com/uvm-plaid/programming-dp/raw/master/notebooks/adult_processed_y.npy)"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"tags": [
"remove-cell"
]
},
"outputs": [],
"source": [
"X = np.load('adult_processed_x.npy')\n",
"y = np.load('adult_processed_y.npy')"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To train a model, we will use some of the data we have available to build a set of *training examples* (as described earlier), but we'll also set aside some of the data as *test examples*. Once we have trained the model, we want to know how well it works on examples that are *not* present in the training set. A model which works well on new examples it hasn't seen before is said to *generalize* well. One which does *not* generalize well is said to have *overfitted* the training data.\n",
"\n",
"To test generalization, we'll use the test examples - we have labels for\n",
"them, so we can test the generalization accuracy of the model by asking\n",
"the model to classify each one, and then comparing the predicted class\n",
"against the actual label from our dataset. We'll split our data into a\n",
"training set containing 80% of the examples, and a testing set containing\n",
"20% of the examples."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {
"tags": [
"hide-cell"
]
},
"outputs": [
{
"data": {
"text/plain": [
"(9044,)"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"training_size = int(X.shape[0] * 0.8)\n",
"\n",
"X_train = X[:training_size]\n",
"X_test = X[training_size:]\n",
"\n",
"y_train = y[:training_size]\n",
"y_test = y[training_size:]\n",
"\n",
"y_test.shape"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A simple way to build a binary classifier is with *logistic regression*. The scikit-learn library has a built-in module for performing logistic regression, called `LogisticRegression`, and it's easy to use to build a model using our data."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"LogisticRegression()"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"from sklearn.linear_model import LogisticRegression\n",
"model = LogisticRegression().fit(X_train[:1000],y_train[:1000])\n",
"model"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Next, we can use the model's `predict` method to predict labels for the test set."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([-1., -1., -1., ..., -1., -1., -1.])"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"model.predict(X_test)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"So, how many test examples does our model get correct? We can compare the\n",
"predicted labels against the actual labels from the dataset; if we divide\n",
"the number of correctly predicted labels by the total number of test\n",
"examples, we can measure the percent of the examples which are correctly\n",
"classified."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.8243034055727554"
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"np.sum(model.predict(X_test) == y_test)/X_test.shape[0]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
" Our model predicts the correct label for 82% of the examples in our test\n",
"set. For this dataset, that's a pretty decent result."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## What is a Model?\n",
"\n",
"What exactly *is* a model? How does it encode the information it uses to make predictions?\n",
"\n",
"There are many different kinds of models, but the ones we'll explore here are *linear models*. For an unlabeled example with a $k$-dimensional feature vector $x_1, \\dots, x_k$, a linear model predicts a label by first calculating the quantity:\n",
"\n",
"\\begin{align}\n",
"w_1 x_1 + \\dots + w_k x_k + bias\n",
"\\end{align}\n",
"\n",
"and then taking the sign of it (i.e. if the quantity above is negative, we predict the label -1; if it's positive, we predict 1).\n",
"\n",
"The model itself, then, can be represented by a vector containing the values $w_1, \\dots, w_k$ and the value for $bias$. The model is said to be linear because the quantity we calculate in predicting a label is a polynomial of degree 1 (i.e. linear). The values $w_1, \\dots, w_k$ are often called the *weights* or *coefficients* of the model, and $bias$ is often called the *bias term* or *intercept*.\n",
"\n",
"This is actually how scikit-learn represents its logistic regression model, too! We can check out the weights of our trained model using the `coef_` attribute of the model:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {
"scrolled": true,
"tags": [
"hide-output"
]
},
"outputs": [
{
"data": {
"text/plain": [
"(-5.346167750306461,\n",
" array([ 3.76035057e-01, -2.55358856e-01, -3.21341426e-02, 3.74545737e-01,\n",
" -6.85885223e-01, 3.91875239e-01, -1.69476241e-01, -7.41793527e-02,\n",
" -5.76496538e-01, 3.94976503e-01, -3.41457312e-01, -6.24912317e-01,\n",
" -6.05605602e-01, -4.56928100e-01, -5.19167009e-01, -1.05743009e-01,\n",
" 8.19586633e-01, 9.96762702e-01, -3.09342985e-01, 6.57277160e-01,\n",
" -1.06436104e-01, 7.71287796e-01, 7.99791034e-02, 1.43803702e-01,\n",
" -1.01006564e-01, 1.59416785e+00, -5.06233997e-02, -5.78477239e-01,\n",
" -3.72601413e-01, -6.35661364e-01, -1.02810175e-01, 0.00000000e+00,\n",
" -1.35478173e-01, 4.36864993e-01, -3.42554362e-01, -1.32819675e-01,\n",
" -2.00200285e-01, -1.53919241e+00, 6.44831702e-02, 7.17836796e-01,\n",
" 3.80039408e-01, 4.25898498e-02, 8.81653483e-01, -7.08110462e-02,\n",
" 6.10385977e-02, 8.94590966e-02, 6.93679716e-01, -1.30382712e+00,\n",
" -6.55878656e-01, 1.11512993e+00, 3.78012650e-01, -4.28231712e-02,\n",
" -3.72812689e-01, 2.41180415e-01, -2.03955636e-01, -3.07042908e-01,\n",
" 3.06644477e-01, 4.31360344e-01, 5.31199745e-01, -6.89615763e-02,\n",
" 4.66366585e-01, -5.81829004e-01, -2.21952424e-01, -2.39529124e-01,\n",
" -1.40562769e-03, 7.26045748e-01, 2.46167426e-01, -6.08617054e-01,\n",
" 0.00000000e+00, -9.02427102e-02, -3.54430134e-03, 0.00000000e+00,\n",
" 0.00000000e+00, -1.29034794e-01, 5.90856998e-01, -5.15912614e-01,\n",
" 0.00000000e+00, -5.42096249e-03, 7.28556009e-01, -5.15261422e-02,\n",
" 2.30704112e-01, -1.61821068e-01, -6.60183260e-01, -1.01170807e-01,\n",
" -2.52337853e-01, -5.77230791e-02, -1.45064565e-01, -3.09985224e-01,\n",
" 0.00000000e+00, -3.31415590e-02, 0.00000000e+00, -1.38495395e-01,\n",
" 0.00000000e+00, 0.00000000e+00, 0.00000000e+00, 4.26243747e-01,\n",
" 0.00000000e+00, 0.00000000e+00, 1.72867533e+00, 7.37281346e-02,\n",
" 1.83154145e+00, 2.40009511e+00, 1.46921214e+00, 1.96856497e+00]))"
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"model.intercept_[0], model.coef_[0]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that we'll always have exactly the same number of weights $w_i$ as we have features $x_i$, since we have to multiply each feature by its corresponding weight. That means our model has exactly the same dimensionality as our feature vectors.\n",
"\n",
"Now that we have a way to get the weights and bias term, we can implement our own function to perform prediction:"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.8243034055727554"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# Prediction: take a model (theta) and a single example (xi) and return its predicted label\n",
"def predict(xi, theta, bias=0):\n",
" label = np.sign(xi @ theta + bias)\n",
" return label\n",
"\n",
"np.sum(predict(X_test, model.coef_[0], model.intercept_[0]) == y_test)/X_test.shape[0]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We've made the bias term optional here, because in many cases it's possible to do just as well without it. To make things simpler, we won't bother to train a bias term in our own algorithm."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Training a Model with Gradient Descent\n",
"\n",
"How does the training process actually work? The scikit-learn library has some pretty sophisticated algorithms, but we can do just about as well by implementing a simple one called *gradient descent*. \n",
"\n",
"Most training algorithms for machine learning are defined in terms of a *loss function*, which specifies a way to measure how \"bad\" a model is at prediction. The goal of the training algorithm is to minimize the output of the loss function - a model with low loss will be *good* at prediction. \n",
"\n",
"The machine learning community has developed many different commonly-used loss functions. A simple loss function might return 0 for each correctly predicted example, and 1 for each incorrectly predicted example; when the loss becomes 0, that means we've predicted each example's label correctly. A more commonly used loss function for binary classification is called the *logistic loss*; the logistic loss gives us a measure of \"how far\" we are from predicting the correct label (which is more informative than the simple 0 vs 1 approach).\n",
"\n",
"The logistic loss is implemented by the following Python function:"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"# The loss function measures how good our model is. The training goal is to minimize the loss.\n",
"# This is the logistic loss function.\n",
"def loss(theta, xi, yi):\n",
" exponent = - yi * (xi.dot(theta))\n",
" return np.log(1 + np.exp(exponent))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can use the loss function to measure how good a particular model is. Let's try it out with a model whose weights are all zeros. This model isn't likely to work very well, but it's a starting point from which we can train a better one."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.6931471805599453"
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"theta = np.zeros(X_train.shape[1])\n",
"loss(theta, X_train[0], y_train[0])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We typically measure how good our model is over our entire training set by simply averaging the loss over all of the examples in the training data. In this case, we get *every* example wrong, so the average loss on the whole training set is exactly equal to the loss we calculated above for just one example."
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.6931471805599453"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"np.mean([loss(theta, x_i, y_i) for x_i, y_i in zip(X_train, y_train)])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Our goal in *training* the model is to *minimize* the loss. So the key question is: how do we modify the model to make the loss smaller? \n",
"\n",
"Gradient descent is an approach that makes the loss smaller by updating the model according to the [*gradient*](https://en.wikipedia.org/wiki/Gradient) of the loss. The gradient is like a multi-dimensional derivative: for a function with multi-dimensional inputs (like our loss function above), the gradient tells you how fast the function's output is changing with respect to *each* dimension of the input. If the gradient is positive in a particular dimension, that means the function's value will *increase* if we increase the model's weight for that dimension; we want the loss to *decrease*, so we should modify our model by *negating* the gradient - i.e. do the *opposite* of what the gradient says. Since we move the model in the opposite direction of the gradient, this is called *descending* the gradient.\n",
"\n",
"When we iteratively perform many steps of this descent process, we slowly get closer and closer to the model which minimizes the loss. This algorithm is called *gradient descent*. Let's see how this looks in Python; first, we'll define the gradient function."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [],
"source": [
"# This is the gradient of the logistic loss\n",
"# The gradient is a vector that indicates the rate of change of the loss in each direction\n",
"def gradient(theta, xi, yi):\n",
" exponent = yi * (xi.dot(theta))\n",
" return - (yi*xi) / (1+np.exp(exponent))"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### A Single Step of Gradient Descent\n",
"\n",
"Next, let's perform a single step of gradient descent. We can apply the `gradient` function to a single example from our training data, which should give us enough information to improve the model for that example. We \"descend\" the gradient by subtracting it from our current model `theta`."
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {
"tags": [
"hide-output"
]
},
"outputs": [
{
"data": {
"text/plain": [
"array([ 0. , 0. , 0. , 0. , -0.5 ,\n",
" 0. , 0. , 0. , -0.5 , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" -0.5 , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , -0.5 , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , -0.5 ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , -0.5 ,\n",
" 0. , -0.5 , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" 0. , 0. , 0. , 0. , 0. ,\n",
" -0.5 , 0. , 0. , -0.25 , -0.0606146 ,\n",
" -0.21875 , 0. , 0. , -0.17676768])"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# If we take a step in the *opposite* direction from the gradient (by negating it), we should \n",
"# move theta in a direction that makes the loss *lower*\n",
"# This is one step of gradient descent - in each step, we're trying to \"descend\" the gradient\n",
"# In this example, we're taking the gradient on just a single training example (the first one)\n",
"theta = theta - gradient(theta, X_train[0], y_train[0])\n",
"theta"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now, if we call `predict` on the same example from the training data, its label is predicted correctly! That means our update did indeed improve the model, since it's now capable of classifying this example."
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"(-1.0, -1.0)"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"y_train[0], predict(theta, X_train[0])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We'll be measuring the accuracy of our model many times, so let's define a helper function for measuring accuracy. It works in the same way as the accuracy measurement for the sklearn model above. We can use it on the `theta` we've built by descending the gradient for one example, to see how good our model is on the test set."
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.7585139318885449"
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"def accuracy(theta):\n",
" return np.sum(predict(X_test, theta) == y_test)/X_test.shape[0]\n",
"\n",
"accuracy(theta)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Our improved model now predicts 75% of the labels for the test set correctly! That's good progress - we've improved the model considerably."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### A Gradient Descent Algorithm\n",
"\n",
"We need to make two changes to arrive at a basic gradient descent algorithm. First, our single step above used only a single example from the training data; we want to consider the *whole* training set when updating the model, so that we improve the model for *all* examples. Second, we need to perform multiple iterations, to get as close as possible to minimizing the loss.\n",
"\n",
"We can solve the first problem by calculating the *average gradient* over all of the training examples, and using it for the descent step in place of the single-example gradient we used before. Our `avg_grad` function calculates the average gradient over a whole array of training examples and the corresponding labels."
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {
"scrolled": true,
"tags": [
"hide-output"
]
},
"outputs": [
{
"data": {
"text/plain": [
"array([-8.03202480e-03, -1.09365062e-02, -5.86649848e-02, -1.70297784e-02,\n",
" -1.85949049e-02, -5.32762100e-03, 3.15432083e-05, 2.24692568e-03,\n",
" 1.80942171e-03, 1.10891317e-03, 7.17940863e-04, 1.22012681e-03,\n",
" 1.09385854e-03, 1.42352970e-03, -4.29266203e-03, -5.73114012e-03,\n",
" -4.96409990e-02, -7.90844879e-03, -1.08970068e-02, -2.50609905e-02,\n",
" 3.27410319e-04, -1.20102580e-02, -1.29608985e-02, 1.15182321e-02,\n",
" -2.26895536e-04, -1.83255483e-01, 1.34642262e-03, 4.47703452e-02,\n",
" 4.31895523e-03, 2.97414610e-03, 6.16295082e-03, -4.88903955e-05,\n",
" -2.13933205e-02, -4.86969833e-02, -8.62802483e-04, 3.11463168e-03,\n",
" 1.23013848e-03, 1.54486498e-02, 1.21336873e-03, -4.38864985e-02,\n",
" -4.34689131e-03, -1.64743409e-02, -4.53583200e-03, -5.47845717e-03,\n",
" -1.67472715e-01, 1.93015718e-02, 4.73608091e-03, 2.44149704e-02,\n",
" 1.61917788e-02, -1.57259641e-02, 6.59058497e-04, -1.58429762e-03,\n",
" 9.21938268e-03, 8.76978910e-04, -1.27725399e-01, 3.39811988e-02,\n",
" -1.52535476e-01, -1.11859092e-04, -7.43481028e-04, -2.46346175e-04,\n",
" 2.71911076e-04, -2.55366711e-04, 4.50825450e-04, 1.10378277e-04,\n",
" 3.56606530e-04, -6.45268003e-04, -2.29994332e-04, -3.86436617e-04,\n",
" -3.08625397e-04, 2.96102401e-04, 1.88227302e-04, 8.58078928e-06,\n",
" 7.20867325e-05, -4.19942412e-05, -8.78083803e-05, -8.39666492e-04,\n",
" -3.06575834e-04, -8.40712924e-05, -5.70563641e-04, 4.00302057e-04,\n",
" -2.64158094e-04, 6.99057157e-05, 2.42709304e-03, 1.82470777e-04,\n",
" 8.76079931e-05, 1.54645694e-04, -2.72063515e-04, -6.37207436e-05,\n",
" 1.24980547e-05, 4.45197135e-04, 4.61621071e-05, 1.15265174e-04,\n",
" -2.77439358e-04, 5.96595409e-05, 1.20539191e-04, -1.18965672e-01,\n",
" 3.44932395e-04, -7.41634269e-05, -6.91870325e-02, -1.45516103e-02,\n",
" -9.95735544e-02, -8.85669054e-03, -9.10018120e-03, -6.35462985e-02])"
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"def avg_grad(theta, X, y):\n",
" grads = [gradient(theta, xi, yi) for xi, yi in zip(X, y)]\n",
" return np.mean(grads, axis=0)\n",
"\n",
"avg_grad(theta, X_train, y_train)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To solve the second problem, we'll define an iterative algorithm that descends the gradient multiple times."
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {},
"outputs": [],
"source": [
"def gradient_descent(iterations):\n",
" # Start by \"guessing\" what the model should be (all zeros)\n",
" theta = np.zeros(X_train.shape[1])\n",
"\n",
" # Perform `iterations` steps of gradient descent using training data\n",
" for i in range(iterations):\n",
" theta = theta - avg_grad(theta, X_train, y_train)\n",
"\n",
" return theta"
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.7787483414418399"
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"theta = gradient_descent(10)\n",
"accuracy(theta)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"After 10 iterations, our model reaches nearly 78% accuracy - not bad! Our gradient descent algorithm looks simple (and it is!) but don't let its simplicity fool you - this basic approach is behind many of the recent successes in large-scale deep learning, and our algorithm is *very* close in its design to the ones implemented in popular frameworks for machine learning like TensorFlow.\n",
"\n",
"Notice that we didn't quite make it to the 84% accuracy of the sklearn model we trained earlier. Don't worry - our algorithm is definitely capable of this! We just need more iterations, to get closer to the minimum of the loss."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"With 100 iterations, we get closer - 82% accuracy. However, the algorithm takes a long time to run when we ask for so many iterations. Even worse, the closer we get to minimizing the loss, the more difficult it is to improve - so we might get to 82% accuracy after 100 iterations, but it might take 1000 iterations to get to 84%. This points to a fundamental tension in machine learning - generally speaking, more iterations of training can improve accuracy, but more iterations requires more computation time. Most of the \"tricks\" used to make large-scale deep learning practical are actually aimed at speeding up each iteration of gradient descent, so that more iterations can be performed in the same amount of time.\n",
"\n",
"One more thing that's interesting to note: the value of the loss function does indeed go down with each iteration of gradient descent we perform - so as we perform more iterations, we slowly get closer to minimizing the loss. Also note that the training and testing loss are very close to one another, suggesting that our model is not *overfitting* to the training data."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {
"tags": [
"hide-cell"
]
},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Training loss: 0.549109439168421\n",
"Testing loss: 0.5415350837580458\n",
"\n",
"Training loss: 0.5224689105514977\n",
"Testing loss: 0.5162665121068426\n",
"\n",
"Training loss: 0.5028090736020403\n",
"Testing loss: 0.49753785424732383\n",
"\n",
"Training loss: 0.4878874803989895\n",
"Testing loss: 0.48335633696635527\n",
"\n",
"Training loss: 0.47628573924997925\n",
"Testing loss: 0.4723742456095848\n",
"\n"
]
}
],
"source": [
"def gradient_descent_log(iterations):\n",
" theta = np.zeros(X_train.shape[1])\n",
"\n",
" for i in range(iterations):\n",
" theta = theta - avg_grad(theta, X_train, y_train)\n",
" print(f'Training loss: {np.mean(loss(theta, X_train, y_train))}')\n",
" print(f'Testing loss: {np.mean(loss(theta, X_test, y_test))}\\n')\n",
"\n",
" return theta\n",
"\n",
"gradient_descent_log(5);"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Gradient Descent with Differential Privacy\n",
"\n",
"How can we make the above algorithm differentially private? We'd like to design an algorithm that ensures differential privacy for the training data, so that the final model doesn't reveal anything about individual training examples.\n",
"\n",
"The only part of the algorithm which uses the training data is the gradient calculation. One way to make the algorithm differentially private is to add noise to the gradient itself at each iteration before updating the model. This approach is usually called *noisy gradient descent*, since we add noise directly to the gradient.\n",
"\n",
"Our gradient function is a vector-valued function, so we can use `gaussian_mech_vec` to add noise to its output:"
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [],
"source": [
"def noisy_gradient_descent(iterations, epsilon, delta):\n",
" theta = np.zeros(X_train.shape[1])\n",
" sensitivity = '???'\n",
"\n",
" for i in range(iterations):\n",
" grad = avg_grad(theta, X_train, y_train)\n",
" noisy_grad = gaussian_mech_vec(grad, sensitivity, epsilon, delta)\n",
" theta = theta - noisy_grad\n",
"\n",
" return theta"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There's just one piece of the puzzle missing - **what is the sensitivity of the gradient function**? Answering this question is the central difficulty in making the algorithm work.\n",
"\n",
"There are two major challenges here. First, the gradient is the result of an *average query* - it's the mean of many per-example gradients. As we've seen previously, it's best to split queries like this up into a sum query and a count query. This isn't difficult to do - we can compute the noisy sum of the per-example gradients, rather than their average, and divide by a noisy count later. Second, we need to bound the sensitivity of each per-example gradient. There are two basic approaches for this: we can either analyze the gradient function itself (as we have done with previous queries) to determine its worst-case global sensitivity, or we can *enforce* a sensitivity by clipping the output of the gradient function (as we did in sample and aggregate).\n",
"\n",
"We'll start with the second approach - often called *gradient clipping* - because it's simpler conceptually and more general in its applications."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Gradient Clipping\n",
"\n",
"Gradient clipping is a technique often employed in machine learning, including differential privacy scenarios, to mitigate the risk of large gradients during training. When training a model, the gradient of the loss with respect to the model's parameters is computed and used to update the parameters. Gradient clipping involves scaling or limiting the gradients to a specified threshold if they exceed that threshold. This helps stabilize training and prevents large updates that may lead to overshooting or divergence.\n",
"\n",
"In the context of differential privacy, gradient clipping is used to control the sensitivity of the model. Recall that, in the context of differential privacy, sensitivity refers to the maximum amount by which the output of a function (or the model's parameters) can change when a single data point is added or removed from the input dataset. It is a crucial concept in differential privacy because it helps quantify how much an individual's data can influence the overall outcome, thus providing a measure of privacy protection. The sensitivity of a model's update is related to the maximum change in the model parameters caused by a single training example. By limiting the gradients during training, gradient clipping indirectly limits the sensitivity of the model, making it more amenable to differential privacy.\n",
"\n",
"To incorporate gradient clipping into a differentially private training process, the clipping is often applied to the gradients before they are used to update the model parameters. This helps ensure that individual training examples do not overly influence the model and helps maintain privacy guarantees.\n",
"\n",
"To sum up: sensitivity in the context of differential privacy refers to the maximum impact a single data point can have on the model's output, and gradient clipping is a technique used to control and limit this sensitivity during the training of differentially private models.\n",
"\n",
"Recall that when we implemented sample and aggregate, we enforced a desired sensitivity on a function $f$ with unknown sensitivity by clipping its output. The sensitivity of $f$ was:\n",
"\n",
"\\begin{align}\n",
"\\lvert f(x) - f(x') \\rvert\n",
"\\end{align}\n",
"\n",
"After clipping with parameter $b$, this becomes:\n",
"\n",
"\\begin{align}\n",
"\\lvert \\mathsf{clip}(f(x), b) - \\mathsf{clip}(f(x'),b) \\rvert\n",
"\\end{align}\n",
"\n",
"In the worst case, $\\mathsf{clip}(f(x), b) = b$, and $\\mathsf{clip}(f(x'),b) = 0$, so the sensitivity of the clipped result is exactly $b$ (the value of the clipping parameter).\n",
"\n",
"We can use the same trick to bound the $L2$ sensitivity of our gradient function. We'll need to define a function which \"clips\" a vector so that it has $L2$ norm within a desired range. We can accomplish this by *scaling* the vector: if we divide the vector elementwise by its $L2$ norm, then the resulting vector will have an $L2$ norm of 1. If we want to target a particular clipping parameter $b$, we can multiply the scaled vector by $b$ to scale it back up to have $L2$ norm $b$. We want to avoid modifying vectors that already have $L2$ norm below $b$; in that case, we just return the original vector. We can use `np.linalg.norm` with the parameter `ord=2` to calculate the $L2$ norm of a vector."
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {},
"outputs": [],
"source": [
"def L2_clip(v, b):\n",
" norm = np.linalg.norm(v, ord=2)\n",
" \n",
" if norm > b:\n",
" return b * (v / norm)\n",
" else:\n",
" return v"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we're ready to analyze the sensitivity of the clipped gradient. We denote the gradient as $\\nabla(\\theta; X, y)$ (corresponding to `gradient` in our Python code):\n",
"\n",
"\\begin{align}\n",
"\\lVert \\mathsf{L2\\_clip}( \\nabla (\\theta; X, y), b) - \\mathsf{L2\\_clip}( \\nabla (\\theta; X', y), 0) \\rVert_2\n",
"\\end{align}\n",
"\n",
"In the worst case, $\\mathsf{L2\\_clip}( \\nabla (\\theta; X, y), b)$ has $L2$ norm of $b$, and $\\mathsf{L2\\_clip}( \\nabla (\\theta; X', y))$ is all zeros - so that the $L2$ norm of the difference is equal to $b$. Thus, the $L2$ sensitivity of the clipped gradient is bounded by the clipping parameter $b$!\n",
"\n",
"Now we can proceed to compute the sum of clipped gradients, and add noise based on the $L2$ sensitivity $b$ that we've enforced by clipping."
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {},
"outputs": [],
"source": [
"def gradient_sum(theta, X, y, b):\n",
" gradients = [L2_clip(gradient(theta, x_i, y_i), b) for x_i, y_i in zip(X,y)]\n",
" \n",
" # sum query\n",
" # L2 sensitivity is b (by clipping performed above)\n",
" return np.sum(gradients, axis=0)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Now we're ready to complete our noisy gradient descent algorithm. To compute the noisy average gradient, we need to:\n",
"\n",
"1. Add noise to the sum of the gradients based on its sensitivity $b$\n",
"2. Compute a noisy count of the number of training examples (sensitivity 1)\n",
"3. Divide the noisy sum from (1) by the noisy count from (2)"
]
},
{
"cell_type": "code",
"execution_count": 23,
"metadata": {},
"outputs": [],
"source": [
"def noisy_gradient_descent(iterations, epsilon, delta):\n",
" theta = np.zeros(X_train.shape[1])\n",
" sensitivity = 5.0\n",
" \n",
" noisy_count = laplace_mech(X_train.shape[0], 1, epsilon)\n",
"\n",
" for i in range(iterations):\n",
" grad_sum = gradient_sum(theta, X_train, y_train, sensitivity)\n",
" noisy_grad_sum = gaussian_mech_vec(grad_sum, sensitivity, epsilon, delta)\n",
" noisy_avg_grad = noisy_grad_sum / noisy_count\n",
" theta = theta - noisy_avg_grad\n",
"\n",
" return theta"
]
},
{
"cell_type": "code",
"execution_count": 24,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.7797434763379035"
]
},
"execution_count": 24,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"theta = noisy_gradient_descent(10, 0.1, 1e-5)\n",
"accuracy(theta)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Each iteration of this algorithm satisfies $(\\epsilon, \\delta)$-differential privacy, and we perform one additional query to determine the noisy count which satisfies $\\epsilon$-differential privacy. If we perform $k$ iterations, then by sequential composition, the algorithm satisfies $(k\\epsilon + \\epsilon, k\\delta)$-differential privacy. We can also use advanced composition to analyze the total privacy cost; even better, we could convert the algorithm to Rényi differential privacy or zero-concentrated differential privacy, and obtain tight bounds on composition."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Sensitivity of the Gradient\n",
"\n",
"Our previous approach is very general, since it makes no assumptions about the behavior of the gradient. Sometimes, however, we *do* know something about the behavior of the gradient. In particular, a large class of useful gradient functions (including the gradient of the logistic loss, which we're using here) are *Lipschitz continuous* - meaning they have bounded global sensitivity. Formally, it is possible to show that:\n",
"\n",
"\\begin{align}\n",
"\\text{If}\\; \\lVert x_i \\rVert_2 \\leq b\\; \\text{then}\\; \\lVert \\nabla(\\theta; x_i, y_i) \\rVert_2 \\leq b\n",
"\\end{align}\n",
"\n",
"This fact allows us to clip the values of the *training examples* (i.e. the *inputs* to the gradient function), instead of the *output* of the gradient function, and obtain a bound on the $L2$ sensitivity of the gradient.\n",
"\n",
"Clipping the training examples instead of the gradients has two advantages. First, it's often easier to estimate the scale of the training data (and thus to pick a good clipping parameter) than it is to estimate the scale of the gradients you'll compute during training. Second, it's computationally more efficient: we can clip the training examples *once*, and re-use the clipped training data every time we train a model; with gradient clipping, we need to clip each gradient during training. Furthermore, we're no longer forced to compute per-example gradients so that we can clip them; instead, we can compute all of the gradients at once, which can be done very efficiently (this is a commonly used trick in machine learning, but we won't discuss it here).\n",
"\n",
"Note, however, that many useful loss functions - in particular, those derived from neural networks in deep learning - do *not* have bounded global sensitivity. For these loss functions, we're forced to use gradient clipping.\n",
"\n",
"We can clip the training examples instead of the gradients with a couple of simple modifications to our algorithm. First, we clip the training examples using `L2_clip` before we start training. Second, we simply delete the code for clipping the gradients."
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {},
"outputs": [],
"source": [
"def gradient_sum(theta, X, y, b):\n",
" gradients = [gradient(theta, x_i, y_i) for x_i, y_i in zip(X,y)]\n",
" \n",
" # sum query\n",
" # L2 sensitivity is b (by sensitivity of the gradient)\n",
" return np.sum(gradients, axis=0)"
]
},
{
"cell_type": "code",
"execution_count": 26,
"metadata": {},
"outputs": [],
"source": [
"def noisy_gradient_descent(iterations, epsilon, delta):\n",
" theta = np.zeros(X_train.shape[1])\n",
" sensitivity = 5.0\n",
" \n",
" noisy_count = laplace_mech(X_train.shape[0], 1, epsilon)\n",
" clipped_X = [L2_clip(x_i, sensitivity) for x_i in X_train]\n",
"\n",
" for i in range(iterations):\n",
" grad_sum = gradient_sum(theta, clipped_X, y_train, sensitivity)\n",
" noisy_grad_sum = gaussian_mech_vec(grad_sum, sensitivity, epsilon, delta)\n",
" noisy_avg_grad = noisy_grad_sum / noisy_count\n",
" theta = theta - noisy_avg_grad\n",
"\n",
" return theta"
]
},
{
"cell_type": "code",
"execution_count": 27,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.7808491817779744"
]
},
"execution_count": 27,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"theta = noisy_gradient_descent(10, 0.1, 1e-5)\n",
"accuracy(theta)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Many improvements to this algorithm are possible, which can improve privacy cost and accuracy. Many are drawn from the machine learning literature. Some examples include:\n",
"\n",
"- Bounding the *total* privacy cost by $\\epsilon$ by calculating a per-iteration $\\epsilon_i$ as part of the algorithm.\n",
"- Better composition for large numbers of iterations via advanced composition, RDP, or zCDP.\n",
"- Minibatching: calculating the gradient for each iteration using a small chunk of the training data, rather than the whole training set (this reduces the computation needed to calculate the gradient).\n",
"- Parallel composition in conjunction with minibatching.\n",
"- Random sampling of batches in conjunction with minibatching.\n",
"- Other hyperparameters, like a learning rate $\\eta$."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Effect of Noise on Training\n",
"\n",
"So far, we've seen that the number of iterations has a big effect on the accuracy of the model we get, since more iterations can get you closer to the minimum of the loss. Since our differentially private algorithm adds noise to the gradient, this can also affect accuracy - the noise can cause our algorithm to move in *the wrong direction* during training, and actually make the model *worse*.\n",
"\n",
"It's reasonable to expect that smaller values of $\\epsilon$ will result in less accurate models (since this has been the trend in every differentially private algorithm we have seen so far). This is true, but there's also a slightly more subtle tradeoff which occurs because of the composition we need to consider when we perform many iterations of the algorithm: more iterations means a larger privacy cost. In the standard gradient descent algorithm, more iterations generally result in a better model. In our differentially private version, more iterations can make the model *worse*, since we have to use a smaller $\\epsilon$ for each iteration, and so the scale of the noise goes up. In differentially private machine learning, it's important (and sometimes, very challenging) to strike the right balance between the number of iterations used and the scale of the noise added.\n",
"\n",
"Let's do a small experiment to see how the setting of $\\epsilon$ effects the accuracy of our model. We'll train a model for several values of $\\epsilon$, using 20 iterations each time, and graph the accuracy of each model against the $\\epsilon$ value used in training it."
]
},
{
"cell_type": "code",
"execution_count": 28,
"metadata": {
"tags": [
"hide-cell"
]
},
"outputs": [],
"source": [
"delta = 1e-5\n",
"\n",
"epsilons = [0.001, 0.003, 0.005, 0.008, 0.01, 0.03, 0.05, 0.08, 0.1]\n",
"thetas = [noisy_gradient_descent(10, epsilon, delta) for epsilon in epsilons]\n",
"accs = [accuracy(theta) for theta in thetas]"
]
},
{
"cell_type": "code",
"execution_count": 29,
"metadata": {
"tags": [
"hide-input"
]
},
"outputs": [
{
"data": {
"image/png": "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",
"text/plain": [
"