{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Automatic Ligand parameterization tutorial using BioExcel Building Blocks (biobb)\n",
"***\n",
"This tutorial aims to illustrate the process of **ligand parameterization** for a **small molecule**, step by step, using the **BioExcel Building Blocks library (biobb)**. The particular example used is the **Ibuprofen** small compound (3-letter code IBP, Drugbank code [DB01050](https://www.drugbank.ca/drugs/DB01050)), a non-steroidal **anti-inflammatory drug** (NSAID) derived from propionic acid and it is considered the first of the propionics. \n",
"\n",
"**OpenBabel and ACPype** packages are used to **add hydrogens**, **energetically minimize the structure**, and \n",
"**generate parameters** for the **GROMACS** package. With *Generalized Amber Force Field (GAFF)* forcefield and *AM1-BCC* charges. \n",
"***\n",
"**Biobb modules** used:\n",
"\n",
" - [biobb_io](https://github.com/bioexcel/biobb_io): Tools to fetch data to be consumed by the rest of the Biobb building blocks.\n",
" - [biobb_chemistry](https://github.com/bioexcel/biobb_chemistry): Tools to manipulate chemistry data.\n",
" \n",
"### Auxiliar libraries used\n",
"\n",
"* [jupyter](https://jupyter.org/): Free software, open standards, and web services for interactive computing across all programming languages.\n",
"* [nglview](http://nglviewer.org/#nglview): Jupyter/IPython widget to interactively view molecular structures and trajectories in notebooks.\n",
"\n",
"### Conda Installation and Launch\n",
"\n",
"```console\n",
"git clone https://github.com/bioexcel/biobb_wf_ligand_parameterization.git\n",
"cd biobb_wf_ligand_parameterization\n",
"conda env create -f conda_env/environment.yml\n",
"conda activate biobb_ligand_parameterization_tutorial\n",
"jupyter-notebook biobb_wf_ligand_parameterization/notebooks/biobb_ligand_parameterization_tutorial.ipynb\n",
"```\n",
"\n",
"***\n",
"### Pipeline steps:\n",
" 1. [Input Parameters](#input)\n",
" 2. [Fetching Ligand Structure](#fetch)\n",
" 3. [Add Hydrogen Atoms](#addh)\n",
" 4. [Energetically Minimize Hydrogen Atoms](#min)\n",
" 5. [Generating Ligand Parameters](#acpype)\n",
" 6. [Output Files](#output)\n",
" 7. [Questions & Comments](#questions)\n",
" \n",
"***\n",
"\n",
"***"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"***\n",
"## Input parameters\n",
"**Input parameters** needed:\n",
" - **ligandCode**: 3-letter code of the ligand structure (e.g. IBP, Drugbank code [DB01050](https://www.drugbank.ca/drugs/DB01050))\n",
" - **mol_charge**: Molecule net charge (e.g. -1)\n",
" - **pH**: Acidity or alkalinity for the small molecule. Hydrogen atoms will be added according to this pH. (e.g. 7.4)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import nglview\n",
"import ipywidgets\n",
"import os\n",
"\n",
"ligandCode = 'IBP'\n",
"mol_charge = 0\n",
"pH = 7.4"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"***\n",
"## Fetching ligand structure\n",
"Downloading **ligand structure** in **PDB format** from the IRB PDB MIRROR database.
\n",
"Alternatively, a **PDB file** can be used as starting structure.
\n",
"***\n",
"**Building Blocks** used:\n",
"\n",
" - [Ligand](https://biobb-io.readthedocs.io/en/latest/api.html#module-api.ligand) from **biobb_io.api.ligand**\n",
"***"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": false
},
"outputs": [],
"source": [
"# Ligand: Download ligand structure from MMB PDB mirror REST API (https://mmb.irbbarcelona.org/api/)\n",
"# Import module\n",
"from biobb_io.api.ligand import ligand\n",
"\n",
"# Create prop dict and inputs/outputs\n",
"input_structure = ligandCode + '.pdb'\n",
"\n",
"prop = {\n",
" 'ligand_code' : ligandCode\n",
"}\n",
"\n",
"#Create and launch bb\n",
"ligand(output_pdb_path=input_structure,\n",
" properties=prop)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Visualizing 3D structure\n",
"Visualizing the downloaded/given **ligand PDB structure** using **NGL**: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
},
"outputs": [],
"source": [
"#Show small ligand structure\n",
"view = nglview.show_structure_file(input_structure)\n",
"view.add_representation(repr_type='ball+stick', selection='all')\n",
"view._remote_call('setSize', target='Widget', args=['','300px'])\n",
"view.camera='orthographic'\n",
"view"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"***\n",
"## Add Hydrogen Atoms\n",
"Adding **Hydrogen atoms** to the small molecule, according to the given pH.\n",
"***\n",
"**Building Blocks** used:\n",
" - [BabelAddHydrogens](https://biobb-chemistry.readthedocs.io/en/latest/babelm.html#module-babelm.babel_add_hydrogens) from **biobb_chemistry.babelm.babel_add_hydrogens** \n",
"***"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Babel_add_hydrogens: add Hydrogen atoms to a small molecule\n",
"# Import module\n",
"from biobb_chemistry.babelm.babel_add_hydrogens import babel_add_hydrogens\n",
"\n",
"# Create prop dict and inputs/outputs\n",
"output_babel_h = ligandCode + '.H.mol2' \n",
"\n",
"prop = {\n",
" 'ph' : pH,\n",
" 'input_format' : 'pdb',\n",
" 'output_format' : 'mol2'\n",
"}\n",
"\n",
"#Create and launch bb\n",
"babel_add_hydrogens(input_path=input_structure,\n",
" output_path=output_babel_h,\n",
" properties=prop)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Visualizing 3D structure\n",
"Visualizing the **ligand PDB structure** with the newly added **hydrogen atoms** using **NGL**: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
},
"outputs": [],
"source": [
"#Show small ligand structure\n",
"view = nglview.show_structure_file(output_babel_h)\n",
"view.add_representation(repr_type='ball+stick', selection='all')\n",
"view.camera='orthographic'\n",
"view"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"***\n",
"## Energetically minimize Hydrogen Atoms\n",
"Energetically minimize newly added **Hydrogen atoms**.\n",
"***\n",
"**Building Blocks** used:\n",
" - [BabelMinimize](https://biobb-chemistry.readthedocs.io/en/latest/babelm.html#module-babelm.babel_minimize) from **biobb_chemistry.babelm.babel_minimize** \n",
"***"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Babel_minimize: Structure energy minimization of a small molecule after being modified adding hydrogen atoms\n",
"# Import module\n",
"from biobb_chemistry.babelm.babel_minimize import babel_minimize\n",
"\n",
"# Create prop dict and inputs/outputs\n",
"output_babel_min = ligandCode + '.H.min.pdb' \n",
"prop = {\n",
" 'method' : 'sd',\n",
" 'criteria' : '1e-10',\n",
" 'force_field' : 'GAFF'\n",
"}\n",
"\n",
"\n",
"#Create and launch bb\n",
"babel_minimize(input_path=output_babel_h,\n",
" output_path=output_babel_min,\n",
" properties=prop)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Visualizing 3D structure\n",
"Visualizing the **ligand PDB structure** with the newly added **hydrogen atoms**, **energetically minimized**, using **NGL**: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
},
"outputs": [],
"source": [
"#Show small ligand structure\n",
"view = nglview.show_structure_file(output_babel_min)\n",
"view.add_representation(repr_type='ball+stick', selection='all')\n",
"view._remote_call('setSize', target='Widget', args=['','300px'])\n",
"view.camera='orthographic'\n",
"view"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Visualizing 3D structures\n",
"Visualizing all the structures generated so far:\n",
"\n",
" - Original **ligand PDB structure** (left)\n",
" - **Ligand PDB structure** with **hydrogen atoms** (middle)\n",
" - **Ligand PDB structure** with **hydrogen atoms energetically minimized** (right) "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"scrolled": true
},
"outputs": [],
"source": [
"#Show different structures generated (for comparison)\n",
"view1 = nglview.show_structure_file(input_structure)\n",
"view1.add_representation(repr_type='ball+stick')\n",
"view1._remote_call('setSize', target='Widget', args=['250px','300px'])\n",
"view1.camera='orthographic'\n",
"view1\n",
"view2 = nglview.show_structure_file(output_babel_h)\n",
"view2.add_representation(repr_type='ball+stick')\n",
"view2._remote_call('setSize', target='Widget', args=['250px','300px'])\n",
"view2.camera='orthographic'\n",
"view2\n",
"view3 = nglview.show_structure_file(output_babel_min)\n",
"view3.add_representation(repr_type='ball+stick')\n",
"view3._remote_call('setSize', target='Widget', args=['250px','300px'])\n",
"view3.camera='orthographic'\n",
"view3\n",
"ipywidgets.HBox([view1, view2, view3])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\n",
"***\n",
"## Generating ligand parameters\n",
"**Building GROMACS topology** corresponding to the **ligand structure**.\n",
"\n",
"**Force field** used in this tutorial step is **amberGAFF**: [General AMBER Force Field](http://ambermd.org/antechamber/gaff.html), designed for rational drug design.\n",
"\n",
"***\n",
"**Building Blocks** used:\n",
"- [AcpypeParamsGMX](https://biobb-chemistry.readthedocs.io/en/latest/acpype.html#module-acpype.acpype_params_gmx) from **biobb_chemistry.acpype.acpype_params_gmx** \n",
"***"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"# Acpype_params_gmx: Generation of topologies for GROMACS with ACPype\n",
"# Import module\n",
"from biobb_chemistry.acpype.acpype_params_gmx import acpype_params_gmx\n",
"\n",
"# Create prop dict and inputs/outputs\n",
"output_acpype_gro = ligandCode + 'params.gro'\n",
"output_acpype_itp = ligandCode + 'params.itp'\n",
"output_acpype_top = ligandCode + 'params.top'\n",
"output_acpype = ligandCode + 'params'\n",
"prop = {\n",
" 'basename' : output_acpype,\n",
" 'charge' : mol_charge\n",
"}\n",
"\n",
"#Create and launch bb\n",
"acpype_params_gmx(input_path=output_babel_min,\n",
" output_path_gro=output_acpype_gro,\n",
" output_path_itp=output_acpype_itp,\n",
" output_path_top=output_acpype_top,\n",
" properties=prop)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### Visualizing 3D structure\n",
"Visualizing the generated **GROMACS** gro structure corresponding to the parameterized **ligand PDB structure** using **NGL**: "
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"#Show small ligand structure\n",
"view = nglview.show_structure_file(output_acpype_gro)\n",
"view.add_representation(repr_type='ball+stick', selection='all')\n",
"view._remote_call('setSize', target='Widget', args=['','300px'])\n",
"view.camera='orthographic'\n",
"view"
]
},
{
"cell_type": "markdown",
"metadata": {
"variables": {
"output_acpype_gro": "IBPparams.gro",
"output_acpype_itp": "IBPparams.itp",
"output_acpype_top": "IBPparams.top"
}
},
"source": [
"\n",
"## Output files\n",
"\n",
"Important **Output files** generated:\n",
" - {{output_acpype_gro}}: **Structure** of the parameterized ligand in gro (GROMACS) format.\n",
" - {{output_acpype_top}}: **Topology** of the parameterized ligand, including a reference to the {{output_acpype_itp}}.\n",
" - {{output_acpype_itp}}: **Include Topology File (itp)** of the parameterized ligand, including the parameters information: bonds, angles, dihedrals, etc."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"***\n",
"\n",
"\n",
"## Questions & Comments\n",
"\n",
"Questions, issues, suggestions and comments are really welcome!\n",
"\n",
"* GitHub issues:\n",
" * [https://github.com/bioexcel/biobb](https://github.com/bioexcel/biobb)\n",
"\n",
"* BioExcel forum:\n",
" * [https://ask.bioexcel.eu/c/BioExcel-Building-Blocks-library](https://ask.bioexcel.eu/c/BioExcel-Building-Blocks-library)\n"
]
}
],
"metadata": {
"anaconda-cloud": {},
"kernelspec": {
"display_name": "Python 3.8.9 64-bit",
"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.9"
},
"vscode": {
"interpreter": {
"hash": "31f2aee4e71d21fbe5cf8b01ff0e069b9275f58929596ceb00d14d90e3e16cd6"
}
}
},
"nbformat": 4,
"nbformat_minor": 2
}