Quick-Start.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quick-Start Guide\n",
    "\n",
    "This documents presents an overview of how to run a simple example using the `Minas` classifier. It was implemented by extending the base estimator from `scikit-multiflow`, so it works similarly to the popular `scikit-learn` API.\n",
    "\n",
    "The `Minas` classifier defines the following methods:\n",
    "\n",
    "- `fit` – Trains a model in the offline phase, in a batch fashion.\n",
    "- `partial_fit` – Incrementally trains the stream model.\n",
    "- `predict` – Predicts the target’s value.\n",
    "\n",
    "## Train and test a stream classification model using `Minas`\n",
    "\n",
    "1. Before we start, we have to import the classifier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from minas import Minas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "2. Create a stream\n",
    "\n",
    "We create a stream using `RandomRBFGenerator`, the Random Radial Basis Function stream generator from `scikit-multiflow`. In this example, we will create a data stream with 3 classes, 4 features, and 6 centroids.\n",
    "\n",
    "Also, before using the stream, we need to prepare it by calling `prepare_for_use()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from skmultiflow.data.random_rbf_generator import RandomRBFGenerator\n",
    "\n",
    "stream = RandomRBFGenerator(model_random_state=123,\n",
    "                            sample_random_state=12,\n",
    "                            n_classes=3,\n",
    "                            n_features=4,\n",
    "                            n_centroids=6)\n",
    "stream.prepare_for_use()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "3. Instantiate the `Minas` classifier\n",
    "\n",
    "The classifier takes the following parameters:\n",
    "\n",
    "- `kini`: Number of clusters for each class to be found during clustering (offline phase and novelty detection process).\n",
    "- `cluster_algorithm`: A string containing the clustering algorithm to use. Currently only supports `'kmeans'`.\n",
    "- `random_state`: Seed to use for random number generation.\n",
    "- `min_short_mem_trigger`: Minimum number of samples in the short term memory required to trigger a novelty detection process.\n",
    "- `min_examples_cluster`: Minimum number of examples required to form a cluster.\n",
    "- `threshold_strategy`: Strategy used to compute the threshold for differentiating between novelty classes and concept extensions. Accepts `1`, `2`, or `3`. The strategies are defined in the [MINAS paper](http://www.liaad.up.pt/area/jgama/MINAS.pdf).\n",
    "- `threshold_factor`: Factor to use for calculating thresholds.\n",
    "- `window_size`: Window size (an integer representing the number of samples) used by the forgetting mechanism.\n",
    "- `update_summary`: Defaults to `False`. If `True`, the summary statistics for a cluster are updated when a new point is added to it.\n",
    "- `animation`: Defaults to `False`. If `True`, a plot is created showing the current state of the model (points and clusters). It only works if the examples have two dimensions.\n",
    "\n",
    "For this example, we will set 10 clusters per class, with at least 30 examples required in the short term memory before triggering a novelty detection procedure, and a minimum of 10 examples per cluster."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "clf = Minas(kini=10,\n",
    "            min_short_mem_trigger=30,\n",
    "            min_examples_cluster=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "4. Get data from the stream\n",
    "\n",
    "Next, we will get the data from the stream. For this example, we use 500 samples to train our model in the offline phase. Then, we will use the next 500 samples for the online phase."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "n_samples = 1000\n",
    "offline_size = 500\n",
    "\n",
    "X_all, y_all = stream.next_sample(n_samples)\n",
    "X_train = X_all[:offline_size]\n",
    "y_train = y_all[:offline_size]\n",
    "X_test = X_all[offline_size:n_samples]\n",
    "y_test = y_all[offline_size:n_samples]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "5. Offline phase\n",
    "\n",
    "The next step corresponds to the offline phase. We run it by calling `fit()` with the training data from the last step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# OFFLINE phase\n",
    "clf.fit(X_train, y_train)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "6. Online phase\n",
    "\n",
    "Now we get to the online phase. We feed each example at a time to the model, and collect the results from the `predict()` calls. In each iteration, we call `partial_fit()` to update the model with the data from the sample it has just seen."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# ONLINE phase\n",
    "y_preds = []\n",
    "for X, y in zip(X_test, y_test):\n",
    "    y_preds.append(clf.predict([X])[0])\n",
    "    clf.partial_fit([X], [y])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "7. Evaluate performance\n",
    "\n",
    "Finally, we will see how our model performed. We create a confusion matrix with the following definition:\n",
    "\n",
    "- Each row represents the true label of the examples from the stream seen during the online phase.\n",
    "- Each column represents the label predicted by the model. The numbers greater than the maximum labels shown in the rows represent the novelty patterns detected. Unknown samples are represented by `-1`.\n",
    "\n",
    "In the confusion matrix below, for our example, the labels from our data set are 0, 1, and 2. The columns 3, 4, and 5 represent 3 novelty patterns discovered by the model. We can see that the model identified classes 0 and 2 quite well, and had more trouble distinguishing examples from class 1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "clf.confusion_matrix(X_test, y_test)"
   ]
  }
 ],
 "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}