evaluation_methods.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Evaluation methods in NLP"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "__author__ = \"Christopher Potts\"\n",
    "__version__ = \"CS224u, Stanford, Spring 2023\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Contents\n",
    "\n",
    "1. [Overview](#Overview)\n",
    "1. [Your projects](#Your-projects)\n",
    "1. [Set-up](#Set-up)\n",
    "1. [Data organization](#Data-organization)\n",
    "    1. [Train/dev/test](#Train/dev/test)\n",
    "    1. [No fixed splits](#No-fixed-splits)\n",
    "1. [Cross-validation](#Cross-validation)\n",
    "    1. [Random splits](#Random-splits)\n",
    "    1. [K-folds](#K-folds)\n",
    "1. [Baselines](#Baselines)\n",
    "    1. [Baselines are crucial for strong experiments](#Baselines-are-crucial-for-strong-experiments)\n",
    "    1. [Random baselines](#Random-baselines)\n",
    "    1. [Task-specific baselines](#Task-specific-baselines)\n",
    "1. [Hyperparameter optimization](#Hyperparameter-optimization)\n",
    "    1. [Rationale](#Rationale)\n",
    "    1. [The ideal hyperparameter optimization setting](#The-ideal-hyperparameter-optimization-setting)\n",
    "    1. [Practical considerations, and some compromises](#Practical-considerations,-and-some-compromises)\n",
    "    1. [Hyperparameter optimization tools](#Hyperparameter-optimization-tools)\n",
    "1. [Classifier comparison](#Classifier-comparison)\n",
    "    1. [Practical differences](#Practical-differences)\n",
    "    1. [Confidence intervals](#Confidence-intervals)\n",
    "    1. [Wilcoxon signed-rank test](#Wilcoxon-signed-rank-test)\n",
    "    1. [McNemar's test](#McNemar's-test)\n",
    "1. [Assessing models without convergence](#Assessing-models-without-convergence)\n",
    "    1. [Incremental dev set testing](#Incremental-dev-set-testing)\n",
    "    1. [Learning curves with confidence intervals](#Learning-curves-with-confidence-intervals)\n",
    "1. [The role of random parameter initialization](#The-role-of-random-parameter-initialization)\n",
    "1. [Closing remarks](#Closing-remarks)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Overview\n",
    "\n",
    "This notebook is an overview of experimental methods for NLU. My primary goal is to help you with the experiments you'll be doing for your projects.  It is a companion to [the evaluation metrics notebook](evaluation_metrics.ipynb), which I suggest studying first.\n",
    "\n",
    "The teaching team will be paying special attention to how you conduct your evaluations, so this notebook should create common ground around what our values are.\n",
    "\n",
    "This notebook is far from comprehensive. I hope it covers the most common tools, techniques, and challenges in the field. Beyond that, I'm hoping the examples here suggest a perspective on experiments and evaluations that generalizes to other topics and techniques."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Your projects\n",
    "\n",
    "1. We will never evaluate a project based on how \"good\" the results are.\n",
    "  1. Publication venues do this, because they have additional constraints on space that lead them to favor positive evidence for new developments over negative results.\n",
    "  1. In CS224u, we are not subject to this constraint, so we can do the right and good thing of valuing positive results, negative results, and everything in between.\n",
    "\n",
    "1. We __will__ evaluate your project on:   \n",
    "  1. The appropriateness of the metrics\n",
    "  1. The strength of the methods\n",
    "  1. The extent to which the paper is open and clear-sighted about the limits of its findings. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Set-up"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections import defaultdict, Counter\n",
    "import datasets\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "import os\n",
    "import pandas as pd\n",
    "from scipy import stats\n",
    "from sklearn.datasets import make_classification\n",
    "from sklearn.metrics import classification_report\n",
    "from sklearn.model_selection import train_test_split\n",
    "import sst\n",
    "from torch_rnn_classifier import TorchRNNClassifier\n",
    "from torch_shallow_neural_classifier import TorchShallowNeuralClassifier\n",
    "import utils"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "utils.fix_random_seeds()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Data organization"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Train/dev/test\n",
    "\n",
    "Many publicly available datasets are released with a train/dev/test structure. __We're all on the honor system to do test-set runs only when development is complete.__\n",
    "\n",
    "Splits like this basically presuppose a fairly large dataset.\n",
    "\n",
    "If there is no dev set as part of the distribution, then you might create one to simulate what a test run will be like, though you have to weigh this against the reduction in train-set size.\n",
    "\n",
    "Having a fixed test set ensures that all systems are assessed against the same gold data. This is generally good, but it is problematic where the test set turns out to have unusual properties that distort progress on the task. Ideally, every task would have dozens of test sets, so that we could report average performance and related statistics. The difficulty and expense of creating so many test sets means that this ideal is rarely if ever realized."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### No fixed splits\n",
    "\n",
    "Many datasets are released without predefined splits. This poses challenges for assessment, especially comparative assessment: __for robust comparisons with prior work, you really have to rerun the models using your assessment regime on your splits__. For example, if you're doing [5-fold cross-validation](#K-folds), then all the systems should be trained and assessed using exactly the same folds, to control for variation in how difficult the splits are.\n",
    "\n",
    "If the dataset is large enough, you might create a train/test or train/dev/test split right at the start of your project and use it for all your experiments. This means putting the test portion in a locked box until the very end, when you assess all the relevant systems against it. For large datasets, this will certainly simplify your experimental set-up, for reasons that will become clear when we discuss [hyperparameter optimization](#Hyperparameter-optimization) below.\n",
    "\n",
    "For small datasets, carving out dev and test sets might leave you with too little data. The most problematic symptom of this is that performance is highly variable because there isn't enough data to optimize reliably. In such situations, you might give up on having fixed splits, opting instead for some form of cross-validation, which allows you to average over multiple runs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Cross-validation\n",
    "\n",
    "In cross-validation, we take a set of examples $X$ and partition them into two or more train/test splits, and then we average over the results in some way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Random splits\n",
    "\n",
    "When creating random train/test splits, we shuffle the examples and split them, with a pre-specified percentage $t$ used for training and another pre-specified percentage (usually $1-t$) used for testing.\n",
    "\n",
    "In general, we want these splits to be __stratified__ in the sense that the train and test splits have approximately the same distribution over the classes.\n",
    "\n",
    "#### The good and the bad of random splits\n",
    "\n",
    "A nice thing about random splits is that you can create as many as you want without having this impact the ratio of training to testing examples. \n",
    "\n",
    "This can also be a liability, though, as there's no guarantee that every example will be used the same number of times for training and testing. In principle, one might even evaluate on the same split more than once (though this will be fantastically unlikely for large datasets). NLP datasets are generally large enough that this isn't a pressing concern.\n",
    "\n",
    "The function `utils.fit_classifier_with_hyperparameter_search` hard-codes a strategy of using random splits by using the [StratifiedShuffleSplit](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.StratifiedShuffleSplit.html#sklearn.model_selection.StratifiedShuffleSplit) utility. The benefit of decoupling the train/test ratio from the number of splits outweights the concerns about split composition.\n",
    "\n",
    "#### Random splits in scikit-learn\n",
    "\n",
    "In scikit-learn, the function [train_test_split](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html) will do random splits. It is a wrapper around [ShuffleSplit](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.ShuffleSplit.html#sklearn.model_selection.ShuffleSplit) or [StratifiedShuffleSplit](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.StratifiedShuffleSplit.html#sklearn.model_selection.StratifiedShuffleSplit), depending on how the keyword argument `stratify` is used. A potential gotcha for classification problems: `train_test_split` does not stratify its splits by default, whereas stratified splits are desired in most situations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### K-folds\n",
    "\n",
    "In K-fold cross-validation, one divides the data into $k$ folds of equal size and then conducts $k$ experiments. In each, fold $i$ is used for assessment, and all the other folds are merged together for training:\n",
    "\n",
    "$$\n",
    "\\begin{array}{c c c }\n",
    "\\textbf{Splits} & \\textbf{Experiment 1} & \\textbf{Experiment 2} & \\textbf{Experiment 3} \\\\\n",
    "\\begin{array}{|c|}\n",
    "\\hline\n",
    "\\textrm{fold } 1  \\\\\\hline\n",
    "\\textrm{fold } 2  \\\\\\hline\n",
    "\\textrm{fold } 3  \\\\\\hline\n",
    "\\end{array}\n",
    "& \n",
    "\\begin{array}{|c c|}\n",
    "\\hline\n",
    "\\textbf{Test} & \\textrm{fold } 1  \\\\\\hline\n",
    "\\textbf{Train} & \\textrm{fold } 2  \\\\\n",
    "& \\textrm{fold } 3  \\\\\\hline\n",
    "\\end{array}\n",
    "&\n",
    "\\begin{array}{|c c|}\n",
    "\\hline\n",
    "\\textbf{Test} & \\textrm{fold } 2  \\\\\\hline\n",
    "\\textbf{Train} & \\textrm{fold } 1  \\\\\n",
    "& \\textrm{fold } 3  \\\\\\hline\n",
    "\\end{array}\n",
    "&\n",
    "\\begin{array}{|c c|}\n",
    "\\hline\n",
    "\\textbf{Test} & \\textrm{fold } 3  \\\\\\hline\n",
    "\\textbf{Train} & \\textrm{fold } 1  \\\\\n",
    "& \\textrm{fold } 2  \\\\\\hline\n",
    "\\end{array}\n",
    "\\end{array}\n",
    "$$\n",
    "\n",
    "#### The good and the bad of k-folds\n",
    "\n",
    "* With k-folds, every example appears in a train set exactly $k-1$ times and in a test set exactly once. We noted above that random splits do not guarantee this.\n",
    "\n",
    "* A major drawback of k-folds is that the size of $k$ determines the size of the train/test splits. With 3-fold cross validation, one trains on 67% of the data and tests on 33%. With 10-fold cross-validation, one trains on 90% and tests on 10%. These are likely to be __very__ different experimental scenarios. This is a consideration one should have in mind when [comparing models](#Classifier-comparison) using statistical tests that depend on repeated runs. This is a large enough drawback to k-folds that I generally favor random splits, [as discussed just above](#Random-splits)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### K-folds in scikit-learn\n",
    "\n",
    "* In scikit-learn, [KFold](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.KFold.html#sklearn.model_selection.KFold) and [StratifiedKFold](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.StratifiedKFold.html#sklearn.model_selection.StratifiedKFold) are the primary classes for creating k-folds from a dataset. As with random splits, the stratified option is recommended for most classification problems, as one generally want to train and assess with the same label distribution.\n",
    "\n",
    "* The methods [cross_validate](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.cross_validate.html#sklearn.model_selection.cross_validate) and [cross_val_score](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.cross_val_score.html#sklearn.model_selection.cross_val_score) are convenience methods that let you pass in a model (`estimator`), a dataset (`X` and `y`), and some cross-validation parameters, and they handle the repeated assessments. These are great. Two tips:\n",
    "  * I strongly recommend passing in a `KFold` or `StratifiedKFold` instance as the value of `cv` to ensure that you get the split behavior that you desire.\n",
    "  * Check that `scoring` has the value that you desire. For example, if you are going to report F1-scores, it's a mistake to leave `scoring=None`, as this will default to whatever your model reports with its `score` method, which is probably accuracy."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Variants  \n",
    "  \n",
    "K-folds has a number of variants and special cases. Two that frequently arise in NLU:\n",
    "\n",
    "1. [LeaveOneOut](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.LeaveOneOut.html#sklearn.model_selection.LeaveOneOut) is the special case where the number of folds equals the number of examples. This is especially useful for very small datasets.\n",
    "\n",
    "1. [LeavePGroupsOut](http://scikit-learn.org/stable/modules/generated/sklearn.model_selection.LeavePGroupsOut.html#sklearn.model_selection.LeavePGroupsOut) creates folds based on criteria that you define. This is useful in situations where the datasets have important structure that the splits need to respect – e.g., you want to assess against a graph sub-network that is never seen on training."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Baselines\n",
    "\n",
    "Evaluation numbers in NLP (and throughout AI) __can never be understood properly in isolation__:\n",
    "\n",
    "* If your system gets 0.95 F1, that might seem great in absolute terms, but your readers will suspect the task is too easy and want to know what simple models achieve.\n",
    "\n",
    "* If your system gets 0.60 F1, you might despair, but it could turn out that humans achieve only 0.80, indicating that you got traction on a very challenging but basically coherent problem."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Baselines are crucial for strong experiments\n",
    "\n",
    "Defining baselines should not be an afterthought, but rather central to how you define your overall hypotheses. __Baselines are essential to building a persuasive case__, and they can also be used to illuminate specific aspects of the problem and specific virtues of your proposed system."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Random baselines\n",
    "\n",
    "Random baselines are almost always useful to include. scikit-learn has classes [DummyClassifier](http://scikit-learn.org/stable/modules/generated/sklearn.dummy.DummyClassifier.html#sklearn.dummy.DummyClassifier) and [DummyRegressor](http://scikit-learn.org/stable/modules/generated/sklearn.dummy.DummyRegressor.html#sklearn.dummy.DummyRegressor). Each of them has a keyword argument `strategy` that allows you to specify a range of different styles of random guessing. I highly recommend using these in your work, for two central reasons:\n",
    "\n",
    "1. They will probably fit into your overall modeling pipeline.\n",
    "2. It's usual conceptually easy to describe these baselines but it can be tricky and error-prone to implement them – and the scikit-learn folks probably already did it for you flawlessly!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Task-specific baselines\n",
    "\n",
    "It is worth considering whether your problem suggests a baseline that will reveal something about the problem or the ways it is modeled. Two recent examples from NLU:\n",
    "\n",
    "1. As disussed briefly in [the NLI models notebook](nli_02_models.ipynb#Other-findings), [Leonid Keselman](https://leonidk.com/) observed [in his 2016 NLU course project](https://leonidk.com/stanford/cs224u.html) that one can do much better than chance on SNLI by processing only the hypothesis, ignoring the premise entirely. The exact interpretation of this is complex (we explore this a bit [in our NLI unit](nli_02_models.ipynb#Hypothesis-only-baselines) and [in our NLI bake-off](nli_wordentail.ipynb)), but it's certainly relevant for understanding how much a system has actually learned about reasoning from a premise to a conclusion.\n",
    " \n",
    "1. [Schwartz et al. (2017)](https://www.aclweb.org/anthology/W17-0907) develop a system for choosing between a coherent and incoherent ending for a story. Their best system achieves 75% accuracy by processing the story and the ending, but they achieve 72% using only stylistic features of the ending, ignoring the preceding story entirely. This puts the 75% – and the extent to which the system understands story completion – in a new light."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Hyperparameter optimization\n",
    "\n",
    "In machine learning, the __parameters__ of a model are those whose values are learned as part of optimizing the model itself. \n",
    "\n",
    "The __hyperparameters__ of a model are any settings that are set by a process that is outside of this optimization process. The boundary between a true setting of the model and a broader design choice will likely be blurry conceptually. For example: \n",
    "\n",
    "* The regularization term for a classifier is a clear hyperparameter – it appears in the model's objective function. \n",
    "* What about the method one uses for normalizing the feature values? This is probably not a setting of the model per se, but rather a choice point in your experimental framework.\n",
    "  \n",
    "For the purposes of this discussion, we'll construe hyperparameters very broadly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Rationale\n",
    "\n",
    "Hyperparameter optimization is one of the most important parts machine learning, and a crucial part of building a persuasive argument. For one angle on why, it's helpful to imagine that you're in an ongoing debate with a very skeptical referee:\n",
    "\n",
    "1. You ran experiments with models A, B, and C. For each, you used the default hyperparameters as given by the implementations you're using. You found that C performed the best, and so you reported that in your paper.\n",
    "1. Your reviewer doesn't have visibility into your process, and maybe doesn't fully trust you. Did you try any other values for the hyperparameters without reporting that? If not, would you have done that if C hadn't outperformed the others? There is no way for the reviewer (or perhaps anyone) to answer these questions.\n",
    "1. So, from the reviewer's perspective, all we learned from your experiments is that there is some set of hyperparameters on which C wins this competition. But, strictly speaking, this conveys no new information; we knew before you did your experiments that we could find settings that would deliver this and all other outcomes. (They might not be __sensible__ settings, but remember you're dealing with a hard-bitten, unwavering skeptic.)\n",
    "\n",
    "Our best response to this situation is to allow these models to explore a wide range of hyperparameters, choose the best ones according to performance on training or development data, and then report how they do with those settings at test time. __This gives every model its best chance to succeed.__\n",
    "\n",
    "If you do this, the strongest argument that your skeptical reviewer can muster is that you didn't pick the right space of hyperparameters to explore for one or more of the models. Alas, there is no satisfying the skeptic, but we can at least feel happy that the outcome of these experiments will have a lot more scientific value than the ones described above with fixed hyperparameters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### The ideal hyperparameter optimization setting\n",
    "\n",
    "When evaluating a model, the ideal regime for hyperparameter optimization is as follows:\n",
    "\n",
    "1. For each hyperparameter, identify a large set of values for it. \n",
    "2. Create a list of all the combinations of all the hyperparameter values. This will be the [cross-product](https://en.wikipedia.org/wiki/Cartesian_product) of all the values for all the features identified at step 1.\n",
    "3. For each of the settings, cross-validate it on the available training data.\n",
    "4. Choose the settings that did best in step 3, train on all the training data using those settings, and then evaluate that model on the test set.\n",
    "\n",
    "This is very demanding. First, The number of settings grows quickly with the number of hyperparameters and values. If hyperparameter $h_{1}$ has $5$ values and hyperparameter $h_{2}$ has $10$, then the number of settings is $5 \\cdot 10 = 50$. If we add a third hyperparameter $h_{3}$ with just $2$ values, then the number jumps to $100$. Second, if you're doing 5-fold cross-validation, then each model is trained 5 times. You're thus committed to training $500$ models.\n",
    "\n",
    "And it could get worse. Suppose you don't have a fixed train/test split, and you're instead reporting, say, the result of 10 random train/test splits. Strictly speaking, the optimal hyperparameters could be different for different splits. Thus, for each split, the above cross-validation should be conducted. Now you're committed to training $5,000$ systems!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Practical considerations, and some compromises\n",
    "\n",
    "The above is untenable as a set of laws for the scientific community. If we adopted it, then complex models trained on large datasets would end up disfavored, and only the very wealthy would be able to participate. Here are some pragmatic steps you can take to alleviate this problem, in descending order of attractiveness. (That is, the lower you go on this list, the more likely the skeptic is to complain!)\n",
    "\n",
    "1. [Bergstra and Bengio (2012)](http://www.jmlr.org/papers/v13/bergstra12a.html) argue that __randomly sampling__ from the space of hyperparameters delivers results like the full \"grid search\" described above with a relatively few number of samples. __Hyperparameter optimization algorithms__ like those implemented in [Hyperopt](http://hyperopt.github.io/hyperopt/) and [scikit-optimize](https://github.com/scikit-optimize/scikit-optimize) allow guided sampling from the full space. All these methods control the exponential growth in settings that comes from any serious look at one's hyperparameters. \n",
    "\n",
    "1. In large deep learning systems, __the hyperparameter search could be done on the basis of just a few iterations__. The systems likely won't have converged, but it's a solid working assumption that early performance is highly predictive of final performance. You might even be able to justify this with learning curves over these initial iterations.\n",
    "\n",
    "1. Not all hyperparameters will contribute equally to outcomes. Via heuristic exploration, it is typically possible to __identify the less informative ones and set them by hand__. As long as this is justified in the paper, it shouldn't rile the skeptic too much.\n",
    "\n",
    "1. Where repeated train/test splits are being run, one might __find optimal hyperparameters via a single split__ and use them for all the subsequent splits. This is justified if the splits are very similar.\n",
    "\n",
    "1. In the worst case, one might have to adopt hyperparameters that were optimal for other experiments that have been published. The skeptic will complain that these findings don't translate to your new data sets. That's true, but it could be the only option. For example, how would one compare against [Rajkomar et al. (2018)](https://arxiv.org/abs/1801.07860) who report that \"the performance of all above neural networks were [sic] tuned automatically using Google Vizier [35] with a total of >201,000 GPU hours\"?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Hyperparameter optimization tools\n",
    "\n",
    "* scikit-learn's [model_selection](http://scikit-learn.org/stable/modules/classes.html#module-sklearn.model_selection) package has classes `GridSearchCV` and `RandomizedSearchCV`. These are very easy to use. (We used `GridSearchCV` in our course code, in `utils.fit_classifier_with_hyperparameter_search`.)\n",
    "\n",
    "* [scikit-optimize](https://github.com/scikit-optimize/scikit-optimize) offers a variety of methods for guided search through the grid of hyperparameters. [This post](https://roamanalytics.com/2016/09/15/optimizing-the-hyperparameter-of-which-hyperparameter-optimizer-to-use/) assesses these methods against grid search and fully randomized search, and it also provides [starter code](https://github.com/roamanalytics/roamresearch/tree/master/BlogPosts/Hyperparameter_tuning_comparison) for using these implementations with sklearn-style classifiers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Classifier comparison\n",
    "\n",
    "Suppose you've assessed two classifier models. Their performance is probably different to some degree. What can be done to establish whether these models are different in any meaningful sense?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Practical differences\n",
    "\n",
    "One very simple step one can take is to simply count up how many examples the models actually differ on. \n",
    "\n",
    "* If the test set has 1,000 examples, then a difference of 1% in accuracy or F1 will correspond to roughly 10 examples. We'll likely have intuitions about whether that difference has any practical import. \n",
    "\n",
    "* If the test set has 1M examples, then 1% will correspond to 10,000 examples, which seems sure to matter. Unless other considerations (e.g., cost, understandability) favor the less accurate model, the choice seems clear.\n",
    "\n",
    "Even where the numbers suggest a practical difference, we might still wonder whether the difference is stable across different runs, and thus we might still want to gather more information."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Confidence intervals\n",
    "\n",
    "If you can afford to run the model multiple times, then reporting confidence intervals based on the resulting scores could suffice to build an argument about whether the models are meaningfully different.\n",
    "\n",
    "The following will calculate a simple 95% confidence interval for a vector of scores `vals`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_ci(vals):\n",
    "    if len(set(vals)) == 1:\n",
    "        return (vals[0], vals[0])\n",
    "    loc = np.mean(vals)\n",
    "    scale = np.std(vals) / np.sqrt(len(vals))\n",
    "    return stats.t.interval(0.95, len(vals)-1, loc=loc, scale=scale)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's very likely that these confidence intervals will look very large relative to the variation that you actually observe. You probably can afford to do no more than 10–20 runs. Even if your model is performing very predictably over these runs (which it will, assuming your method for creating the splits is sound), the above intervals will be large in this situation. This might justify bootstrapping the confidence intervals. I recommend [scikits-bootstrap](https://github.com/cgevans/scikits-bootstrap) for this.\n",
    "\n",
    "__Important__: when evaluating multiple systems via repeated train/test splits or cross-validation, all the systems have to be run on the same splits. This is the only way to ensure that all the systems face the same challenges."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Wilcoxon signed-rank test\n",
    "\n",
    "NLPers always choose tables over plots for some reason, and confidence intervals are hard to display in tables. This might mean that you want to calculate a p-value. \n",
    "\n",
    "Where you can afford to run the models at least 10 times with different splits (and preferably more like 20), [Demšar (2006)](http://www.jmlr.org/papers/v7/demsar06a.html) recommends the [Wilcoxon signed-rank test](https://en.wikipedia.org/wiki/Wilcoxon_signed-rank_test). This is implemented in scipy as [scipy.stats.wilcoxon](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.wilcoxon.html). This test relies only on the absolute differences between scores for each split and makes no assumptions about how the scores are distributed.\n",
    "\n",
    "Take care not to confuse this with [scipy.stats.ranksums](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.ranksums.html), which does the Wilcoxon rank-sums test. This is also known as the [Mann–Whitney U test](https://en.wikipedia.org/wiki/Mann–Whitney_U_test), though SciPy distinguishes this as a separate test ([scipy.stats.mannwhitneyu](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.mannwhitneyu.html#scipy.stats.mannwhitneyu)). In any case, the heart of this is that the signed-rank variant is more appropriate for classifier assessments, where we are always comparing systems trained and assessed on the same underlying pool of data.\n",
    "\n",
    "Like all tests of this form, we should be aware of what they can tell us and what they can't: \n",
    "\n",
    "* The test says __nothing__ about the practical importance of any differences observed. \n",
    "\n",
    "* __Small p-values do not reliably indicate large effect sizes__. (A small p-value will more strongly reflect the number of samples you have.)\n",
    "\n",
    "* Large p-values simply mean that the available evidence doesn't support a conclusion that the systems are different, not that there is no difference in fact. And even that limited conclusion is only relative to this particular, quite conservative test. \n",
    "\n",
    "All this is to say that these values should not be asked to stand on their own, but rather presented as part of a larger, evidence-driven argument."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### McNemar's test\n",
    "\n",
    "[McNemar's test](https://en.wikipedia.org/wiki/McNemar%27s_test) operates directly on the vectors of predictions for the two models being compared. As such, it doesn't require repeated runs, which is good where optimization is expensive.\n",
    "\n",
    "The basis for the test is a contingency table with the following form, for two models A and B:\n",
    "\n",
    "$$\\begin{array}{|c | c |}\n",
    "\\hline\n",
    "\\textrm{number of examples}        & \\textrm{number of examples} \\\\\n",
    "\\textrm{where A and B are correct} & \\textrm{where A is correct, B incorrect} \n",
    "\\\\\\hline\n",
    "\\textrm{number of examples}        & \\textrm{number of examples} \\\\\n",
    "\\textrm{where A is correct, B incorrect} & \\textrm{where both A and B are incorrect} \\\\\\hline\n",
    "\\end{array}$$\n",
    "\n",
    "Following [Dietterich (1998)](http://sci2s.ugr.es/keel/pdf/algorithm/articulo/dietterich1998.pdf), let the above be abbreviated to\n",
    "\n",
    "$$\\begin{array}{|c | c |}\n",
    "\\hline\n",
    "n_{11} & n_{10}\n",
    "\\\\\\hline\n",
    "n_{01} & n_{00} \\\\\n",
    "\\hline\n",
    "\\end{array}$$\n",
    "\n",
    "The null hypothesis tested is that the two models have the same error rate, i.e., that $n_{01} = n_{10}$. The test statistic is\n",
    "\n",
    "$$\n",
    "\\frac{\n",
    "    \\left(|(n_{01} - n_{10}| - 1\\right)^{2}\n",
    "}{\n",
    "    n_{01} + n_{10}\n",
    "}$$\n",
    "\n",
    "which has an approximately chi-squared distribution with 1 degree of freedom. \n",
    "\n",
    "An implementation is available in this repository: `utils.mcnemar`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Assessing models without convergence\n",
    "\n",
    "When working with linear models, convergence issues rarely arise. Typically, the implementation has a fixed number of iterations it performs, or a threshold on the error, and the model stops when it reaches one of these points. We mostly don't reflect on this because of the speed and stability of these models.\n",
    "\n",
    "With neural networks, convergence takes center stage. The models rarely converge, or they converge at different rates between runs, and their performance on the test data is often heavily dependent on these differences. Sometimes a model with a low final error turns out to be great, and sometimes it turns out to be worse than one that finished with a higher error. Who knows?!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Incremental dev set testing\n",
    "\n",
    "The key to addressing this uncertainty is to __regularly collect information about dev set performance as part of training__. For example, after every epoch, one could make predictions on the dev set and store that vector of predictions, or just whatever assessment metric one is using. These assessments can provide direct information about how the model is doing on the actual task we care about, which will be a better indicator than the errors.\n",
    "\n",
    "All the PyTorch models for this course accept a keyword argument `early_stopping`. The behavior should closely resemble that of `sklearn.neural_network` models. If `early_stopping=True`, then part of the dataset given to the `fit` method is reserved for incremental testing. The amount can be controlled with `validation_fraction` (default: `0.10`). After every epoch, this data will be used to evaluate the model using its `score` method. The parameters of the best model are stored. If an improvement of more than `tol` (default: `1e-5`) isn't seen within `n_iter_no_change` steps (default: `10`), then optimization stops, and the parameters of the numerically best model seen are used as the final model.\n",
    "\n",
    "It's important to see just how different this dev set performance can be from the training loss. In particular, the training loss can continue to go down even as the model grows worse and worse in evaluations on held-out data. This is a common form of __over-fitting__."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Dataset to illustrate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_toy, y_toy = make_classification(\n",
    "    n_samples=1000, n_classes=3, \n",
    "    n_informative=10, n_features=50, \n",
    "    weights=[0.2, 0.2, 0.6],\n",
    "    random_state=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_toy_train, X_toy_test, y_toy_train, y_toy_test = train_test_split(\n",
    "    X_toy, y_toy, test_size=0.20, stratify=y_toy, random_state=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Model without early stopping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "mod_no_stopping = TorchShallowNeuralClassifier(\n",
    "    early_stopping=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Finished epoch 1000 of 1000; error is 0.007025938481092453"
     ]
    }
   ],
   "source": [
    "_ = mod_no_stopping.fit(X_toy_train, y_toy_train)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "              precision    recall  f1-score   support\n",
      "\n",
      "           0      0.600     0.585     0.593        41\n",
      "           1      0.674     0.725     0.699        40\n",
      "           2      0.821     0.807     0.814       119\n",
      "\n",
      "    accuracy                          0.745       200\n",
      "   macro avg      0.698     0.706     0.702       200\n",
      "weighted avg      0.746     0.745     0.745       200\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(classification_report(y_toy_test, mod_no_stopping.predict(X_toy_test), digits=3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Model with early stopping"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "mod_stopping = TorchShallowNeuralClassifier(\n",
    "    early_stopping=True,\n",
    "    n_iter_no_change=50)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Stopping after epoch 131. Validation score did not improve by tol=1e-05 for more than 50 epochs. Final error is 0.2840419411659241"
     ]
    }
   ],
   "source": [
    "_ = mod_stopping.fit(X_toy_train, y_toy_train)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "              precision    recall  f1-score   support\n",
      "\n",
      "           0      0.615     0.585     0.600        41\n",
      "           1      0.700     0.700     0.700        40\n",
      "           2      0.843     0.857     0.850       119\n",
      "\n",
      "    accuracy                          0.770       200\n",
      "   macro avg      0.719     0.714     0.717       200\n",
      "weighted avg      0.768     0.770     0.769       200\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(classification_report(y_toy_test, mod_stopping.predict(X_toy_test), digits=3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "#### Errors vs. incremental performance"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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EvFevkpYytv+TyamcXr98StlN7xOt/VcG9ffExFR1+bp6dnsA/rCwkLI5XK4uLi0ep9CoYCDg4PeYcz+vBXd/45c5lZ0RESkI1oi7+rqCplM1mJH/NcR9b8SBAFr1qzBtGnTYGlpqfdea537jZ5pah17ZzueVQag7dPqm0Q3Xp+SVaobKfkrVVUtMosqAQC9fFjojoiIbi4uLg5JSUl653766SfExsbCwuLmO6uYkvF9fOBoY4Grpdexh1vRERFRI9ESeUtLS8TExDTriJOSkhAfH3/De/ft24eLFy9i1qxZzd5rrXO/2TOpdU2F7qINTOSjfBxgKZOiuLIGWSVVLV5zMqcMQMO2dk62li1eQ0RE5q2iogKpqalITU0F0LC9XGpqqm4Xm0WLFmH69Om66+fMmYMrV65g4cKFOHv2LNasWYPVq1fjmWeeESP8DmVtKcPkfg1b0a0+mClyNEREZCxEnVq/cOFCfPrpp1izZg3Onj2Lp59+GllZWZgzZw6A5h13k9WrV2PAgAGIiopq9t78+fPx008/4c0338S5c+fw5ptvYvfu3ViwYEFHN8cslVfX4nzj1nB9AxwNulchlyHSp2F2Q2vr5HXT6n05Gk9E1FUdO3YM0dHRiI6OBtDw+0F0dDReeuklAA11cf68NW1QUBC2b9+OvXv3ok+fPnj11Vfx3nvv4f777xcl/o42Iz4AcqkERzNLdHVliIioa5OL+cUnTZqE4uJiLF26FHl5eYiKisL27dt1Vej/2nEDgEqlwubNm/Huu++2+Mz4+Hhs3LgRL7zwAl588UUEBwdj06ZNGDBgQIe3xxydyFZBEABfJ2u42xu+NVxffyekZJXh+JUy3Bft28LzywCw0B0RUVd21113tboEC2ioi/NXd955J44fP96BURkPL6U17untja0pOfjkQCbefzBa7JCIiEhkoibyADB37lzMnTu3xfda6riVSiWqqlqept3kgQcewAMPPNAe4XV5x3X7xxs2rb5JX38nrEbmTUfke7PQHRERUatmJwRha0oOtp/Kw/NjwuDjaC12SEREJCLRq9aTcfsjkXe8pfubpuOfyy9HVU2d3nuF6mrkq6shlTSspyciIqKWRXorER/sgnqtgLVcK09E1OUxkadWabUCUhor1hta6K6Jl9IaXkor1GsFnMhW6b13onE0PsTdHjaWok8OISIi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5557hEceeaR9GkxERNTFsK8nMi9cI09EAIAhQ4Zg5cqVeuecnZ11f46Li9N7Ly4uDqmpqQCAs2fPonfv3rC1tdW9P2jQIGi1Wpw/fx4SiQS5ubkYNmzYDWPo1auX7s+2trawt7dHYWEhAODxxx/H/fffj+PHj2PkyJGYMGEC4uPjb6mtREREXRH7eiLzwUSeiAA0dKZ/nf52MxKJBAAgCILuzy1dY21t3abnWVhYNLtXq9UCAMaMGYMrV67gxx9/xO7duzFs2DA88cQTeOeddwyKmYiIqKtiX09kPrhGnoja5Ndff232OiwsDAAQERGB1NRUVFZW6t4/dOgQpFIpQkNDYW9vj8DAQOzZs+e2YnBzc8PDDz+ML774AomJiVi1atVtPY+IiIj+wL6eyHRwRJ6IAAAajQb5+fl65+Ryua7IzNdff43Y2FjccccdWL9+PX777TesXr0aADBlyhS8/PLLmDFjBl555RVcu3YNTz31FKZNmwYPDw8AwCuvvII5c+bA3d0dY8aMQXl5OQ4dOoSnnnqqTfG99NJLiImJQWRkJDQaDX744QeEh4e343eAiIjIvLGvJzIfTOSJCACwc+dOeHl56Z3r0aMHzp07B6ChyuzGjRsxd+5ceHp6Yv369YiIiAAA2NjYYNeuXZg/fz769esHGxsb3H///Vi+fLnuWTNmzEB1dTX++9//4plnnoGrqyseeOCBNsdnaWmJRYsW4fLly7C2tkZCQgI2btzYDi0nIiLqGtjXE5kPiSAIgthBEJFxk0gk2Lp1KyZMmCB2KERERNQB2NcTmRaukSciIiIiIiIyIUzkiYiIiIiIiEwIp9YTERERERERmRCOyBMRERERERGZECbyRERERERERCaEiTwRERERERGRCWEiT0RERERERGRCmMgTERERERERmRAm8kREREREREQmhIk8ERERERERkQlhIk9ERERERERkQpjIExEREREREZmQ/wcALlg9v0eAmQAAAABJRU5ErkJggg==\n",
      "text/plain": [
       "<Figure size 1200x400 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scores = mod_stopping.validation_scores\n",
    "errors = mod_no_stopping.errors[: len(scores)]\n",
    "\n",
    "fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))\n",
    "\n",
    "ax1 = pd.Series(scores).plot(ax=ax1)\n",
    "ax1.set_xlabel(\"Epochs\")\n",
    "ax1.set_ylabel(\"Macro F1 score\")\n",
    "\n",
    "ax2 = pd.Series(errors).plot(ax=ax2)\n",
    "ax2.set_xlabel(\"Epochs\")\n",
    "_ = ax2.set_ylabel(\"Error\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Learning curves with confidence intervals\n",
    "\n",
    "I frankly think the best response to all this is to accept that incremental performance plots like the above are how we should be assessing our models. This exposes all of the variation that we actually observe. \n",
    "\n",
    "In addition, in deep learning, we're often dealing with classes of models that are in principle capable of learning anything. The real question is implicitly how efficiently they can learn given the available data and other resources. Learning curves bring this our very clearly.\n",
    "\n",
    "We can improve the curves by adding confidence intervals to them derived from repeated runs. Here's a plot from a paper I wrote with Nick Dingwall ([Dingwall and Potts 2018](https://arxiv.org/abs/1803.09901)):\n",
    "\n",
    "<img src=\"fig/diagnosis-curve.png\" />\n",
    "\n",
    "I think this shows very clearly that, once all is said and done, the Mittens model (red) learns faster than the others, but is indistinguishable from the Clinical text GloVe model (blue) after enough training time. Furthermore, it's clear that the other two models are never going to catch up in the current experimental setting. A lot of this information would be lost if, for example, we decided to stop training when dev set performance reached its peak and report only a single F1 score per class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## The role of random parameter initialization\n",
    "\n",
    "Most deep learning models have their parameters initialized randomly, perhaps according to some heuristics related to the number of parameters ([Glorot and Bengio 2010](http://proceedings.mlr.press/v9/glorot10a.html)) or their internal structure ([Saxe et al. 2014](https://arxiv.org/abs/1312.6120)). This is meaningful largely because of the non-convex optimization problems that these models define, but it can impact simpler models that have multiple optimal solutions that still differ at test time. \n",
    "\n",
    "There is growing awareness that these random choices have serious consequences. For instance, [Reimers and Gurevych (2017)](https://www.aclweb.org/anthology/D17-1035) report that different initializations for neural sequence models can lead to statistically significant results, and they show that a number of recent systems are indistinguishable in terms of raw performance once this source of variation is taken into account.\n",
    "\n",
    "This shouldn't surprise practitioners, who have long struggled with the question of what to do when a system experiences a catastrophic failure as a result of unlucky initialization. (I think the answer is to report this failure rate.)\n",
    "\n",
    "The code snippet below lets you experience this phenomenon for yourself. The XOR logic operator, which is true just in case its two arguments have the same value, is famously not learnable by a linear classifier but within reach of a neural network with a single hidden layer and a non-linear activation function ([Rumelhart et al. 1986](https://www.nature.com/articles/323533a0)). But how consistently do such models actually learn XOR? No matter what settings you choose, you rarely if ever see perfect performance across multiple runs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Finished epoch 500 of 500; error is 0.009758551605045795"
     ]
    },
    {
     "data": {
      "text/plain": [
       "defaultdict(int, {'incorrect': 5, 'correct': 5})"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def xor_eval(n_trials=10):\n",
    "    xor = [\n",
    "        ([1.,1.], 1),\n",
    "        ([1.,0.], 0),\n",
    "        ([0.,1.], 0),\n",
    "        ([0.,0.], 1)]\n",
    "    X, y = zip(*xor)\n",
    "    results = defaultdict(int)\n",
    "    for trial in range(n_trials):\n",
    "        model = TorchShallowNeuralClassifier(\n",
    "            hidden_dim=2,\n",
    "            max_iter=500,\n",
    "            eta=0.01)\n",
    "        model.fit(X, y)\n",
    "        preds = tuple(model.predict(X))\n",
    "        result = 'correct' if preds == y else 'incorrect'\n",
    "        results[result] += 1\n",
    "    return results\n",
    "\n",
    "xor_eval(n_trials=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "For better or worse, the only response we have to this situation is to __report scores for multiple complete runs of a model with different randomly chosen initializations__. [Confidence intervals](#Confidence-intervals) and [statistical tests](#Wilcoxon-signed-rank-test) can be used to summarize the variation observed. If the evaluation regime already involves comparing the results of multiple train/test splits, then ensuring a new random initializing for each of those would seem sufficient.\n",
    "\n",
    "Arguably, these observations are incompatible with evaluation regimes involving only a single train/test split, as in [McNemar's test](#McNemar's-test). However, [as discussed above](#Practical-considerations,-and-some-compromises), we have to be realistic. If multiple run aren't feasible, then a more heuristic argument will be needed to try to convince skeptics that the differences observed are larger than we would expect from just different random initializations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Closing remarks\n",
    "\n",
    "We can summarize most of the above with a few key ideas:\n",
    "    \n",
    "1. Your evaluation should be based around a few systems that are related in ways that illuminate your hypotheses and help to convey what the best models are learning.\n",
    "\n",
    "1. Every model you assess should be given its best chance to shine (but we need to be realistic about how many experiments this entails!).\n",
    "\n",
    "1. The test set should play no role whatsoever in optimization or model selection. The best way to ensure this is to have the test set locked away until the final batch of experiments that will be reported in the paper, but this separation is simulated adequately by careful cross-validation set-ups.\n",
    "\n",
    "1. Strive to base your model comparisons in multiple runs on the same splits. This is especially important for deep learning, where a single model can perform in very different ways on the same data, depending on the vagaries of optimization."
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}