Merge pull request #39 from dominiquesydow/update-dyno-notebook

Update dyno notebook

Author: dominiquesydow

docs/tutorials/dynophore.ipynb

@@ -412,9 +412,7 @@
     }
    ],
    "source": [
-    "view = view3d.show(\n",
-    "    dynophore, pdb_path, visualization_type=\"spheres\", select_cloud_range=[900, 1000]\n",
-    ")\n",
+    "view = view3d.show(dynophore, pdb_path, visualization_type=\"spheres\", frame_range=[900, 1000])\n",
     "view.display(gui=True, style=\"ngl\")"
    ]
   },

docs/tutorials/explore_view3d.ipynb

@@ -4,14 +4,38 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Dynophore notebook\n",
+    "# Dynophore notebook"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Introduction"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### What is a dynophore?\n",
     "\n",
-    "This notebook contains the following dynophore analyses:\n",
+    "* A **dynophore** is a collection of so-called superfeatures. \n",
+    "* A **superfeature** is defined as a pharmacophore feature on the ligand side — defined by a feature type and one or more ligand atoms — that occurs at least once during an MD simulation. Example: HBA[4618] (feature type, ligand atom numbers)\n",
+    "* A superfeature has a **point cloud**, where each point corresponds to the centroid of feature during one frame of the trajectory.\n",
+    "* A superfeature can have one or more interaction partner(s) on the macromolecule side. These interaction partners are called **environmental partners**. Example: GLN-131-A[2057] (residue name, residue number, chain, atom serial numbers)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### How to work with a dynophore?\n",
     "\n",
-    "- __2D view__ of the dynophore's superfeatures mapped onto the structure-bound ligand using `rdkit`.\n",
-    "- __3D view__ of the dynophore's point clouds (one cloud per superfeature) using `nglview` allows easy visual inspection of the dynamic macromolecule-ligand interactions. Point clouds are rendered alongside the topology and (optionally) the trajectory underlying the dynophore.\n",
-    "- __Statistics__ cover the occurrence of superfeatures and their environmental partners as well as distances between them.\n",
-    "- __Dynophore data__ can be further analyzed conveniently right here in this notebook by working with the `Dynophore` class."
+    "* **Dynophore raw data** can be analyzed conveniently right here in this notebook by working with the `Dynophore` class.\n",
+    "* **Dynophore 2D view** shows all superfeatures on a 2D view of the structure-bound ligand using `rdkit`.\n",
+    "* **Dynophore 3D view** maps each superfeature's point cloud in 3D using `nglview`, allowing for an easy visual inspection of the dynamic macromolecule-ligand interactions. Point clouds are rendered alongside the complex structure's topology and (optionally) the trajectory underlying the dynophore.\n",
+    "* **Dynophore statistics** cover the occurrence of superfeatures and their environmental partners as well as distances between them."
    ]
   },
   {
@@ -44,17 +68,14 @@
     "import nglview as nv\n",
     "\n",
     "# Import Dynophore class - contains all dynophore data\n",
-    "from dynophores import Dynophore\n",
-    "\n",
-    "# Load modules for 3D viewing and plotting\n",
-    "from dynophores import view2d, view3d, plot"
+    "import dynophores as dyno"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Set paths"
+    "## Set data paths"
    ]
   },
   {
@@ -79,7 +100,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Load data as `Dynophore` object"
+    "## Load data as `Dynophore` object\n",
+    "\n",
+    "You can load the dynophore data as `Dynophore` object. We will need this object below for visualization purposes but you can also use the raw data for your own customized analyses.\n",
+    "\n",
+    "__Note__: Check out [this tutorial](https://dynophores.readthedocs.io/en/latest/tutorials/explore_data.html) on the dynophore's data structure."
    ]
   },
   {
@@ -88,21 +113,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dynophore = Dynophore.from_dir(dyno_path)"
+    "dynophore = dyno.Dynophore.from_dir(dyno_path)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "__Note__: Check out [this tutorial](https://dynophores.readthedocs.io/en/latest/tutorials/explore_data.html) on the dynophore's data structure."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## 2D view"
+    "## 2D view\n",
+    "\n",
+    "Investigate the dynophore's superfeatures in 2D; display the atom serial numbers (those will show up in the superfeatures' identifiers in the plots below)."
    ]
   },
   {
@@ -111,14 +131,34 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "view2d.interactive.show(dynophore)"
+    "dyno.view2d.interactive.show(dynophore)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 3D view"
+    "## 3D view\n",
+    "\n",
+    "Investigate the dynophore in 3D - you have different options that you can change in the method signature below:\n",
+    "\n",
+    "* `pdb_path` and `dcd_path` have been defined at the beginning of this notebook; these are the file paths to your complex structure's topology and trajectory (if you do not want to load the trajectory, set `dcd_path=None`).\n",
+    "* `visualization_type`: `spheres` or `points`\n",
+    "  * [Default] Show each frames features as small spheres with `visualization_type=spheres`.\n",
+    "  * [Work-In-Progress] Render the dynophore cloud as more burred and connected points using `visualization_type=points` (still has some NGL rendering issues that we cannot fix on our end, see [NGL GitHub issue](https://github.com/nglviewer/ngl/issues/868))\n",
+    "* `color_cloud_by_frame`: `False` or `True`\n",
+    "  * [Default] Color cloud by superfeature type. Example: The points belonging to a HBA-based superfeature will all be colored red.\n",
+    "  * Color cloud by superfeature type *and* frame index. Example: The points belonging to a HBA-based superfeauture will be colored from red (first frame) to light red (last frame).\n",
+    "* `macromolecule_color`: Set a color for the macromolecule; defaults to blue.\n",
+    "* `frame_range`: Show a selected frame range only, e.g. `frame_range=[100, 1000]`. By default, all frames are shown with `frame_range=None`.\n",
+    "\n",
+    "Interact directly with the 3D visualization using the NGL GUI:\n",
+    "\n",
+    "* Toogle on/off macromolecule > *cartoon*\n",
+    "* Toogle on/off ligand > *hyperball*\n",
+    "* Toogle on/off pocket residue side chains > *licorice*\n",
+    "* Toogle on/off superfeatures > superfeature identifier e.g. *HBA[4618]*\n",
+    "* Run trajectory if loaded"
    ]
   },
   {
@@ -127,16 +167,23 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "view = view3d.show(dynophore, pdb_path, dcd_path)\n",
-    "view.display(gui=True, style=\"ngl\")\n",
-    "# NOTE: You might need to run this cell twice for the content to show up"
+    "view = dyno.view3d.show(\n",
+    "    dynophore,\n",
+    "    pdb_path=pdb_path,\n",
+    "    dcd_path=dcd_path,\n",
+    "    visualization_type=\"spheres\",\n",
+    "    color_cloud_by_frame=False,\n",
+    "    macromolecule_color=\"#005780\",\n",
+    "    frame_range=None,\n",
+    ")\n",
+    "view.display(gui=True, style=\"ngl\")"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "In case a trajectory is Load the `TrajectoryPlayer` for more visualization options:"
+    "In case a trajectory is loaded, use the `TrajectoryPlayer` for more visualization options:"
    ]
   },
   {
@@ -157,9 +204,13 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "source": [
-    "### Plot interactions overview (heatmap)"
+    "### Plot interactions overview (heatmap)\n",
+    "\n",
+    "Check how often each superfeature interacts with which environmental partners throughout the MD simulation (in %)."
    ]
   },
   {
@@ -168,14 +219,18 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.interactive.superfeatures_vs_envpartners(dynophore)"
+    "dyno.plot.interactive.superfeatures_vs_envpartners(dynophore)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Plot superfeature occurrences (time series)"
+    "### Plot superfeature occurrences (time series)\n",
+    "\n",
+    "Check when (barcode) and how often (in %) a superfeature $S$ occurs throughout the MD simulation.\n",
+    "\n",
+    "$S\\,\\text{occurrence [%]} = \\frac{\\text{Number of frames in which}\\,S\\,\\text{occurs}}{\\text{Number of frames}} \\times 100$"
    ]
   },
   {
@@ -184,7 +239,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.interactive.superfeatures_occurrences(dynophore)"
+    "dyno.plot.interactive.superfeatures_occurrences(dynophore)"
    ]
   },
   {
@@ -198,7 +253,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Interaction occurrence"
+    "#### Interaction occurrence\n",
+    "\n",
+    "Check when (barcode) and how often (in %\\) each environmental partner $E$ interacts in context of a superfeature $S$ ($E_S$).\n",
+    "\n",
+    "$E_S\\,\\text{occurrence [%]} = \\frac{\\text{Number of frames where}\\,E\\,\\text{interacts in context of}\\,S}{\\text{Number of frames where}\\,S\\,\\text{occurs}} \\times 100$"
    ]
   },
   {
@@ -207,14 +266,19 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.interactive.envpartners_occurrences(dynophore)"
+    "dyno.plot.interactive.envpartners_occurrences(dynophore)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Interaction distances"
+    "#### Interaction distances\n",
+    "\n",
+    "Check for each superfeature, the distances to all environmental partners throughout the MD simulation. \n",
+    "\n",
+    "* **Time series**: Distances are shown for all frames regardless of whether that frame shows an interaction between the environmental partner and the superfeature's ligand atoms or not. Interactions are indicated with a dot in the plot.\n",
+    "* **Histogram**: Only distances are shown that belong to frames in which an interaction between the environmental partner and the superfeature's ligand atoms ocurrs."
    ]
   },
   {
@@ -223,14 +287,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.interactive.envpartners_distances(dynophore)"
+    "dyno.plot.interactive.envpartners_distances(dynophore)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Interaction profile (all-in-one)"
+    "#### Interaction profile (all-in-one)\n",
+    "\n",
+    "This is a summary of the plots shown above. Note that in this case *all* distances throughout the MD simulation are shown (regardless of whether the frame shows an interaction or not)."
    ]
   },
   {
@@ -239,7 +305,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "plot.interactive.envpartners_all_in_one(dynophore)"
+    "dyno.plot.interactive.envpartners_all_in_one(dynophore)"
    ]
   }
  ],

dynophores/notebooks/dynophore.ipynb

@@ -18,7 +18,7 @@
 
 
 @pytest.mark.parametrize(
-    "pdb_path, dcd_path, visualization_type, color_cloud_by_frame, select_cloud_range",
+    "pdb_path, dcd_path, visualization_type, color_cloud_by_frame, frame_range",
     [
         (PATH_TEST_DATA / "in/startframe.pdb", None, "spheres", False, None),
         (
@@ -33,20 +33,20 @@
     ],
 )
 def test_show(
-    dynophore, pdb_path, dcd_path, visualization_type, color_cloud_by_frame, select_cloud_range
+    dynophore, pdb_path, dcd_path, visualization_type, color_cloud_by_frame, frame_range
 ):
     view3d.show(
         dynophore,
         pdb_path,
         dcd_path=dcd_path,
         visualization_type=visualization_type,
         color_cloud_by_frame=color_cloud_by_frame,
-        select_cloud_range=select_cloud_range,
+        frame_range=frame_range,
     )
 
 
 @pytest.mark.parametrize(
-    "pdb_path, dcd_path, visualization_type, color_cloud_by_frame, select_cloud_range",
+    "pdb_path, dcd_path, visualization_type, color_cloud_by_frame, frame_range",
     [
         (PATH_TEST_DATA / "in/startframe.pdb", None, "xxx", None, None),  # Unknown viz type
         (
@@ -66,7 +66,7 @@ def test_show(
     ],
 )
 def test_show_raises(
-    dynophore, pdb_path, dcd_path, visualization_type, color_cloud_by_frame, select_cloud_range
+    dynophore, pdb_path, dcd_path, visualization_type, color_cloud_by_frame, frame_range
 ):
 
     with pytest.raises(ValueError):
@@ -76,5 +76,5 @@ def test_show_raises(
             dcd_path=dcd_path,
             visualization_type=visualization_type,
             color_cloud_by_frame=color_cloud_by_frame,
-            select_cloud_range=select_cloud_range,
+            frame_range=frame_range,
         )