tutorials/advanced/modelling/deep_learning_models.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Deep learning models\n",
    "In the other tutorials, all examples have used scikit-learn models. However,\n",
    "QSPRpred also has a number of other deep-learning models build-in. These models rely on\n",
    "torch, therefore you need to make sure to have torch or installed QSPPred with the `deep` (or `full`) option (see [README.txt](https://github.com/CDDLeiden/QSPRpred#readme)).\n",
    "\n",
    "First, we will load the dataset as usual."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Failed to find the pandas get_adjustment() function to patch\n",
      "Failed to patch pandas - PandasTools will have limited functionality\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>SMILES</th>\n",
       "      <th>pchembl_value_Mean</th>\n",
       "      <th>Year</th>\n",
       "      <th>QSPRID</th>\n",
       "      <th>pchembl_value_Mean_original</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>QSPRID</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>DeepLearningTutorialDataset_0000</th>\n",
       "      <td>Cc1cc(C)n(-c2cc(NC(=O)CCN(C)C)nc(-c3ccc(C)o3)n...</td>\n",
       "      <td>8.68</td>\n",
       "      <td>2008.0</td>\n",
       "      <td>DeepLearningTutorialDataset_0000</td>\n",
       "      <td>8.68</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DeepLearningTutorialDataset_0001</th>\n",
       "      <td>Nc1c(C(=O)Nc2ccc([N+](=O)[O-])cc2)sc2nc3c(cc12...</td>\n",
       "      <td>4.82</td>\n",
       "      <td>2010.0</td>\n",
       "      <td>DeepLearningTutorialDataset_0001</td>\n",
       "      <td>4.82</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DeepLearningTutorialDataset_0002</th>\n",
       "      <td>O=C(Nc1nc2ncccc2n2c(=O)n(-c3ccccc3)nc12)c1ccccc1</td>\n",
       "      <td>5.65</td>\n",
       "      <td>2009.0</td>\n",
       "      <td>DeepLearningTutorialDataset_0002</td>\n",
       "      <td>5.65</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DeepLearningTutorialDataset_0003</th>\n",
       "      <td>CNC(=O)C12CC1C(n1cnc3c(NCc4cccc(Cl)c4)nc(C#CCC...</td>\n",
       "      <td>5.45</td>\n",
       "      <td>2009.0</td>\n",
       "      <td>DeepLearningTutorialDataset_0003</td>\n",
       "      <td>5.45</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>DeepLearningTutorialDataset_0004</th>\n",
       "      <td>CCCn1c(=O)c2c(nc3cc(OC)ccn32)n(CCCNC(=O)c2ccc(...</td>\n",
       "      <td>5.20</td>\n",
       "      <td>2019.0</td>\n",
       "      <td>DeepLearningTutorialDataset_0004</td>\n",
       "      <td>5.20</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "                                                                             SMILES  \\\n",
       "QSPRID                                                                                \n",
       "DeepLearningTutorialDataset_0000  Cc1cc(C)n(-c2cc(NC(=O)CCN(C)C)nc(-c3ccc(C)o3)n...   \n",
       "DeepLearningTutorialDataset_0001  Nc1c(C(=O)Nc2ccc([N+](=O)[O-])cc2)sc2nc3c(cc12...   \n",
       "DeepLearningTutorialDataset_0002   O=C(Nc1nc2ncccc2n2c(=O)n(-c3ccccc3)nc12)c1ccccc1   \n",
       "DeepLearningTutorialDataset_0003  CNC(=O)C12CC1C(n1cnc3c(NCc4cccc(Cl)c4)nc(C#CCC...   \n",
       "DeepLearningTutorialDataset_0004  CCCn1c(=O)c2c(nc3cc(OC)ccn32)n(CCCNC(=O)c2ccc(...   \n",
       "\n",
       "                                  pchembl_value_Mean    Year  \\\n",
       "QSPRID                                                         \n",
       "DeepLearningTutorialDataset_0000                8.68  2008.0   \n",
       "DeepLearningTutorialDataset_0001                4.82  2010.0   \n",
       "DeepLearningTutorialDataset_0002                5.65  2009.0   \n",
       "DeepLearningTutorialDataset_0003                5.45  2009.0   \n",
       "DeepLearningTutorialDataset_0004                5.20  2019.0   \n",
       "\n",
       "                                                            QSPRID  \\\n",
       "QSPRID                                                               \n",
       "DeepLearningTutorialDataset_0000  DeepLearningTutorialDataset_0000   \n",
       "DeepLearningTutorialDataset_0001  DeepLearningTutorialDataset_0001   \n",
       "DeepLearningTutorialDataset_0002  DeepLearningTutorialDataset_0002   \n",
       "DeepLearningTutorialDataset_0003  DeepLearningTutorialDataset_0003   \n",
       "DeepLearningTutorialDataset_0004  DeepLearningTutorialDataset_0004   \n",
       "\n",
       "                                  pchembl_value_Mean_original  \n",
       "QSPRID                                                         \n",
       "DeepLearningTutorialDataset_0000                         8.68  \n",
       "DeepLearningTutorialDataset_0001                         4.82  \n",
       "DeepLearningTutorialDataset_0002                         5.65  \n",
       "DeepLearningTutorialDataset_0003                         5.45  \n",
       "DeepLearningTutorialDataset_0004                         5.20  "
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import os\n",
    "\n",
    "from qsprpred.data import QSPRDataset, RandomSplit\n",
    "from qsprpred.data.descriptors.fingerprints import MorganFP\n",
    "\n",
    "os.makedirs(\"../../tutorial_output/data\", exist_ok=True)\n",
    "\n",
    "# Create dataset\n",
    "dataset = QSPRDataset.fromTableFile(\n",
    "    filename=\"../../tutorial_data/A2A_LIGANDS.tsv\",\n",
    "    store_dir=\"../../tutorial_output/data\",\n",
    "    name=\"DeepLearningTutorialDataset\",\n",
    "    target_props=[{\"name\": \"pchembl_value_Mean\", \"task\": \"REGRESSION\"}],\n",
    "    random_state=42\n",
    ")\n",
    "\n",
    "# calculate compound features and split dataset into train and test\n",
    "dataset.prepareDataset(\n",
    "    split=RandomSplit(test_fraction=0.2, dataset=dataset),\n",
    "    feature_calculators=[MorganFP(radius=3, nBits=2048)],\n",
    "    recalculate_features=True,\n",
    ")\n",
    "\n",
    "dataset.getDF().head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fully connected neural network\n",
    "### Initialization\n",
    "The first model we will look at is a fully connected neural network. This model uses the `DDNModel` class instead of the `SklearnModel` class. The `DDNModel` class accepts a `patience` argument, which is the number of epochs to wait before stopping training if the validation loss does not improve and a tolerance ( `tol`) argument, which is the minimum improvement in validation loss to be considered an improvement.\n",
    "\n",
    "Other parameters for the underlying estimator `STFullyConnected` can be passed to the `parameters` argument as usual.\n",
    "There is no need to specify the `alg` argument, as currently only `STFullyConnected` is available."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "qsprpred - WARNING - Random state supplied, but alg <class 'qsprpred.extra.gpu.models.neural_network.STFullyConnected'> does not support it. Ignoring this setting.\n"
     ]
    }
   ],
   "source": [
    "# Create model\n",
    "from qsprpred.extra.gpu.models.dnn import DNNModel\n",
    "\n",
    "os.makedirs(\"../../tutorial_output/models\", exist_ok=True)\n",
    "model = DNNModel(\n",
    "    base_dir='../../tutorial_output/models',\n",
    "    name='DeepLearningTutorialModel',\n",
    "    parameters={'n_epochs': 100},  # maximum number of epochs to train for\n",
    "    patience=3,\n",
    "    tol=0.01,\n",
    "    random_state=42\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Early Stopping\n",
    "The `DNNModel` supports early stopping of the training, which as mentioned can be controlled by the `patience` and the `tol` arguments. You can check if a model supports early stopping, by checking the `supportsEarlyStopping` attribute."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.supportsEarlyStopping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The model can be trained as usual, but a part of the training set will be used as a validation set to determine wether to stop training. By default a random 10% of the training set is used as a validation set. This can be changed by setting the `split` argument of `QSPRModel.fit` to a different value, which can be any scikit-learn or QSPRpred `DataSplit`. See the [data splitting tutorial](../../basics/data/data_splitting.ipynb) for more information on the possibilities. Here, you can see how to change the validation split to a 20% random split."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([-1.58563831, -1.61295136, -1.75909456, -2.07876972, -1.38434467])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qsprpred.models import CrossValAssessor\n",
    "\n",
    "CrossValAssessor('r2')(model, dataset,\n",
    "                       split=RandomSplit(test_fraction=0.2, dataset=dataset))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a model supports early stopping, it also has an `EarlyStopping` attribute which is an instance of the `EarlyStopping` class that keeps track of the number of epochs trained. The `EarlyStopping` class has a `mode` attribute that sets how early stopping should be handled when fitting the estimator. It can be one of four modes: `EarlyStoppingMode.RECORDING`, `EarlyStoppingMode.NOT_RECORDING`, `EarlyStoppingMode.OPTIMAL`, `EarlyStoppingMode.FIXED`. You can find [a schematic overview](####early-stopping-modes-overview) of the different modes below.\n",
    "By default it is set to `EarlyStoppingMode.NOT_RECORDING`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<EarlyStoppingMode.NOT_RECORDING: 'NOT_RECORDING'>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.earlyStopping.mode"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this mode (`EarlyStoppingMode.NOT_RECORDING`), the `EarlyStopping` class will not keep track of at which epoch the training is stopped in a fit. In the `EarlyStoppingMode.RECORDING` mode the `EarlyStopping` class will keep track of the epoch on which the training was stopped. This can be accessed through the `EarlyStopping` class `trainedEpochs` attribute, which is a list of the epochs on which the training was stopped. You can see that for now it is just an empty list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.earlyStopping.trainedEpochs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we then run a cross-validation with the mode set to `EarlyStoppingMode.RECORDING`, we can see that the `trainedEpochs` attribute is now filled with the epochs on which the training was stopped for each fold."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[61, 51, 63, 34, 55]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qsprpred.models import EarlyStoppingMode\n",
    "\n",
    "CrossValAssessor('r2', mode=EarlyStoppingMode.RECORDING)(model, dataset)\n",
    "model.earlyStopping.trainedEpochs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Mind that the mode has now been changed to `EarlyStoppingMode.RECORDING`, therefore, if you run the cross-validation again, the `trainedEpochs` attribute will be appended with the epochs on which the training was stopped previously."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<EarlyStoppingMode.RECORDING: 'RECORDING'>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.earlyStopping.mode"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[61, 51, 63, 34, 55, 63, 51, 62, 34, 56]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "CrossValAssessor('r2')(model, dataset)\n",
    "model.earlyStopping.trainedEpochs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `EarlyStopping` class has an attribute `optimalEpochs`, which is an aggregation of the `trainedEpochs` attribute, calculated by the `aggregateFunc`, which by default is the arithmetric mean. You can change the `aggregateFunc` by passing a function to the `aggregateFunc` argument of the `EarlyStopping` class. For example, if you want to use the median instead of the mean, you can pass the `np.median` function to the `aggregateFunc` argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<function numpy.mean(a, axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.earlyStopping.aggregateFunc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "53"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.earlyStopping.optimalEpochs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "56"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "model.earlyStopping.aggregateFunc = np.median\n",
    "model.earlyStopping.optimalEpochs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we now fit the model with the `EarlyStoppingMode.OPTIMAL` mode, the estimator will be fitted for exactly `optimalEpochs`. This is the `EarlyStoppingMode` that is used by default for `QSPRModel.fitDataset`. This is done to avoid having to use a part of the dataset as validation set to determine the early stopping epoch in the final fit of the model. However, if you want to use a different mode, you can pass it to the `mode` argument of the `QSPRModel.fitDataset` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "_ = model.fitDataset(dataset)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also reset the recorded epochs with the `clean` function. If we then try to run fit attached with the `EarlyStoppingMode.OPTIMAL` mode, we get an error, because the `trainedEpochs` attribute is empty."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[]\n",
      "No number of epochs have been recorded yet, first run fit with early stopping mode set to RECORDING or set the optimal number of epochs manually.\n"
     ]
    }
   ],
   "source": [
    "model.earlyStopping.clean()\n",
    "print(model.earlyStopping.trainedEpochs)\n",
    "try:\n",
    "    model.fitDataset(dataset)\n",
    "except ValueError as e:\n",
    "    print(e)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another option is to forgo early stopping and just train for a fixed number of epochs. This can be done by setting the `mode` argument to `EarlyStoppingMode.FIXED` and `QSPRModel.earlyStopping.numEpochs` argument to the number of epochs to train for.\n",
    "Be aware, that if you `DNNModel` parameter `n_epochs` is set to a value smaller than `QSPRModel.earlyStopping.numEpochs`, the model will only be trained for `n_epochs` epochs, as this is the maximum number of epochs to train for.\n",
    "In this example, we will train the model for 10 epochs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "model.earlyStopping.numEpochs = 10\n",
    "_ = model.fitDataset(dataset, mode=EarlyStoppingMode.FIXED)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Early stopping modes overview\n",
    "![EarlyStopping.png](../../figures/EarlyStopping.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Training\n",
    "Below we will show a complete training of the DNN. First we run hyperparameter optimization to find the best parameters for the model. Here we will will use `EarlyStoppingMode.NOT_RECORDING` as the best epoch to stop training may depend on the hyper-parameters. Then we will apply cross-validation and test set evaluation to get an estimate of the performance of the model, with early stopping set to `EarlyStoppingMode.RECORDING`. Finally, we will use `QSPRModel.fitDataset` training for exactly the average number of epochs trained for in the cross-validation and the test set evaluation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[22, 20, 18, 19, 16, 18]\n",
      "19\n"
     ]
    }
   ],
   "source": [
    "from qsprpred.models import GridSearchOptimization, TestSetAssessor\n",
    "\n",
    "# Define the search space\n",
    "search_space = {\"lr\": [1e-4, 1e-3, ], \"neurons_h1\": [100, 200]}\n",
    "\n",
    "gridsearcher = GridSearchOptimization(\n",
    "    param_grid=search_space,\n",
    "    model_assessor=TestSetAssessor(\n",
    "        scoring='r2',\n",
    "        mode=EarlyStoppingMode.NOT_RECORDING\n",
    "    ),\n",
    ")\n",
    "gridsearcher.optimize(model, dataset)\n",
    "\n",
    "# Create a CrossValAssessor object\n",
    "CrossValAssessor('r2', mode=EarlyStoppingMode.RECORDING)(model, dataset)\n",
    "TestSetAssessor('r2', mode=EarlyStoppingMode.RECORDING)(model, dataset)\n",
    "\n",
    "model.earlyStopping.aggregateFunc = np.mean\n",
    "print(\n",
    "    model.earlyStopping.trainedEpochs)  # list of 6 values, one for each cross-validation fold and one for the test set\n",
    "print(model.earlyStopping.optimalEpochs)  # average of the 6 values\n",
    "\n",
    "# fit the model on the whole dataset\n",
    "_ = model.fitDataset(dataset, mode=EarlyStoppingMode.OPTIMAL)"
   ]
  }
 ],
 "metadata": {
  "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}