06_molecular_visualization.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "667a2266-cb12-4121-a78a-1fb24721dea5",
   "metadata": {},
   "source": [
    "## Molecular Visualization with iCN3D\n",
    "### Overview\n",
    "#### Questions\n",
    "1. How do you incorporate iCN3D into a Jupyter Notebook?\n",
    "1. How do you view structures from PDB files in iCN3D?  \n",
    "1. How do you superimpose structures in iCN3D in a Jupyter Notebook?\n",
    "1. How can you control the renderings of features of a protein in iCN3D?\n",
    "\n",
    "#### Objectives\n",
    "\n",
    "- Learn to load the iCN3D app\n",
    "- Identify controls that are available within the iCN3D window in a Jupyter Notebook\n",
    "- Implement commands captured from an iCN3D web page in a Jupyter notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f44082a-4b81-4554-8178-113fecd73685",
   "metadata": {},
   "source": [
    "## iCN3D and Molecular Visualization\n",
    "iCN3D is a molecular viewer that is provided by the National Center for Biotechnology Information and integrated into many of their web pages. Here is a [link](https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html) that enables you to open an iCN3D web page and load a PDB structure of interest. In fact, Henry Jakubowski has created an extensive collection of [iCN3D web pages](https://bio.libretexts.org/Learning_Objects/Visualizations_and_Simulations/Biochemistry-iCn3D_Molecular_Models) to support his [Biochemistry textbook offered through Libretext](https://bio.libretexts.org/Bookshelves/Biochemistry). \n",
    "\n",
    "### Loading the iCN3D library\n",
    "As we have seen previously, the `import` command is used to load iCN3D into your Jupyter notebook. Be careful to use the exact name of the library, all in lower case letters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ecfadfa2-ed31-4876-bf60-750bcb95619d",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "856c9139-96dd-4c9f-ae57-db81d5578e50",
   "metadata": {},
   "source": [
    "### Viewing a PDB structure\n",
    "As a first step, we will simply load a PDB structure in the default representation provided when you use the icn3dpy.view command for Jupyter notebooks. Please note that you can substitute in any structure id of interest using the format 'pdbid = xxxx'. If you have a favorite structure, use that instead of 1a0j."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba4a7cad-be45-4200-b696-b129cee16335",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "968f3b42-de02-4d6e-81f1-4df474d8fc16",
   "metadata": {},
   "source": [
    "### Applying the power of python\n",
    "The above approach offers no real advantages over simply using an [iCN3D web page](https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html) to view your structure, so we are going to create some variables and functions that will enable you to quickly generate your desired views of many different PDB entries using simple commands. \n",
    "We will use the `icn3dpy.view` function. It requires an argument, `q` that gives information about the molecule we'd like to visualize.\n",
    "\n",
    "```python\n",
    "view = icn3dpy.view(q='pdbid=1a0j')\n",
    "view\n",
    "```\n",
    "\n",
    "This can be replaced with another variable that contains the string. Let's try that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "426a29f6-d21b-4369-ac89-c61fc15c4232",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Replacing the 'pdbid=1a0j' string with a variable\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6637c10-2136-4bfd-977f-335e5c395cb4",
   "metadata": {},
   "source": [
    "### Adding commands to the icn3dpy.view function\n",
    "It is possible to add commands to the icn3dpy.view function to create a different view. You can find a list of commands on the [iCN3D menuicon page](https://www.ncbi.nlm.nih.gov/Structure/icn3d/icn3d.html#commands). Let's consider a few examples and then explore additional ways to control them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c582fb0b-2554-47af-b1ce-97f2188f04fa",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adding this command string with the syntax shown to change the appearance\n",
    "# of the protein from strands to cylinder and plate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "25a24105-092c-4693-a33b-fbfa699486e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change the heme group to ball and stick\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "9078d815-0f5b-48c7-857e-66306729bfbe",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Assigning command strings to variables\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "fd64325e-c028-4668-8876-765ce3091d1e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Do the same thing with a different protein\n",
    "# Assigning command strings to variables\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f1048b69-7c41-4d25-bdcd-29ad2f9550f4",
   "metadata": {},
   "source": [
    "# Pulling collections of commands from an iCN3D web page\n",
    "You can imagine that it might be quite time consuming to make 8 or 10 modifications to a visualization using commands like those seen above. One of the features of iCN3D web pages is that you can create a view there and import the commands into a Jupyter notebook. In this [iCN3D page for PDB ID 1ETS](https://structure.ncbi.nlm.nih.gov/icn3d/share.html?TmUEcZr72jbmKirq9), the following steps were taken: \n",
    "\n",
    "- the ligand was changed to ball and stick; \n",
    "- the protein was changed from ribbon to cylinder and plate; \n",
    "- the color was changed to represent secondary structures; \n",
    "- the background was changed to white. \n",
    "\n",
    "The resulting page looks like this:\n",
    "![modified image of 1ETS](images/1ets.png \"modified image of 1ETS\")\n",
    "\n",
    "There is a feature on an iCN3D web page that enables you to modify the structure on the page and reproduce the structure in a Jupyter notebook. Why would you want to do that? We'll get to that in a bit.\n",
    "\n",
    "On the [iCN3D page for PDB ID 1ETS](https://structure.ncbi.nlm.nih.gov/icn3d/share.html?TmUEcZr72jbmKirq9), select `File` from the dropdown menu, then choose `Share Link` and it will bring up a dialog box. \n",
    "\n",
    "![dialog box from modified 1ETS](images/dialog_box.png \"modified image of 1ETS\")\n",
    "\n",
    "Simply go to 2. `Commands Used in Jupyter Notebooks` and click on `Copy Commands`. Then paste those commands into a code cell on your Jupyter notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1e820e77-80a7-455f-aea3-14d978600f64",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "5531d9c6-77ca-46c6-88f4-de4f76bd98bc",
   "metadata": {},
   "source": [
    "### Teasing apart the command set from the [iCN3D page for PDB ID 1ETS](https://structure.ncbi.nlm.nih.gov/icn3d/share.html?TmUEcZr72jbmKirq9)\n",
    "\n",
    "If you explore the collected list of commands we extracted from the iCN3D page, you can see that the PDB ID was used three times:\n",
    "\n",
    "1. in the form of mmdbafid=1ETS early in the line of code *icn3dpy.view(q = 'mmdbafid=1ETS')*\n",
    "2. in the form of 1ets in the phrase *load mmdb 1ets*\n",
    "3. in the form of 1ets in the phrase *&mmdbid=1ets&bu=1*\n",
    "\n",
    "We are going to substitute variables in this command set so that you could generate the same view for almost any PDB entry. Remember that this set of commands is a string, so we have to be careful with the syntax. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "68f9d3a5-3774-42db-a43e-c16c77157253",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "f1c4b4ca-1fa1-46fc-9da9-407471047179",
   "metadata": {},
   "source": [
    "# Creating functions based on preferred command sets generated from iCN3D web pages\n",
    "\n",
    "The use of variables to control the appearance of any PDB entry is pretty cool. Wouldn't it be great if you could enter a simple command with a PDB ID and have it do this? We can if we define and use a `function`. Here is some text from nonlinear regression part 2 to remind us how to work with functions. \n",
    "\n",
    "In Python, the following syntax is used to declare a function:\n",
    "\n",
    "```python\n",
    "def function_name(independent_variable, parameter1, parameter2):\n",
    "    ** function body code **\n",
    "    return value_to_return\n",
    "```\n",
    "\n",
    "Functions are defined using the `def` keyword, followed by the name of the function. The function may have independent variable(s) and parameters which are passed to it; these are in parenthesis following the function name. You then add a colon after the parentheses. This causes the function body code to indent in a Jupyter notebook coding cell. In certain cases, a function may have no parameters as well. Most (though not all) functions return some type of information. It is important to note here that defining a function does not execute it.\n",
    "\n",
    "Now we will create a function for a predesigned view in an iCN3D cell in a Jupyter notebook, using the code from the [iCN3D page for PDB ID 1ETS](https://structure.ncbi.nlm.nih.gov/icn3d/share.html?TmUEcZr72jbmKirq9)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d004438f-3fc4-443f-b1da-3162d6780078",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f05eba53-7dc4-428a-8908-8b94b10205a6",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "9b8f65f1-3dbf-4237-9432-a37287ebb52e",
   "metadata": {},
   "source": [
    "<div class=\"exercise-this-is-a-title exercise\">\n",
    "<p class=\"exercise-title\"><b>Exercise</b></p>\n",
    "    <p>Create an iCN3D visualization on an <a href=\"https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html\">iCN3D web page</a>, using PDB entry 1ETS. Here is a suggestion, but you can try anything you like, especially if you are familiar with iCN3D. Once you have the view you like, capture the commands and transfer them to a new cell in this Jupyter notebook. </p>\n",
    "    \n",
    "    <ul>\n",
    "        <li>Style > Proteins > Strand</li>\n",
    "        <li>Color > Secondary > Sheet in Yellow</li>\n",
    "        <li>Style > Background > Gray</li>\n",
    "    \n",
    "\n",
    "    \n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b80737cf-83b3-47f3-a7f7-8fb3a6dcd2d3",
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "id": "f0019c3c-7460-400e-b7a3-156ff8f88b28",
   "metadata": {},
   "source": [
    "### Take Home Exercise\n",
    "\n",
    "Create two or more views on an [iCN3D web page](https://www.ncbi.nlm.nih.gov/Structure/icn3d/full.html) that you would like to use frequently in your research or teaching. For example, you might have one preferred view for an enzyme, another for a transcription factor bound to DNA, and a third to illustrate an antibody/antigen interaction. Once you have completed one of the views, transfer those commands into a Jupyter notebook you could use for any structure. Try them on multiple different structures. *Advanced*: Create and name variables (or even a `function`) that represents each of your preferred views and change the structure simply by entering the PDB ID in the cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a99d8eab-a497-4b2a-965c-bf0f103e6b32",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}