demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# FPSim2 demo\n",
    "\n",
    "- FPSim2 is an easy to use, simple and small Python library to run fast similarity searches.\n",
    "- Heavy processing is implemented in C++ calling SIMD instructions and taking advantadge of [pybind11](https://pybind11.readthedocs.io/en/stable/)'s awesome integration with Numpy. \n",
    "- GIL is released most of the time, so multiple threads can be used for speeding up a single query.\n",
    "- Fingerprints are stored in a PyTables table.\n",
    "- Provides 2 working modes:\n",
    "  - In memory search: Fastest\n",
    "  - On disk search: In case the dataset doesn't fit in memory.\n",
    "- It has **limitation**: Only integer ids can be used to identify molecules. This library was designed to work in backends which must have integer ids for its data. We are using ChEMBL's **molregno** as id in this example.\n",
    "\n",
    "ChEMBL31 is only 2.3 million molecules. Advantadge in using multiple threads in a single query is more obviously seen on bigger datasets. \n",
    "\n",
    "It's been already tested against Unichem (>150 million compounds) and GDB13 (>970 million compounds).\n",
    "\n",
    "**Notice that Binder performance is not very good.**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from FPSim2 import FPSim2Engine\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load fp db and show fp parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "fp_filename = 'chembl_31.h5'\n",
    "\n",
    "fpe = FPSim2Engine(fp_filename)\n",
    "\n",
    "print('FP type: ', fpe.fp_type)\n",
    "print('FP parameters: ', fpe.fp_params)\n",
    "print('RDKit version: ', fpe.rdkit_ver)\n",
    "print('Num fps:', fpe.fps.shape[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Run a similarity (Tanimoto) search\n",
    "In small databases like ChEMBL an important portion of the search time is spent processing the query molecule."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "query = 'CC(=O)Oc1ccccc1C(=O)O'\n",
    "results = fpe.similarity(query, 0.7, n_workers=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Results in a nice structured numpy array"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(results.shape)\n",
    "results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Time it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%timeit\n",
    "results = fpe.similarity(query, 0.7, n_workers=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## it is also possible to run Tversky asymmetric searches\n",
    "\n",
    "Tversky is a generalisation of Tanimoto and Dice coefficients so by setting a and b with the following values:\n",
    " - a=1, b=1: its equivalent (but slower) to fpe.similarity function (Tanimoto)\n",
    " - a=1, b=0: its equivalent (but slower) to fpe.substructure function (substructure screenout)\n",
    " - a=0.5, b=0.5 will calculate the Sørensen–Dice coefficient"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "results = fpe.tversky(query, 0.7, 0.5, 0.5, n_workers=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(results.shape)\n",
    "results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## On disk search\n",
    "\n",
    "If your dataset doesn't fit in memory or you're dealing with huge datasets, it's still possible to run searches."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "query = 'CC(=O)Oc1ccccc1C(=O)O'\n",
    "\n",
    "fpe = FPSim2Engine(fp_filename, in_memory_fps=False)\n",
    "results = fpe.on_disk_similarity(query, 0.7, chunk_size=100000, n_workers=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "print(results.shape)\n",
    "results"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Time it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "%%timeit\n",
    "results = fpe.on_disk_similarity(query, 0.7, chunk_size=100000, n_workers=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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-final"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}