{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "faa87047",
   "metadata": {},
   "source": [
    "# Structural Search\n",
    "\n",
    "This notebook demonstrates two structural-search workflows. The first uses the live NIST Chemistry WebBook structural-search endpoint. The second searches a tiny local CSV index fixture using RDKit and the indexed InChI/InChIKey fields.\n",
    "\n",
    "RDKit is required for SMILES/InChI conversion and for local structural search. Install it with `pip install -e \".[structure]\"` or with `conda install -c conda-forge rdkit`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "80c62a06",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T17:38:18.839482Z",
     "iopub.status.busy": "2026-05-20T17:38:18.839294Z",
     "iopub.status.idle": "2026-05-20T17:38:19.334941Z",
     "shell.execute_reply": "2026-05-20T17:38:19.334401Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "True\n"
     ]
    }
   ],
   "source": [
    "import nistchempy as nist\n",
    "\n",
    "molblock = nist.molblock_from_smiles('c1ccccc1')\n",
    "print(molblock.splitlines()[0])\n",
    "print('M  END' in molblock)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4748dfe3",
   "metadata": {},
   "source": [
    "## Live WebBook structural search\n",
    "\n",
    "The live structural search sends a MOL block to the WebBook. Passing a MOL file or MOL block does not require RDKit, but this example uses RDKit to convert SMILES to a MOL block first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "bd9317fd",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T17:38:19.336386Z",
     "iopub.status.busy": "2026-05-20T17:38:19.336142Z",
     "iopub.status.idle": "2026-05-20T17:38:20.222826Z",
     "shell.execute_reply": "2026-05-20T17:38:20.222343Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(True, 1, ['C71432'])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "search = nist.run_structural_search(\n",
    "    smiles='c1ccccc1',\n",
    "    search_type='struct',\n",
    ")\n",
    "search.success, search.num_compounds, search.compound_ids[:5]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d09b6d5",
   "metadata": {},
   "source": [
    "## Local structural search over an index\n",
    "\n",
    "The local index stores InChI and InChIKey values. With RDKit installed, NistChemPy can screen those indexed structures locally. This is a linear scan over the CSV table, not a persistent fingerprint database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "0bbdbfe5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T17:38:20.224024Z",
     "iopub.status.busy": "2026-05-20T17:38:20.223896Z",
     "iopub.status.idle": "2026-05-20T17:38:20.247426Z",
     "shell.execute_reply": "2026-05-20T17:38:20.246872Z"
    }
   },
   "outputs": [
    {
     "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>ID</th>\n",
       "      <th>name</th>\n",
       "      <th>formula</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>C71432</td>\n",
       "      <td>Benzene</td>\n",
       "      <td>C6H6</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "       ID     name formula\n",
       "1  C71432  Benzene    C6H6"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "index_path = Path('example_index.csv')\n",
    "if not index_path.exists():\n",
    "    index_path = Path('docs/source/example_index.csv')\n",
    "\n",
    "index = nist.get_local_index(index_path)\n",
    "index.structural_search(\n",
    "    smiles='c1ccccc1',\n",
    "    mode='exact',\n",
    ").loc[:, ['ID', 'name', 'formula']]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "396d34d2",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-05-20T17:38:20.248768Z",
     "iopub.status.busy": "2026-05-20T17:38:20.248611Z",
     "iopub.status.idle": "2026-05-20T17:38:20.270676Z",
     "shell.execute_reply": "2026-05-20T17:38:20.270175Z"
    }
   },
   "outputs": [
    {
     "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>ID</th>\n",
       "      <th>name</th>\n",
       "      <th>formula</th>\n",
       "      <th>similarity</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>C64175</td>\n",
       "      <td>Ethanol</td>\n",
       "      <td>C2H6O</td>\n",
       "      <td>1.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "       ID     name formula  similarity\n",
       "2  C64175  Ethanol   C2H6O         1.0"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "index.structural_search(\n",
    "    smiles='CCO',\n",
    "    mode='similarity',\n",
    "    threshold=0.1,\n",
    ").loc[:, ['ID', 'name', 'formula', 'similarity']]"
   ]
  }
 ],
 "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.13.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}