AIMSim-demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# AIMSim Demo\n",
    "This notebook demonstrates the key uses of _AIMSim_ as a graphical user interface, command line tool, and scripting utility. For detailed explanations and to view the source code for _AIMSim_, visit our [documentation page](https://vlachosgroup.github.io/AIMSim/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing _AIMSim_\n",
    "For users with Python already in use on their devices, it is _highly_ recommended to first create a virtual environment before installing _AIMSim_. This package has a large number of dependencies with only a handful of versions supported, so conflicts are likely unless a virtual environment is used.\n",
    "\n",
    "For new Python users, the authors recommended installing anaconda navigator to manage dependencies for _AIMSim_ and make installation easier overall. Once anaconda navigator is ready, create a new environment with Python 3.8 or newer, open a terminal or command prompt in this environment, and follow the instructions below. \n",
    "\n",
    "We recommend installing _AIMSim_ using the commands shown below (omit exclamation points and the %%capture, unless you are running in a Jupyter notebook):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%capture\n",
    "!pip install aimsim nbformat"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, start the _AIMSim_ GUI by typing `python -m aimsim` or simply `aimsim` into the command line."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Graphical User Interface Walkthrough\n",
    "For most users, the Graphical User Interface (GUI) will provide access to all the key functionalities in _AIMSim_. The GUI works by serving the user with drop downs and text fields which represent settings that would otherwise need to be configured in a file by hand. This file is written to the disk by the GUI as part of execution so that the file can be used as a 'starting point' for more advanced use cases.\n",
    "\n",
    "**Important Note**: Jupyter Notebook _cannot_ run _AIMSim_ from Binder. In order to actually run the _AIMSim_ GUI alongside this tutorial, you will need to download this notebook and run it from a local installation of Jupyter, or follow the installation instructions above and start _AIMSim_ from there. You can install Jupyter [here](https://jupyter.org/install).\n",
    "\n",
    "![GUI](AIMSim-GUI.png)\n",
    "\n",
    "\n",
    "### Row 1: Molecule Database Entry\n",
    "This field accepts a file or directory path containing an input set of molecules in one of the accepted formats: SMILES strings, Protein Data Bank files, and excel files containing these data types.\n",
    "\n",
    "Example:\n",
    "\n",
    "`/Users/chemist/Desktop/SMILES_database.smi`\n",
    "\n",
    "The `Browse...` button can also be used to find files anywhere on your computer using your system's default file explorer.\n",
    "\n",
    "### Row 2: Molecule Database Checkboxes\n",
    "#### Database Similarity Plot\n",
    "Checking this box will generate a similarity distribution with _AIMSim's_ default color scheme and labels. To customize this plot further, edit the configuration file produced by _AIMSim_ by clicking `Open Config`, then re-submit the file through the command line interface.\n",
    "In addition to the similarity distribution, this will create a heatmap showing pairwise comparisons between the two species. As above, edit the configuration file to control the appearance of this plot.\n",
    "\n",
    "Example:\n",
    "\n",
    "![Image of sulfonamide substrate scope](tests/sulfonamide-substrate-scope.png)\n",
    "\n",
    "#### Property Similarity Plot\n",
    "Like in the previous two examples, checking this box will create a plot showing how a provided molecular property varies according to the chosen molecular fingerprint. For this to work, data must be provided in a comma-separated value format (which can be generated using Excel with Save As... -> CSV) where the rightmost column is a numerical value (the property of interest).\n",
    "\n",
    "Example:\n",
    "\n",
    "| SMILES | Boiling Point |\n",
    "|--------|---------------|\n",
    "| C      | -161.6        |\n",
    "| CC     | -89           |\n",
    "| CCC    | -42           |\n",
    "\n",
    "\n",
    "### Row 3: Target Molecule Entry\n",
    "Provide a SMILES string representing a single molecule for comparison to the provided database of molecules. In the screenshot above, the default option is shown (since this field is optional). Any valid SMILES strings are accepted, and any errors in the SMILES string will not affect the execution of other tasks.\n",
    "\n",
    "As in the Database Entry Field, use the `Browse...` button to find a single molecule in an accepted data format using a file explorer popup window.\n",
    "\n",
    "\n",
    "### Row 4: Similarity Measure\n",
    "This dropdown includes all of the similarity metrics currently implemented in _AIMSim_. The default selected metric is likely a great starting point for most users, and the additional metrics are provided for advanced users or more specific use cases. \n",
    "\n",
    "Available Similarity Measures are automatically updated according to the fingerprint currently selected. Not all metrics are compatible with all fingerprints, and _AIMSim_ recognizes will only allow the user to select valid combinations.\n",
    "\n",
    "_AIMSim_ also has the ability to determine which similarity metric is best to represent the data in hand. Selecting `AI Search` will identify said descriptor and use it in subsequent analysis. Similarly, _AIMSim_ can determine which fingerprint best represents the data, though this feature is currently only accessible via the command line (see the specifications file below).\n",
    "\n",
    "For a complete list of implemented descriptors, run _AIMSim_ locally or check the online documentation [here](https://vlachosgroup.github.io/AIMSim/implemented_metrics.html).\n",
    "\n",
    "\n",
    "### Row 5: Molecular Descriptor\n",
    "This dropdown includes all of the molecular descriptors, mainly fingerprints, currently implemented in _AIMSim_:\n",
    "\n",
    "|#|Fingerprint|\n",
    "|---|---|\n",
    "|1|morgan|\n",
    "|2|topological|\n",
    "|3|daylight|\n",
    "\n",
    "Each of these fingerprints should be generally applicable for chemical problems, though they are all provided to serve as an easy way to compare the results according to fingerprinting approach.\n",
    "\n",
    "Additional descriptors are included with _AIMSim_ which are not mathematically compatible with some of the similarity measures. When such a descriptor is selected, the corresponding similarity measure will be removed from the dropdown.\n",
    "\n",
    "The `Exp. Descriptors` checkbox adds additional molecular descriptors into the `Molecular Descriptor` dropdown. These are marked as _experimental_ because they are generated using third-party libraries over which we have very little or no control. The descriptors generated by these libraries should be used only when the user has a very specific need for a descriptor as implemented in one of the packages below:\n",
    " - [minhash](https://github.com/reymond-group/mhfp): Much faster fingerprint for similarity searches, supports non-binary similarity metrics.\n",
    " - [ccbmlib](https://doi.org/10.12688/f1000research.22292.2): All molecular fingerprints included in the `ccbmlib` library have been reproduced in _AIMSim_. Read about these fingerprints [in the `ccbmlib` repository](https://github.com/vogt-m/ccbmlib).\n",
    " - [mordred](https://doi.org/10.1186/s13321-018-0258-y): All 1000+ descriptors included in `mordred` are available in _AIMSim_, though through the community maintained alternative package `mordred-community`. (command line only)\n",
    " - [PaDELPy](https://doi.org/10.1002/jcc.21707): [This package](https://github.com/ecrl/padelpy) provides access to all of the molecular descriptors included as part of the PaDEL-Descriptor standalone Java program. (command line only)\n",
    "\n",
    "### Row 6: The Power Buttons\n",
    "#### Run\n",
    "Pressing this button will call a number of input checkers to verify that the information entered into the fields above is valid, and then the tasks will be passed into _AIMSim_ for execution. Additional input to _AIMSim_ needed for some tasks may be requested from the command line.\n",
    "\n",
    "For large collections of molecules with substantial run times, your operating system may report that _AIMSim_ has stopped responding and should be closed. This is likely not the case, and _AIMSim_ is simply executing your requested tasks. If unsure, try checking the `Verbose` checkbox discussed below, which will provide near-constant output while _AIMSim_ is running.\n",
    "\n",
    "#### Open Config\n",
    "Using your system's default text editor, this button will open the configuration file generated by _AIMSim_ after pressing the run button. This is useful for fine-tuning your plots or re-running the exact same tasks in the future. This configuration file can also access additional functionality present in _AIMSim_ which is not included in the GUI, such as the sampling ratio for the data (covered in greater depth in the __Command Line and Configuration Files__ section below). To use this configuration file, include the name of the file after your call to _AIMSim_ on the command line, i.e.:\n",
    "\n",
    "`aimsim aimsim-ui-config.yaml` or `python -m aimsim aimsim-ui-config.yaml`\n",
    "\n",
    "Because of the way Python install libraries like _AIMSim_, this file will likely be saved somewhere difficult to find among many other internal Python files. It is highly recommended to make a copy of this file in a more readily accessible location, or copy the contents of this file into another one. The name of the file can also be changed to something more meaningful (i.e., JWB-Solvent-Screen-123.yaml) as long as the file extension (.yaml) is still included.\n",
    "\n",
    "### Row 7: Configuration Checkboxes\n",
    "### Verbose\n",
    "Selecting this checkbox will cause _AIMSim_ to emit near-constant updates to the command line on its status during execution. This is useful to confirm that _AIMSim_ is executing and has not crashed, and also to provide additional information about errors in the input data.\n",
    "\n",
    "For large datasets, this may generate a _significant_ amount of command line output. A pairwise comparison of 10,000 molecules would require 100,000,000 (10,000 \\* 10,000) operations, generating at least that many lines of text in the console.\n",
    "\n",
    "Example __Verbose__ output:\n",
    "\n",
    "```\n",
    "Reading SMILES strings from C:\\path\\to\\file\\small.smi\n",
    "Processing O=S(C1=CC=CC=C1)(N2CCOCC2)=O (1/5)\n",
    "Processing O=S(C1=CC=C(C(C)(C)C)C=C1)(N2CCOCC2)=O (2/5)\n",
    "Processing O=S(C1=CC=C(C2=CC=CC=C2)C=C1)(N3CCOCC3)=O (3/5)\n",
    "Processing O=S(C1=CC=C(OC)C=C1)(N2CCOCC2)=O (4/5)\n",
    "Processing O=S(C1=CC=C(SC)C=C1)(N2CCOCC2)=O (5/5)\n",
    "Computing similarity of molecule num 1 against 1\n",
    "Computing similarity of molecule num 2 against 1\n",
    "Computing similarity of molecule num 3 against 1\n",
    "Computing similarity of molecule num 4 against 1\n",
    "Computing similarity of molecule num 5 against 1\n",
    "Computing similarity of molecule num 1 against 2\n",
    "```\n",
    "\n",
    "### Outlier Check\n",
    "Checking this will have _AIMSim_ create an Isolation Forest (read more about this in [Sklearn's documentation](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.IsolationForest.html)) to identify possible outliers in the input database of molecules. The results from this approach are _non-deterministic_ because of the underlying algorithm driving the Isolation Forest, so this feature is intended to be a \"sanity check\" rather than a quantitative measure of 'outlier-ness'. To truly determine how different a single example molecule is to a set of molecules, use the `Compare Target Molecule` functionality discussed above.\n",
    "\n",
    "### Enable Multiple Workers\n",
    "This checkbox will enable multiprocessing, speeding up execution time on the data. By default, _AIMSim_ will use __all__ physical cores available on your machine, which may impact performance of other programs.\n",
    "\n",
    "The user should only enable this option with datasets off a few hundred or more molecules. This is because there is additional processing time associated with creating and destroying multiple processes, so for small data sets it is faster to simply execute the comparisons serially."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Command Line and Configuration Files\n",
    "For users who prefer to use _AIMSim_ without a user interface, a command line interface is provided. This requires the user to manually write configuration files, but allows access to more granular control and some additional features which are not included in the GUI. This can be invoked by typing `aimsim config.yaml` into your terminal or command window, where `config.yaml` is a configuration file you have provided or copied from the _AIMSim_ repository.\n",
    "\n",
    "Below is a 'maximum specification' file to be used with _AIMSim_, showing all possible settings and tasks which _AIMSim_ can ingest. Any overall settings which are left out will be inferred by _AIMSim_, and any tasks which are not included will simply not be executed. Each field used in the file is explained afterward."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Maximum Specification File\n",
    "```\n",
    "is_verbose (bool):\n",
    "molecule_database (str): # path to excel / csv/ text file\n",
    "molecule_database_source_type (str):  # Type of source file. 'excel', 'csv', 'text'\n",
    "similarity_measure (str):  #Set to determine if auto identification required\n",
    "fingerprint_type (str):  # Set to determine if auto identification required\n",
    "measure_id_subsample (float):  # [0, 1] Subsample used for measure search\n",
    "sampling_ratio (float): # [0, 1] Subsample used for all tasks\n",
    "n_workers (int / str):   # [int, 'auto'] number of processes, or let AIMSim decide\n",
    "global_random_seed (int / str):  # int or 'random'\n",
    "    \n",
    "tasks:\n",
    "  get_extended_similarity_indices:\n",
    "    # Extended Similarity Indices has no options\n",
    "\n",
    "  compare_target_molecule:\n",
    "    target_molecule_smiles (str):\n",
    "    draw_molecule (bool):  # If true, strucures of target, most and least similar molecules are displayed\n",
    "    similarity_plot_settings:\n",
    "        plot_color (str): # Set a color recognized by matplotlib\n",
    "        shade (bool): # If true, the similarity density is shaded\n",
    "        plot_title (str):\n",
    "    log_file_path (str):\n",
    "    \n",
    "  visualize_dataset:\n",
    "      heatmap_plot_settings:\n",
    "        cmap (str): # matplotlib recognized cmap (color map) used for heatmap.\n",
    "        plot_title (str):\n",
    "        annotate (bool):  # If true, heatmap is annotated\n",
    "      similarity_plot_settings:\n",
    "        plot_color (str):\n",
    "        shade (bool): # If true, the similarity density is shaded\n",
    "      embedding_plot_settings:\n",
    "        plot_title (str):\n",
    "        embedding:\n",
    "          method (str): # algorithm used for embedding molecule set in 2 dimensions.\n",
    "          params:  # method specific parameters\n",
    "            random_state (int): #used for seeding stochastic algorithms\n",
    " \n",
    "  see_property_variation_w_similarity:\n",
    "    log_file_path (str):\n",
    "    property_plot_settings:\n",
    "      plot_color (str):  # Set a color recognized by matplotlib\n",
    "  \n",
    "  identify_outliers:  \n",
    "    random_state (int):\n",
    "    output (str):  # filepath or \"terminal\" to control where results are shown\n",
    "    plot_outliers (bool):\n",
    "    pair_similarity_plot_settings: # Only meaningful if plot_outliers is True\n",
    "      plot_color (str): # Set a color recognized by matplotlib\n",
    "  \n",
    "  cluster:\n",
    "    n_clusters (int):\n",
    "    clustering_method (str):\n",
    "    log_file_path (str):\n",
    "    cluster_file_path (str):\n",
    "    cluster_plot_settings:\n",
    "      cluster_colors (list): # Ensure len(list) >= n_cluster\n",
    "    embedding_plot_settings:\n",
    "      plot_title (str):\n",
    "      embedding:\n",
    "        method (str): # algorithm used for embedding molecule set in 2 dimensions.\n",
    "        params:  # method specific parameters\n",
    "          random_state (int): #used for seeding stochastic algorithms\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Overall _AIMSim_ Settings\n",
    "These settings impact how all tasks run by _AIMSim_ will be executed.\n",
    " - `is_verbose`: Must be either `True` or `False`. When `True`, _AIMSim_ will emit text updates of during execution to the command line, useful for debugging.\n",
    " - `molecule_database`: A file path to an Excel workbook, text file containing SMILES strings, or PDB file surrounded by single quotes, i.e. `'/User/my_user/smiles_database.smi'`. Can also point to a directory containing a group of PDB files, but the file path must end with a '/' (or '\\' for Windows).\n",
    " - `molecule_database_source_type`: The type of data to be input to _AIMSim_, being either `text`, `excel`, or `pdb`.\n",
    " - `similarity_measure`: The similarity measure to be used during all tasks, chosen from the list of supported similarity measures. Automatic similarity measure determination is also supported, and can be performed by specifying `determine`.\n",
    " - `fingerprint_type`: The fingerprint type or molecular descriptor to be used during all tasks, chosen from the list of supported descriptors. Automatic determination is also supported, and can be performed by specifying `determine`.\n",
    " - `measure_id_subsample`: A decimal number between 0 and 1 specifying what fraction of the dataset to use for automatic determination of similarity measure and fingerprint. For a dataset of 10,000 molecules, setting this to `0.1` would run only 1000 randomly selected molecules, dramatically reducing runtime. This field is only needed if `determine` is used in either of the prior fields.\n",
    " - `sampling_ratio`: A decimal number between 0 and 1 specifying what fraction of the dataset to use for tasks. For a dataset of 10,000 molecules, setting this to `0.1` would run only 1000 randomly selected molecules, dramatically reducing runtime.\n",
    "  - `n_workers`: Either an integer or the string 'auto'. With an integer, _AIMSim_ will create that many processes for its operation. This number should be less than or equal to the number of _physical_ CPU cores in your computer. Set this option to 'auto' to let _AIMSim_ configure multiprocessing for you.\n",
    " - `global_random_seed`: Integer to be passed to all non-deterministic functions in _AIMSim_. By default, this value is 42 to ensure consistent results between subsequent executions of _AIMSim_. This seed will override the random seeds provided to any other _AIMSim_ tasks. Alternatively, specify 'random' to allow _AIMSim_ to randomly generate a seed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Task-Specific Settings\n",
    "The settings fields below dictate the behavior of _AIMSim_ when performing its various tasks.\n",
    "\n",
    "##### Compare Target Molecule\n",
    "Generates a similarity distribution for the dataset compared to an individual molecule.\n",
    " - `target_molecule_smiles`: SMILES string for the molecule used in comparison to the dataset.\n",
    " - `draw_molecule`: If this is set to True, then _AIMSim_ draws the structure of the target molecule, and of the molecule most and least similar to it.\n",
    "     - `similarity_plot_settings`: Controls the appearance of the distribution.\n",
    "         - `plot_color`: Can be any color recognized by the _matplotlib_ library.\n",
    "         - `shade`: `True` or `False`, whether or not to shade in the area under the curve.\n",
    "         - `plot_title`: String containing text to be written above the plot.\n",
    "     - `log_file_path`: String specifying a file to write output to for the execution of this task. Useful for debugging.\n",
    "\n",
    "##### Visualize Dataset\n",
    "Generates a pairwise comparison matrix for all molecules in the dataset.\n",
    " - `heatmap_plot_settings`: Control the appearance of the plot.\n",
    "     - `cmap`: _matplotlib_ recognized cmap (color map) used for heatmap.\n",
    "     - `plot_title`: String containing text to be written above the plot.\n",
    "     - `annotate`: `True` or `False`, controls whether or not _AIMSim_ will write annotations over the heatmap.\n",
    " - `similarity_plot_settings`: Controls the appearance of the distribution.\n",
    "     - `plot_color`: Can be any color recognized by the _matplotlib_ library.\n",
    "     - `shade`: `True` or `False`, whether or not to shade in the area under the curve.\n",
    " \n",
    " - `embedding_plot_settings`: Constrols the lower dimensional embedding of the dataset.\n",
    "     - `plot_title`: String containing text to be written above the plot.\n",
    "     - `embedding`: Set the algorithmic aspects of the embedding\n",
    "         - `method`: Label specifying the algorithm embedding the molecule set in 2 dimensions.\n",
    "         - `params`:  Specific hyperparameters which are passed through to the underlying implementation\n",
    "             - `random_state`: Number used for seeding stochastic algorithms\n",
    "\n",
    "##### Property Variation Visualization\n",
    "Creates a plot of how a given property in the input molecule set varies according to the structural fingerprint chosen.\n",
    " - `log_file_path`: String specifying a file to write output to for the execution of this task. Useful for debugging or retrospection.\n",
    "     - `property_plot_settings`: Control the appearance of the plot.\n",
    "       - `plot_color`: Any color recognized by the _matplotlib_ library.\n",
    "  \n",
    "##### Identify Outliers\n",
    "Trains an [IsolationForest](https://scikit-learn.org/stable/modules/generated/sklearn.ensemble.IsolationForest.html) on the input data to check for potential outliers.\n",
    " - `random_state`: An integer to pass through to random_state in sklearn. _AIMSim_ sets this to 42 by default.\n",
    " - `output`: A string which specifies where the output of the outlier search should go. This can be either a filepath or \"terminal\" to write the output directly to the terminal.\n",
    " - `plot_outliers`: Set this to `True` to generate a 2D plot of which molecules are potential outliers.\n",
    " - `pair_similarity_plot_settings`: Only meaningful if plot_outliers is True, allows access to plot settings.\n",
    "     - `plot_color`: Any color recognized by the _matplotlib_ library.\n",
    "       \n",
    "##### Cluster\n",
    "Use a clustering algorithm to make groups from the database of molecules.\n",
    " - `n_clusters`: The number of clusters to group the molecules into.\n",
    "     - `clustering_method`: Optional string specifying a clustering method implemented in `sklearn`, one of `ward`, or `complete_linkage`. `complete_linkage` will be chosen by default if no alternative is provided.\n",
    "     - `log_file_path`: String specifying a file to write output to for the execution of this task. Useful for debugging.\n",
    "     - `cluster_file_path`: String specifying a file path where _AIMSim_ will output the result of clustering. Useful for comparing multiple clustering approaches or saving the results of large data sets.\n",
    "     - `cluster_plot_settings`: Control the appearance of the clustering plot.\n",
    "       - `cluster_colors`: A list of strings, each of which is a color recognized by _matplotlib_ to use for the clusters. Must specify at least as many colors as there are clusters. Additional colors will be ignored.\n",
    "     - `embedding_plot_settings`: Constrols the lower dimensional embedding of the dataset.\n",
    "         - `plot_title`: String containing text to be written above the plot.\n",
    "         - `embedding`: Set the algorithmic aspects of the embedding\n",
    "             - `method`: Label specifying the algorithm embedding the clustered molecule set in 2 dimensions.\n",
    "             - `params`:  Specific hyperparameters which are passed through to the underlying implementation\n",
    "                 - `random_state`: Number used for seeding stochastic algorithms"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Writing Scripts with _AIMSim_\n",
    "Advanced users may wish to use _AIMSim_ to create their own descriptors, use the descriptor's provided in _AIMSim_ for something else entirely, or utilize the various similarity scores. Brief explanations for how to access the core functionalities of _AIMSim_ from a Python script are shown below."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Making Custom Descriptors\n",
    "Any arbitrary numpy array can be provided as a molecular descriptor, though correct function with the similarity metrics provided with _AIMSim_ is not guaranteed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aimsim.ops.descriptor import Descriptor\n",
    "desc = Descriptor()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With the `Descriptor` class instantiated, one can then call the methods to set the value(s) of the descriptor."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3])"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "custom_desc = np.array([1, 2, 3])\n",
    "desc.set_manually(custom_desc)\n",
    "desc.numpy_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This same function can be achieved by passing in a numpy array for the keyword argument `value` in the constructor for `Descriptor`, as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([1, 2, 3])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "desc = Descriptor(custom_desc)\n",
    "desc.numpy_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above code is useful for individually changing a descriptor for one molecule in a `MoleculeSet` but is obviously not practical for bulk custom descriptors. To assign descriptors for an entire set of molecules at once, instantiate the `MoleculeSet` class and call the `_set_descriptor` method passing in a 2-dimensional numpy array of descriptors."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "from AIMSim.chemical_datastructures.molecule_set import MoleculeSet\n",
    "molset = MoleculeSet(\n",
    "    '/path/to/databse/smiles.txt',\n",
    "    'text',\n",
    "    False,\n",
    "    'tanimoto'\n",
    ")\n",
    "molset._set_descriptor([[1, 2, 3], [4, 5, 6]])\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generating Descriptors with _AIMSim_\n",
    "Because _AIMSim_ is able to generate such a wise variety of molecular fingerprints and descriptors from only the SMILES strings, you may want to avoid re-inventing the wheel and use the descriptors that it generates. There are two general approaches to doing this, and the approach used depends on what other code you already have in place:\n",
    " 1. If you have only SMILES strings to turn into fingerprints/descriptors, the `Molecule` class should be used to handle generating the molecule object and generating the descriptors.\n",
    " 2. If you have already created a molecule using `RDKit`, you must provide the existing molecule in your call to the constructor in `Molecule`.\n",
    "These approaches are covered in this order below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 0, 0, ..., 0, 0, 0], dtype=int8)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# with a SMILES string\n",
    "smiles = \"CO\"\n",
    "from aimsim.chemical_datastructures.molecule import Molecule\n",
    "mol = Molecule(mol_smiles=smiles)\n",
    "mol.set_descriptor(fingerprint_type=\"atom-pair_fingerprint\")\n",
    "mol.get_descriptor_val()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([6])"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# with an RDKit molecule\n",
    "from rdkit import Chem\n",
    "\n",
    "mol_graph = Chem.MolFromSmiles(smiles)\n",
    "\n",
    "mol = Molecule(mol_graph=mol_graph)\n",
    "mol.set_descriptor(fingerprint_type=\"mordred:nAtom\")\n",
    "mol.get_descriptor_val()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Acessing _AIMSim_ Similarity Metrics\n",
    "As of January 2022, _AIMSim_ implements 47 unique similarity metrics for use in comparing two numbers and/or two sets of numbers. These metrics were pulled from a variety of sources, including some original implementations, so it may be of interest to use this code in your own work.\n",
    "\n",
    "All of the similarity metrics can be accessed through the `SimilarityMeasure` class, as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.22360679774997896"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from aimsim.ops.similarity_measures import SimilarityMeasure\n",
    "from rdkit.Chem import MolFromSmiles\n",
    "\n",
    "sim_mes = SimilarityMeasure(\"driver-kroeber\")\n",
    "desc_1 = Descriptor()\n",
    "desc_1.make_fingerprint(\n",
    "    MolFromSmiles(\"COC\"),\n",
    "    \"morgan_fingerprint\",\n",
    ")\n",
    "desc_2 = Descriptor()\n",
    "desc_2.make_fingerprint(\n",
    "    MolFromSmiles(\"CCCC\"),\n",
    "    \"morgan_fingerprint\",\n",
    ")\n",
    "out = sim_mes(\n",
    "    desc_1,\n",
    "    desc_2,\n",
    ")\n",
    "out"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A complete list of supported similarity measures and the names by which _AIMSim_ recognizes them is listed in the GUI walkthrough section."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using AIMSim Tasks inside custom Python pipelines"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this section we will take a look at using some of the Tasks provided by AIMSim inside custom Python scripts."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Visualizing a Dataset"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we create the dataset which consists of 100 samples, each containing 3 features. We will first create an Excel file and load that file via _AIMSim_ to visualize it. <b>Note that </b> columns corresponding to sample names or features in the Excel have to be prefixed by <i>'descriptor_'</i> \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%capture\n",
    "!pip install openpyxl  # for using the excel writer\n",
    "\n",
    "import pandas as pd\n",
    "from numpy.random import random\n",
    "\n",
    "n_samples = 100\n",
    "dataset = {'descriptor_f1': random(size=n_samples),\n",
    "          'descriptor_f2': random(size=n_samples),\n",
    "          'descriptor_f3': random(size=n_samples)}\n",
    "df = pd.DataFrame(dataset)\n",
    "dataset_file = 'dataset.xlsx'\n",
    "df.to_excel(dataset_file)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First we load the data into a MoleculeSet object. We use the arbitrary features defined above and L2- similarity to define the similarity in this feature space."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aimsim.chemical_datastructures import MoleculeSet\n",
    "\n",
    "\n",
    "# load a MoleculeSet from the file\n",
    "molecule_set = MoleculeSet(\n",
    "    molecule_database_src=dataset_file,\n",
    "    molecule_database_src_type=\"excel\",\n",
    "    similarity_measure=\"l2_similarity\",\n",
    "    is_verbose=False,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we visualize it using the VisualizeDataset Task. \n",
    "Note that the arguments to the VisualizeDataset constructor are used to edit the plot settings (such as colors and axis labels) as well as the type and parameters of the 2D embedding (here we use PCA to embed the dataset in 2 dimensions). A complete list of the keywords accepted and their default values can be found in the docstring of the constructor in our [documentation page](https://vlachosgroup.github.io/AIMSim/). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aimsim.tasks import VisualizeDataset\n",
    "# instantiate the task\n",
    "viz = VisualizeDataset(embedding_plot_settings={\"embedding\": {\"method\": \"pca\"}})\n",
    "viz(molecule_set)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Clustering"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dataset can also be clustered using the ClusterData Task in _AIMSim_. The following code snippets clusters the dataset using the K-Medoids algorithm. Note that we reuse the MoleculeSet object, therefore we are still using the L2 similarity for clustering. The data is clustered into 5 clusters and the 2D embedding is again generated using PCA. A complete list of the keywords accepted by the ClusterData constructor and their default values can be found in the docstring of the constructor in our [documentation page](https://vlachosgroup.github.io/AIMSim/). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from aimsim.tasks import ClusterData\n",
    "\n",
    "clustering = ClusterData(\n",
    "    n_clusters=5,  # data is clustered into 5 clusters\n",
    "    clustering_method=\"ward\",\n",
    "    embedding_plot_settings={\"embedding\": {\"method\": \"pca\"}},\n",
    ")\n",
    "clustering(molecule_set)"
   ]
  }
 ],
 "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.12.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}