notebooks/07_parallel_transforms.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3c3e2734",
   "metadata": {},
   "source": [
    "# Parallel calculations of transforms\n",
    "\n",
    "Scikit-mol supports parallel calculations of fingerprints and descriptors. This feature can be activated and configured using the `parallel` parameter or the `.parallel` attribute after object instantiation.\n",
    "\n",
    "To begin, let's import the necessary libraries: RDKit and pandas. And of course, we'll also need to import scikit-mol, which is the new kid on the block."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "d34a6f7e",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:28.855965Z",
     "iopub.status.busy": "2024-04-12T12:10:28.855774Z",
     "iopub.status.idle": "2024-04-12T12:10:29.593405Z",
     "shell.execute_reply": "2024-04-12T12:10:29.592709Z"
    }
   },
   "outputs": [],
   "source": [
    "from rdkit.Chem import PandasTools\n",
    "import pandas as pd\n",
    "import time\n",
    "\n",
    "\n",
    "from scikit_mol.descriptors import MolecularDescriptorTransformer\n",
    "from scikit_mol.fingerprints import MorganFingerprintTransformer\n",
    "from scikit_mol.conversions import SmilesToMolTransformer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f73bfd41",
   "metadata": {},
   "source": [
    "## Obtaining the Data\n",
    "\n",
    "We'll need some data to work with, so we'll use a dataset of SLC6A4 active compounds from ExcapeDB that is available on Zenodo. Scikit-mol uses a subset of this dataset for testing purposes, and the samples have been specially selected to provide good results in testing. Note: This dataset should never be used for production modeling.\n",
    "\n",
    "In the code below, you can set full_set to True to download the full dataset. Otherwise, the smaller dataset will be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "f59b0883",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:29.596321Z",
     "iopub.status.busy": "2024-04-12T12:10:29.596022Z",
     "iopub.status.idle": "2024-04-12T12:10:29.600548Z",
     "shell.execute_reply": "2024-04-12T12:10:29.599990Z"
    }
   },
   "outputs": [],
   "source": [
    "full_set = False\n",
    "\n",
    "if full_set:\n",
    "    csv_file = \"SLC6A4_active_excape_export.csv\"\n",
    "    if not os.path.exists(csv_file):\n",
    "        import urllib.request\n",
    "        url = \"https://ndownloader.figshare.com/files/25747817\"\n",
    "        urllib.request.urlretrieve(url, csv_file)\n",
    "else:\n",
    "    csv_file = '../tests/data/SLC6A4_active_excapedb_subset.csv'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9cb3cb5c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:29.602922Z",
     "iopub.status.busy": "2024-04-12T12:10:29.602713Z",
     "iopub.status.idle": "2024-04-12T12:10:29.643748Z",
     "shell.execute_reply": "2024-04-12T12:10:29.643141Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 out of 200 SMILES failed in conversion\n"
     ]
    }
   ],
   "source": [
    "\n",
    "data = pd.read_csv(csv_file)\n",
    "\n",
    "PandasTools.AddMoleculeColumnToFrame(data, smilesCol=\"SMILES\")\n",
    "print(f\"{data.ROMol.isna().sum()} out of {len(data)} SMILES failed in conversion\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cbdda331",
   "metadata": {},
   "source": [
    "## Evaluating the Impact of Parallelism on Transformations\n",
    "\n",
    "Let's start by creating a baseline for our calculations without using parallelism."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "45c042f0",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:29.646541Z",
     "iopub.status.busy": "2024-04-12T12:10:29.646035Z",
     "iopub.status.idle": "2024-04-12T12:10:29.651144Z",
     "shell.execute_reply": "2024-04-12T12:10:29.650588Z"
    },
    "title": "A demonstration of the speedup that can be had for the descriptor transformer"
   },
   "outputs": [],
   "source": [
    "transformer = MolecularDescriptorTransformer(parallel=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "8f158499",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:29.653455Z",
     "iopub.status.busy": "2024-04-12T12:10:29.653236Z",
     "iopub.status.idle": "2024-04-12T12:10:31.579596Z",
     "shell.execute_reply": "2024-04-12T12:10:31.578985Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculation time on dataset of size 200  with parallel=False:\t1.92 seconds\n"
     ]
    }
   ],
   "source": [
    "def test_transformer(transformer):\n",
    "    t0 = time.time()\n",
    "    X = transformer.transform(data.ROMol)\n",
    "    t = time.time()-t0\n",
    "    print(f\"Calculation time on dataset of size {len(data)}  with parallel={transformer.parallel}:\\t{t:0.2F} seconds\")\n",
    "test_transformer(transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08b2cb6e",
   "metadata": {},
   "source": [
    "\n",
    "Let's see if parallelism can help us speed up our transformations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f1b48596",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:31.582218Z",
     "iopub.status.busy": "2024-04-12T12:10:31.581970Z",
     "iopub.status.idle": "2024-04-12T12:10:32.110173Z",
     "shell.execute_reply": "2024-04-12T12:10:32.109459Z"
    }
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/home/esben/python_envs/vscode/lib/python3.10/site-packages/numpy/core/fromnumeric.py:59: FutureWarning: 'Series.swapaxes' is deprecated and will be removed in a future version. Please use 'Series.transpose' instead.\n",
      "  return bound(*args, **kwds)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculation time on dataset of size 200  with parallel=True:\t0.52 seconds\n"
     ]
    }
   ],
   "source": [
    "\n",
    "transformer = MolecularDescriptorTransformer(parallel=True)\n",
    "test_transformer(transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "267de7b7",
   "metadata": {},
   "source": [
    "We've seen that parallelism can help speed up our transformations, with the degree of speedup depending on the number of CPU cores available. However, it's worth noting that there may be some overhead associated with the process of splitting the dataset, pickling objects and functions, and passing them to the parallel child processes. As a result, it may not always be worthwhile to use parallelism, particularly for smaller datasets or certain types of fingerprints.\n",
    "\n",
    "It's also worth noting that there are different methods for creating the child processes, with the default method on Linux being 'fork', while on Mac and Windows it's 'spawn'. The code we're using has been tested on Linux using the 'fork' method.\n",
    "\n",
    "Now, let's see how parallelism impacts another type of transformer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "f8b61e6c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:32.113041Z",
     "iopub.status.busy": "2024-04-12T12:10:32.112800Z",
     "iopub.status.idle": "2024-04-12T12:10:32.220711Z",
     "shell.execute_reply": "2024-04-12T12:10:32.219973Z"
    },
    "lines_to_next_cell": 2,
    "title": "Some of the benchmarking plots"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculation time on dataset of size 200  with parallel=False:\t0.02 seconds\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calculation time on dataset of size 200  with parallel=True:\t0.08 seconds\n"
     ]
    }
   ],
   "source": [
    "transformer = MorganFingerprintTransformer(parallel=False)\n",
    "test_transformer(transformer)\n",
    "transformer.parallel = True\n",
    "test_transformer(transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c29a58f",
   "metadata": {},
   "source": [
    "Interestingly, we observed that parallelism actually took longer to calculate the fingerprints in some cases, which is a perfect illustration of the overhead issue associated with parallelism. Generally, the faster the fingerprint calculation in itself, the larger the dataset needs to be for parallelism to be worthwhile. For example, the Descriptor transformer, which is one of the slowest, can benefit even for smaller datasets, while for faster fingerprint types like Morgan, Atompairs, and Topological Torsion fingerprints, the dataset needs to be larger.\n",
    "\n",
    "![ Relation ship between throughput and parallel speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/max_speedup_vs_throughput.png \"Not all fingerprints are equally fast and benefit the same from parallelism\")\n",
    "\n",
    "We've also included a series of plots below, showing the speedup over serial for different numbers of cores used for different dataset sizes. These timings were taken on a 16 core machine (32 Hyperthreads). Only the largest datasets (>10,000 samples) would make it worthwhile to parallelize Morgan, Atompairs, and Topological Torsions. SECfingerprint, MACCS keys, and RDKitFP are intermediate and would benefit from parallelism when the dataset size is larger, say >500. Descriptors, on the other hand, benefit almost immediately even for the smallest datasets (>100 samples).\n",
    "\n",
    "![Atompairs fingerprint](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/AtomPairFingerprintTransformer_par.png \"Atompairs fingerprint speedup\")\n",
    "\n",
    "![Descriptors calculation speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/Desc2DTransformer_par.png \"Descriptors calculation speedup\")\n",
    "\n",
    "![MACCS keys speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/MACCSTransformer_par.png \"MACCS keys speedup\")\n",
    "\n",
    "![Morgan fingerprint speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/MorganTransformer_par.png \"Morgan fingerprint speedup\")\n",
    "\n",
    "![RDKit fingerprint speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/RDKitFPTransformer_par.png \"RDKit fingerprint speedup\")\n",
    "\n",
    "![SEC fingerprint speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/SECFingerprintTransformer_par.png \"SEC fingerprint speedup\")\n",
    "\n",
    "![TopologicalTorsion fingerprint speedup](https://github.com/EBjerrum/scikit-mol/raw/main/notebooks/images/TopologicalTorsionFingerprintTransformer_par.png \"TopologicalTorsion fingerprint speedup\")\n",
    "\n",
    "\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "title,-all",
   "formats": "ipynb,py:percent"
  },
  "kernelspec": {
   "display_name": "rdkit2",
   "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}