code/demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# ROCKET"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dempster A, Petitjean F, Webb GI (2019) ROCKET: Exceptionally fast and accurate time series classification using random convolutional kernels. [arXiv:1910.13051](https://arxiv.org/abs/1910.13051)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "1. [Overview](#1-Overview)\n",
    "2. [Requirements](#2-Requirements)\n",
    "3. [Basic Use](#3-Basic-Use)\n",
    "4. [Worked Example](#4-Worked-Example)\n",
    "5. [Reproducing the Experiments](#5-Reproducing-the-Experiments)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1 Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "ROCKET transforms time series using random convolutional kernels (random length, weights, bias, dilation, and padding).  ROCKET computes two features from the resulting feature maps: the max, and the proportion of positive values (or *ppv*).  The transformed features are used to train a linear classifier.\n",
    "\n",
    "ROCKET is implemented in Python, using just-in-time compilation via Numba."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2 Requirements"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To use ROCKET, you will need:\n",
    "\n",
    "* Python (3.7+);\n",
    "* Numba (0.45.1+);\n",
    "* NumPy;\n",
    "* scikit-learn (or equivalent).\n",
    "\n",
    "All of these should be ready to go in [Anaconda](https://www.anaconda.com/distribution/).\n",
    "\n",
    "For `reproduce_experiments_bakeoff.py`, we also use pandas (included in Anaconda).\n",
    "\n",
    "For `reproduce_experiments_scalability.py`, you will also need [PyTorch](https://pytorch.org/) (1.2+)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3 Basic Use"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Basic use follows this pattern:\n",
    "\n",
    "```python\n",
    "# (1) generate random kernels\n",
    "kernels = generate_kernels(input_length = X_training.shape[1], num_kernels = 10_000)\n",
    "\n",
    "# (2) transform the training data and train a classifier\n",
    "X_training_transform = apply_kernels(X = X_training, kernels = kernels)\n",
    "classifier.fit(X_training_transform, Y_training)\n",
    "\n",
    "# (3) transform the test data and use the classifier\n",
    "X_test_transform = apply_kernels(X = X_test, kernels = kernels)\n",
    "classifier.predict(X_test_transform)\n",
    "```\n",
    "\n",
    "**Note**: Time series should be normalised to have a zero mean and unit standard deviation before using `apply_kernels(...)`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4 Worked Example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.1 Import ROCKET\n",
    "\n",
    "Import the ROCKET functions `generate_kernels(...)`, to generate the random kernels, and `apply_kernels(...)`, to transform the data using the generated kernels; NumPy, to handle the data; and a classifier (here, we use `RidgeClassifierCV` from scikit-learn)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "from sklearn.linear_model import RidgeClassifierCV\n",
    "\n",
    "from rocket_functions import generate_kernels, apply_kernels"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.2 Load the Training Data\n",
    "\n",
    "Load the training data (here, we use the txt version of the 'coffee' dataset from [timeseriesclassification.com](http://www.timeseriesclassification.com))."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "training_data = np.loadtxt(\"coffee_TRAIN.txt\")\n",
    "Y_training, X_training = training_data[:, 0].astype(np.int), training_data[:, 1:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.3 (Optional) Precompile ROCKET Functions\n",
    "\n",
    "Numba provides just-in-time compilation.  For various reasons, we might want to compile the ROCKET functions, `generate_kernels(...)` and `apply_kernels(...)`, before using them.  One way of doing this (i.e., 'forcing' Numba to compile the functions) is as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "# generate \"dummy\" kernels -> compiles *generate_kernels(...)*\n",
    "_ = generate_kernels(100, 10)\n",
    "\n",
    "# apply \"dummy\" kernels to \"dummy\" data -> compiles *apply_kernels(...)*\n",
    "_ = apply_kernels(np.zeros_like(training_data)[:, 1:], _)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.4 Generate Kernels\n",
    "\n",
    "Generate random kernels using `generate_kernels(input_length, num_kernels)`, where `input_length` is the length of the time series, and `num_kernels` is the number of random kernels to generate (here, we generate 100; in our experiments, we use 10,000)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "kernels = generate_kernels(X_training.shape[1], 100)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.5 Transform the Training Data\n",
    "\n",
    "Transform the training data using `apply_kernels(X, kernels)` where `X` are the time series (NumPy array of shape `[num_examples, input_length]`), and `kernels` are the kernels generated using `generate_kernels(...)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_training_transform = apply_kernels(X_training, kernels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: Unless already normalised (time series may already be normalised for some datasets), time series should be normalised to have a zero mean and unit standard deviation before using `apply_kernels(...)`.  For example:\n",
    "\n",
    "```python\n",
    "# (1) if not already normalised, normalise time series\n",
    "X_training = (X_training - X_training.mean(axis = 1, keepdims = True)) / X_training.std(axis = 1, keepdims = True)\n",
    "\n",
    "# (2) then transform the normalised time series\n",
    "X_training_transform = apply_kernels(X_training, kernels)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.6 Train a Classifier\n",
    "\n",
    "Train a classifier using the transformed features (here, we use `RidgeClassifierCV` from scikit-learn, our suggested classifier for smaller datasets)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "classifier = RidgeClassifierCV(alphas = np.logspace(-3, 3, 10), normalize = True)\n",
    "classifier.fit(X_training_transform, Y_training)\n",
    "\n",
    "print(end = \"\") # suppress print output of classifier.fit(...)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.7 Load the Test Data\n",
    "\n",
    "Load the test data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "test_data = np.loadtxt(\"coffee_TEST.txt\")\n",
    "Y_test, X_test = test_data[:, 0].astype(np.int), test_data[:, 1:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.8 Transform the Test Data\n",
    "\n",
    "Transform the test data using `apply_kernels(...)`, as for the training data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "X_test_transform = apply_kernels(X_test, kernels)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note**: As for the training data, unless already normalised, time series should be normalised to have a zero mean and unit standard deviation before using `apply_kernels(...)` (see 4.5, above)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.9 Classify the Test Data\n",
    "\n",
    "Classify the (transformed) test data using the trained classifer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "predictions = 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1\n",
      "accuracy    = 1.0\n"
     ]
    }
   ],
   "source": [
    "predictions = classifier.predict(X_test_transform)\n",
    "\n",
    "print(f\"predictions = {', '.join(predictions.astype(str))}\")\n",
    "print(f\"accuracy    = {(predictions == Y_test).mean()}\") # or classifier.score(X_test_transform, Y_test)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 5 Reproducing the Experiments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## UCR Archive"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 'Bake Off' Datasets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`reproduce_experiments_bakeoff.py` is intended to allow for reproduction of the experiments on the 'bake off' datasets (using the txt versions of the 'bake off' datasets from [timeseriesclassification.com](http://www.timeseriesclassification.com)).\n",
    "\n",
    "The required arguments are:\n",
    "* `-i` or `--input_path`, the parent directory for the datasets (probably something like`.../Univariate_arff/`); and\n",
    "* `-o` or `--output_path`, the directory in which to save the results.\n",
    "\n",
    "The optional arguments are:\n",
    "* `-n` or `--num_runs`, the number of runs (default 10); and\n",
    "* `-k` or `--num_kernels`, the number of kernels (default 10,000).\n",
    "\n",
    "As ROCKET is nondeterministic, results will differ between runs.  However, any single run should produce representative results.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```bash\n",
    "python reproduce_experiments_bakeoff.py -i ./Univariate_arff/ -o ./\n",
    "python reproduce_experiments_bakeoff.py -i ./Univariate_arff/ -o ./ -n 1 -k 100\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Additional 2018 Datasets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*(Forthcoming...)*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Scalability"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`reproduce_experiments_scalability.py` is intended to:\n",
    "\n",
    "* allow for reproduction of the scalability experiments (in terms of dataset size); and\n",
    "* serve as a template for integrating ROCKET with logistic / softmax regression and stochastic gradient descent (or, e.g., Adam) for other large datasets using PyTorch.\n",
    "\n",
    "The required arguments are:\n",
    "\n",
    "* `-tr` or `--training_path`, the training dataset (csv);\n",
    "* `-te` or `--test_path`, the test dataset (csv);\n",
    "* `-o` or `--output_path`, the directory in which to save the results;\n",
    "* `-k` or `--num_kernels`, the number of kernels.\n",
    "\n",
    "**Note**: It may be necessary to adapt the code to your dataset in terms of dataset size and structure, regularisation, etc.\n",
    "\n",
    "Examples:\n",
    "\n",
    "```bash\n",
    "python reproduce_experiments_scalability.py -tr training_data.csv -te test_data.csv -o ./ -k 100\n",
    "python reproduce_experiments_scalability.py -tr training_data.csv -te test_data.csv -o ./ -k 1_000\n",
    "python reproduce_experiments_scalability.py -tr training_data.csv -te test_data.csv -o ./ -k 10_000\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}