notebooks/01_basic_usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8a3e313c",
   "metadata": {},
   "source": [
    "# Scikit-Mol\n",
    "## scikit-learn compatible RDKit transformers\n",
    "\n",
    "Scikit-mol is a collection of scikit-learn compatible transformer classes that integrate into the scikit-learn framework and thus bridge between the molecular information in form of RDKit molecules or SMILES and the machine learning framework from scikit-learn\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7bcbed23",
   "metadata": {},
   "source": [
    "The transformer classes are easy to load, configure and use to process molecular information into vectorized formats using fingerprinters or collections of descriptors. For demonstration purposes, let's load a MorganTransformer, that can convert a list of RDKit molecular objects into a numpy array of morgan fingerprints. First create some molecules from SMILES strings."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "f8025236",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:09.802220Z",
     "iopub.status.busy": "2024-04-12T12:10:09.802030Z",
     "iopub.status.idle": "2024-04-12T12:10:09.808949Z",
     "shell.execute_reply": "2024-04-12T12:10:09.808440Z"
    }
   },
   "outputs": [],
   "source": [
    "from IPython.core.display import HTML"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "58a33f4d",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:09.811277Z",
     "iopub.status.busy": "2024-04-12T12:10:09.811060Z",
     "iopub.status.idle": "2024-04-12T12:10:09.936897Z",
     "shell.execute_reply": "2024-04-12T12:10:09.936201Z"
    }
   },
   "outputs": [],
   "source": [
    "from rdkit import Chem\n",
    "\n",
    "smiles_strings = [\"C12C([C@@H](OC(C=3C=CC(=CC3)F)C=4C=CC(=CC4)F)CC(N1CCCCCC5=CC=CC=C5)CC2)C(=O)OC\", \n",
    "\"O(C1=NC=C2C(CN(CC2=C1)C)C3=CC=C(OC)C=C3)CCCN(CC)CC\",\n",
    "\"O=S(=O)(N(CC=1C=CC2=CC=CC=C2C1)[C@@H]3CCNC3)C\",\n",
    "\"C1(=C2C(CCCC2O)=NC=3C1=CC=CC3)NCC=4C=CC(=CC4)Cl\",\n",
    "\"C1NC[C@@H](C1)[C@H](OC=2C=CC(=NC2C)OC)CC(C)C\",\n",
    "\"FC(F)(F)C=1C(CN(C2CCNCC2)CC(CC)CC)=CC=CC1\"]\n",
    "\n",
    "mols = [Chem.MolFromSmiles(smiles) for smiles in smiles_strings]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0228c878",
   "metadata": {},
   "source": [
    "Next we import the Morgan fingerprint transformer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "cdb821a1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:09.939980Z",
     "iopub.status.busy": "2024-04-12T12:10:09.939552Z",
     "iopub.status.idle": "2024-04-12T12:10:10.505528Z",
     "shell.execute_reply": "2024-04-12T12:10:10.504885Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MorganFingerprintTransformer(radius=3)\n"
     ]
    }
   ],
   "source": [
    "from scikit_mol.fingerprints import MorganFingerprintTransformer\n",
    "\n",
    "transformer = MorganFingerprintTransformer(radius=3)\n",
    "print(transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8ebae67",
   "metadata": {},
   "source": [
    "It actually renders as a cute little interactive block in the Jupyter notebook and lists the options that are not the default values. If we print it, it also gives the information on the settings. \n",
    "\n",
    "![An image of the interactive transformer widget](images/Transformer_Widget.jpg \"Transformer object rendering in Jupyter\")\n",
    "\n",
    "The graphical representation is probably nice when working with complex pipelines. However, the graphical representation doesn't work when previewing the notebook on GitHub and sometimes nbviewer.org, so for the rest of these scikit-mol notebook examples, we'll use the print() output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "c3a24f4e",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.508400Z",
     "iopub.status.busy": "2024-04-12T12:10:10.508055Z",
     "iopub.status.idle": "2024-04-12T12:10:10.514636Z",
     "shell.execute_reply": "2024-04-12T12:10:10.514117Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>#sk-container-id-1 {color: black;}#sk-container-id-1 pre{padding: 0;}#sk-container-id-1 div.sk-toggleable {background-color: white;}#sk-container-id-1 label.sk-toggleable__label {cursor: pointer;display: block;width: 100%;margin-bottom: 0;padding: 0.3em;box-sizing: border-box;text-align: center;}#sk-container-id-1 label.sk-toggleable__label-arrow:before {content: \"▸\";float: left;margin-right: 0.25em;color: #696969;}#sk-container-id-1 label.sk-toggleable__label-arrow:hover:before {color: black;}#sk-container-id-1 div.sk-estimator:hover label.sk-toggleable__label-arrow:before {color: black;}#sk-container-id-1 div.sk-toggleable__content {max-height: 0;max-width: 0;overflow: hidden;text-align: left;background-color: #f0f8ff;}#sk-container-id-1 div.sk-toggleable__content pre {margin: 0.2em;color: black;border-radius: 0.25em;background-color: #f0f8ff;}#sk-container-id-1 input.sk-toggleable__control:checked~div.sk-toggleable__content {max-height: 200px;max-width: 100%;overflow: auto;}#sk-container-id-1 input.sk-toggleable__control:checked~label.sk-toggleable__label-arrow:before {content: \"▾\";}#sk-container-id-1 div.sk-estimator input.sk-toggleable__control:checked~label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 div.sk-label input.sk-toggleable__control:checked~label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 input.sk-hidden--visually {border: 0;clip: rect(1px 1px 1px 1px);clip: rect(1px, 1px, 1px, 1px);height: 1px;margin: -1px;overflow: hidden;padding: 0;position: absolute;width: 1px;}#sk-container-id-1 div.sk-estimator {font-family: monospace;background-color: #f0f8ff;border: 1px dotted black;border-radius: 0.25em;box-sizing: border-box;margin-bottom: 0.5em;}#sk-container-id-1 div.sk-estimator:hover {background-color: #d4ebff;}#sk-container-id-1 div.sk-parallel-item::after {content: \"\";width: 100%;border-bottom: 1px solid gray;flex-grow: 1;}#sk-container-id-1 div.sk-label:hover label.sk-toggleable__label {background-color: #d4ebff;}#sk-container-id-1 div.sk-serial::before {content: \"\";position: absolute;border-left: 1px solid gray;box-sizing: border-box;top: 0;bottom: 0;left: 50%;z-index: 0;}#sk-container-id-1 div.sk-serial {display: flex;flex-direction: column;align-items: center;background-color: white;padding-right: 0.2em;padding-left: 0.2em;position: relative;}#sk-container-id-1 div.sk-item {position: relative;z-index: 1;}#sk-container-id-1 div.sk-parallel {display: flex;align-items: stretch;justify-content: center;background-color: white;position: relative;}#sk-container-id-1 div.sk-item::before, #sk-container-id-1 div.sk-parallel-item::before {content: \"\";position: absolute;border-left: 1px solid gray;box-sizing: border-box;top: 0;bottom: 0;left: 50%;z-index: -1;}#sk-container-id-1 div.sk-parallel-item {display: flex;flex-direction: column;z-index: 1;position: relative;background-color: white;}#sk-container-id-1 div.sk-parallel-item:first-child::after {align-self: flex-end;width: 50%;}#sk-container-id-1 div.sk-parallel-item:last-child::after {align-self: flex-start;width: 50%;}#sk-container-id-1 div.sk-parallel-item:only-child::after {width: 0;}#sk-container-id-1 div.sk-dashed-wrapped {border: 1px dashed gray;margin: 0 0.4em 0.5em 0.4em;box-sizing: border-box;padding-bottom: 0.4em;background-color: white;}#sk-container-id-1 div.sk-label label {font-family: monospace;font-weight: bold;display: inline-block;line-height: 1.2em;}#sk-container-id-1 div.sk-label-container {text-align: center;}#sk-container-id-1 div.sk-container {/* jupyter's `normalize.less` sets `[hidden] { display: none; }` but bootstrap.min.css set `[hidden] { display: none !important; }` so we also need the `!important` here to be able to override the default hidden behavior on the sphinx rendered scikit-learn.org. See: https://github.com/scikit-learn/scikit-learn/issues/21755 */display: inline-block !important;position: relative;}#sk-container-id-1 div.sk-text-repr-fallback {display: none;}</style><div id=\"sk-container-id-1\" class=\"sk-top-container\"><div class=\"sk-text-repr-fallback\"><pre>MorganFingerprintTransformer(radius=3)</pre><b>In a Jupyter environment, please rerun this cell to show the HTML representation or trust the notebook. <br />On GitHub, the HTML representation is unable to render, please try loading this page with nbviewer.org.</b></div><div class=\"sk-container\" hidden><div class=\"sk-item\"><div class=\"sk-estimator sk-toggleable\"><input class=\"sk-toggleable__control sk-hidden--visually\" id=\"sk-estimator-id-1\" type=\"checkbox\" checked><label for=\"sk-estimator-id-1\" class=\"sk-toggleable__label sk-toggleable__label-arrow\">MorganFingerprintTransformer</label><div class=\"sk-toggleable__content\"><pre>MorganFingerprintTransformer(radius=3)</pre></div></div></div></div></div>"
      ],
      "text/plain": [
       "MorganFingerprintTransformer(radius=3)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "transformer"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c6e5de37",
   "metadata": {},
   "source": [
    "If we want to get all the settings explicitly, we can use the .get_params() method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "112afff2",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.517110Z",
     "iopub.status.busy": "2024-04-12T12:10:10.516867Z",
     "iopub.status.idle": "2024-04-12T12:10:10.521207Z",
     "shell.execute_reply": "2024-04-12T12:10:10.520689Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'nBits': 2048,\n",
       " 'parallel': False,\n",
       " 'radius': 3,\n",
       " 'useBondTypes': True,\n",
       " 'useChirality': False,\n",
       " 'useCounts': False,\n",
       " 'useFeatures': False}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "parameters = transformer.get_params()\n",
    "parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45296da6",
   "metadata": {},
   "source": [
    "The corresponding .set_params() method can be used to update the settings from options or from a dictionary (via ** unpackaging). The get_params and set_params methods are sometimes used by sklearn, as example hyperparameter search objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "4229d3d3",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.523546Z",
     "iopub.status.busy": "2024-04-12T12:10:10.523347Z",
     "iopub.status.idle": "2024-04-12T12:10:10.527067Z",
     "shell.execute_reply": "2024-04-12T12:10:10.526450Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MorganFingerprintTransformer(nBits=256)\n"
     ]
    }
   ],
   "source": [
    "parameters[\"radius\"] = 2\n",
    "parameters[\"nBits\"] = 256\n",
    "transformer.set_params(**parameters)\n",
    "print(transformer)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d38c224",
   "metadata": {},
   "source": [
    "Transformation is easy, simply use the .transform() method. For sklearn compatibility the scikit-learn transformers also have a .fit_transform() method, but it is usually not fitting anything."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "d2276e30",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.529451Z",
     "iopub.status.busy": "2024-04-12T12:10:10.529229Z",
     "iopub.status.idle": "2024-04-12T12:10:10.533310Z",
     "shell.execute_reply": "2024-04-12T12:10:10.532819Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "fps is a <class 'numpy.ndarray'> with shape (6, 256) and data type int8\n"
     ]
    }
   ],
   "source": [
    "fps = transformer.transform(mols)\n",
    "print(f\"fps is a {type(fps)} with shape {fps.shape} and data type {fps.dtype}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "666bf64b",
   "metadata": {},
   "source": [
    "For sklearn compatibility, the transform function can be given a second parameter, usually representing the targets in the machine learning, but it is simply ignored most of the time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "d3b01806",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.535668Z",
     "iopub.status.busy": "2024-04-12T12:10:10.535455Z",
     "iopub.status.idle": "2024-04-12T12:10:10.540535Z",
     "shell.execute_reply": "2024-04-12T12:10:10.539917Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[0, 1, 0, ..., 0, 0, 0],\n",
       "       [1, 0, 0, ..., 0, 0, 1],\n",
       "       [1, 0, 0, ..., 0, 0, 0],\n",
       "       [0, 0, 0, ..., 0, 0, 1],\n",
       "       [1, 1, 0, ..., 0, 0, 0],\n",
       "       [1, 1, 0, ..., 0, 0, 0]], dtype=int8)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "y = range(len(mols))\n",
    "transformer.transform(mols, y)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e5c385f",
   "metadata": {},
   "source": [
    "Sometimes we may want to transform SMILES into molecules, and scikit-mol also has a transformer for that. It simply takes a list of SMILES and produces a list of RDKit molecules, this may come in handy when building pipelines for machine learning models, as we will demo in another notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "26081bb2",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.542876Z",
     "iopub.status.busy": "2024-04-12T12:10:10.542661Z",
     "iopub.status.idle": "2024-04-12T12:10:10.546656Z",
     "shell.execute_reply": "2024-04-12T12:10:10.546143Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SmilesToMolTransformer()\n"
     ]
    }
   ],
   "source": [
    "from scikit_mol.conversions import SmilesToMolTransformer\n",
    "smi2mol = SmilesToMolTransformer()\n",
    "print(smi2mol)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "6b0e5f4a",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-04-12T12:10:10.548964Z",
     "iopub.status.busy": "2024-04-12T12:10:10.548714Z",
     "iopub.status.idle": "2024-04-12T12:10:10.553416Z",
     "shell.execute_reply": "2024-04-12T12:10:10.552805Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[[<rdkit.Chem.rdchem.Mol object at 0x798ebb81ee30>]\n",
      " [<rdkit.Chem.rdchem.Mol object at 0x798ebb81eea0>]\n",
      " [<rdkit.Chem.rdchem.Mol object at 0x798ebb81ef10>]\n",
      " [<rdkit.Chem.rdchem.Mol object at 0x798ebb81ef80>]\n",
      " [<rdkit.Chem.rdchem.Mol object at 0x798ebb81eff0>]\n",
      " [<rdkit.Chem.rdchem.Mol object at 0x798ebb81f060>]]\n"
     ]
    }
   ],
   "source": [
    "print(smi2mol.transform(smiles_strings))"
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "formats": "ipynb,py:percent"
  },
  "kernelspec": {
   "display_name": "Python 3.9.4 ('rdkit')",
   "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
}