Example: Plot drug binding hotspots w/ NGLView

[dwhswenson]

Consider drug binding. I thought it might be interesting to visualize the per-residue contact frequency on the protein itself, using NGLView.

Per-residue coloring had been hidden API in NGLView, and had changed since the last time I used it. So after finding the fix (nglviewer/nglview#491 (comment)), I asked @hainm if it could join the public API and he said that he'd make it a priority! (Thanks!)

This PR will be updated once the official NGLView API is in place. I mainly want it up so that @hainm can see my use case. I may add other functions to the main code to facilitate this, as well, or we might leave it as an advanced example (I've heavily commented the fancier bits of code that would perhaps be moved to a function).

With the GSK3B trajectory that we already have in the repo, the results are kind of dull (and maybe viridis isn't the best color map):

Maybe I should ask for one of those DE Shaw trajectories -- not to put in the repo, but it might make a nice example for the paper!

[hainm]

Unfortunately, the NGLView widget (which allows you to rotate the molecule, run the trajectory, zoom in, etc.) can't be converted to HTML.

This is not true anymore. :D

You can use the latest version, and either use

• nglview.write_html('index.html', view)
• Or: https://ipywidgets.readthedocs.io/en/latest/embedding.html

So that you can view a snapshot of the live notebook in nbviewer: https://nbviewer.jupyter.org/github/arose/nglview/blob/master/notebooks/gui.ipynb

Related issues:

• coloring lost with write_html nglviewer/nglview#802
• ADD: embed trajectory (or write_html) nglviewer/nglview#687

[dwhswenson]

Cool! Thanks, and I'll try that out! (I'll also have to check through some of the OpenPathSampling examples, which I think will also benefit from that.)

[hainm]

Should be available in v2.6.7: nglviewer/nglview#839
(there's still one outstanding issue with embedding html: nglviewer/nglview#840)

cheers.

[hainm]

The selection scheme does not work with color as integer, so you might want to convert to hex.

[hainm]

I have additional comments while playing with your notebook:

• Use default=False to avoid initial repr

view = nv.show_mdtraj(traj, default=False)
view.center()
# view.clear() # don't need this anymore
view.add_cartoon(selection='protein', color="contacts")
view

• You might try to use view.gui_style = 'ngl' which turns on the nice GUI in NGL (http://nglviewer.org/ngl/)

• you might want to superpose and smooth the traj (mdtraj has it).
  cheers.

[dwhswenson]

@hainm : Could you glance over the text in the notebook section "Creating the NGLView color mapping"? I just want to be sure that I'm accurately describing things. (And thanks for the other suggestions -- in particular, I hadn't been aware of default=False; that will be useful for a lot of things!)

@sroet : This is ready for review. I think I prefer to leave this as "make the user do the conversion", because (1) it's about 7 lines of code; (2) it is only relevant if you're looking at contacts with just 1 residue (this would not work for visualizing protein-protein interfaces); and (3) it goes to the narrative I'm always pushing about a scientific software ecosystem, where it is easy to get the pieces to talk to each other.

A quick summary of what's in this PR:

• new example notebook showing how to visualize the frequency each residue is in contact with a drug molecule on an image of the protein itself, by interfacing with NGLView
• new plotting helper functions to get colors and associated unit tests (I really wish that these functions were matplotlib built-ins)
• updates to docs configuration so that nbsphinx can show the NGLView widget (and CSS fixes that were needed after)

Still desired: a way to get nbsphinx to include some NGLView output when it generates PDF output. It might be possible by editing notebook metadata -- I haven't tried that yet.

Note: when merging this one, please squash commits. Every notebook save took a lot of space.

[hainm]

Could you glance over the text in the notebook section "Creating the NGLView color mapping"? I just want to be sure that I'm accurately describing things.

Looks good to me.

Per "where color_* are colors that can be names ('red', 'blue') or can be web-formatted hexadecimal values ('#FF0000', '#0000FF'),", the color can be a predefined scheme too (e.g: atomindex, https://github.com/arose/ngl/blob/master/examples/scripts/color/selection.js)

[sroet]

One small doc change requested.

Also, you might want to reference the command jupyter-nbextension enable nglview --py --sys-prefix at the end of the notebook as a trouble shooting tip (as it took me a bit of effort finding that command after my conda install)

LGTM otherwise

[sroet]

please add slightly more documentation to this keyword (as it was relatively difficult to find in the matplotlib documentation as well)

[jbloom]

Unfortunately, the NGLView widget (which allows you to rotate the molecule, run the trajectory, zoom in, etc.) can't be converted to HTML.

This is not true anymore. :D

You can use the latest version, and either use

• nglview.write_html('index.html', view)
• Or: https://ipywidgets.readthedocs.io/en/latest/embedding.html

So that you can view a snapshot of the live notebook in nbviewer: https://nbviewer.jupyter.org/github/arose/nglview/blob/master/notebooks/gui.ipynb

Related issues:

• arose/nglview#802
• arose/nglview#687

@hainm: This embedding works almost perfectly for me. The one thing that I've noticed is that the orientation of the camera is not saved in the HTML embeddings. Is that possible to fix?

[hainm]

hi @jbloom, it might be fixed according to this issue but I have not tried to fix that in nglview yet.

nglviewer/ngl#687

For the time being, you might want to update the orientation in html file. cheers.