Repository files navigation

There are many ways to get PyMOL running in JupyterLab. For details on installing both, go to theGitHub Page associated with this project.Go to this project'sGitHub Page for a list of the snippets and their descriptions.

• Motivation
• New to scripting in PyMOL
• Tech Stack
• Installation
• Configuration Setup
• Usage
• Testing
• Requests for new snippets and text editors
• Bug reports
• Roadmaps
• License
• Contact Information
• How to cite

The animation below demonstrates the use of theao.py snippet inJupyterLab to insert 17 lines of code for generating the ambient occlusion effect.

The result of applying a variant of the above code to a 27-nucleotide RNA hairpin is shown below.

There is no option in a pulldown menu inPyMOL to make such an image.A script file with 17 commands is required.This code can be applied to any molecular object that has been loaded intoPyMOL.

Return to Table of Contents

You can store the images generated by PyMOL in oneJupyter Notebook file instead of having dozens of script and image files squirreled away in dozens of subfolders.Using one file makes it easier to find the code to make a particular figure because the code can be placed above the image.This ability to quickly find the required code at a later time reduces the resistance to remaking a figure for manuscript resubmission, journal cover artwork, posters, platform presentations, lectures, book chapters, review articles, websites, and wall hangings.

Using one file also eases sharing images with collaborators because only one file needs to be shared.If your collaborators are not PyMOL or Jupyter Notebook users, you can reformat the notebook as a static HTML or PDF file.

During a molecular structure analysis project, you can run additional software from the same notebook (e.g., bio3d, ProDy, cctbx, phenix, ccp4, ccpem, XDS).This can improve the reproducibility of the computational aspects of your research.

The primary caveat is that the nonPython software will require different kernels.This caveat means that you will have to switch kernels to use these packages in the same notebook and that you cannot run software with different kernels in the same cell.These are minor limitations.

A secondary caveat is that some heavily used structural biology programs have yet to migrate from Python2 to Python3.You may have trouble running a Python2 kernel inJupyterLab installed to run with Python3.Fortunately, you can run many of these programs by using the shell magic in the notebook.This cell magic allows you to store the input and output in the notebook.This workaround enables you to carry on with your modern reproducible research practices with legacy code.

Return to Table of Contents

1. There is nothing stopping you from running the PyMOL GUI next to yourJupyterLab session. You can adjust the molecule's orientation manually, run theget_view command, copy the output in the command history window from PyMOL, and paste it into a cell in theJupyter Notebook. The one line of settings returned by therv shortcut is much easier to use. Therv shortcut is in thepymolshortcuts.py script.

2. You will discover that you really do not need the PyMOL viewport. With 10-15 minutes of practice, you can master the rapid iterating of the rotate and translate commands to adjust the molecule's orientation with much greater precision than via manipulation of the mouse. Iteratively issuing the rotate and the translate commands is less likely to cause repetitive stress injury than the use of the mouse to reorient the molecule. These injuries occur frequently when generating numerous molecular graphics images up against a deadline.

Return to Table of Contents

If you are not ready to write PyMOL scripts, please consider usingPyMOL shortcuts to enhance your productivity inPyMOL interactive sessions.For example, the above ambient occlusion effect can be invoked at any time by enteringAO at thePyMOL prompt if thepymolshortcuts.py file has been loaded.These shortcuts can also be invoked in aJupyter Notebook by submitting them as arguments to the cmd.do() method, (e.g., cmd.do("AO") to generate the ambient occlusion effect.)

Thejupyterlabpymolpysnips library contains 260 code fragments (i.e., templates or snippets) written in Python to run PyMOL inJupyterLab viaPyMOL'sPython API.This API is only available for recent versions ofPyMOL that depend on Python3.This API is available for both the incentive and open-source versions ofPyMOL.

Return to Table of Contents

You may have to create a new conda env to install the older version of JupyterLab.

Some of the snippets are limited to Python3 code.Suppose you use an outdated version ofPyMOL that relies on Python2. In that case, you can buy a license to the current version ofPyMOL; install a free, open-source version ofPyMOL that depends on Python3 (See thePyMOL Wiki); or you can rewrite the snippet's code to be Python2 compliant.The latter task involves replacing print statements in Python2 with print() functions in Python3.The command-line program2to3 automates this process.Note that multiple versions ofPyMOL can operate side-by-side on a computer, so you do not have to delete that old version ofPyMOL.

JupyterLab can use thejupyterlab-snippets extension to make the snippets available via thesnippets pull-down menu.Conda, pip, or the extension manager inJupyter Lab can install the extension.

Assuming thatJupyterLab,jupyterlab-snippets, andPyMOL are already installed, run the following commands one line at a time,

jupyter --pathcd~/.local/share/jupyter# change as per output from prior line. Use cd ~/Library/Jupyter on the Mac.mkdir snippetscd snippetsgit clone https://github.com/MooersLab/jupyterlabpymolpysnips.git pymolgit clone https://github.com/MooersLab/jupyterlabpymolpysnipsplus.git pymol+

When you openJupyterLab, you will find asnippet pull-down menu on the JupyterLab menu bar.There will be apymol sub-menu and apymol+ sub-menu under this pull-down.

JupyterLab needs to be version >=2.2.0 forjupyterlab-snippets to run.The current version ofJupyterLab is 3.3.4.

You can installNode.js from the Node.js developer's website or with a package manager.It needs to be more recent than version 10.0.0.Beware that Anaconda has in the past installed ancient versions of Node, and you may have to set the version number to install a newer version of Node via Anaconda.You may have better luck using the installer from the developer.Run it in the active conda env where you want to run jupyterlab.

Return to Table of Contents

Alternatively, you can use thejupyterlab-snippets-multimenus package.The package will appear on the menu bar as separate pull-down menus:pymol andpymol+.This approach removes a layer of hierarchy in the pull-down menus, allowing users to select the snippet of interest faster.The downside is that you must use an older version of JupyterLab.

Assuming thatJupyterLab,jupyterlab-snippets-multimenus, and PyMOL are already installed, run the following commands one line at a time:

jupyter --pathcd~/.local/share/jupyter# change as per output from prior line. Use cd ~/Library/Jupyter on the Mac.mkdir multimenus_snippetscd multimenus_snippetsgit clone https://github.com/MooersLab/jupyterlabpymolpysnips.git pymolgit clone https://github.com/MooersLab/jupyterlabpymolpysnipsplus.git pymol+

The snippets in thepymolpysnips+ library have a second copy of the code in a comment with the tab stops marked as follows${1:default value}.Tab stops are sites of parameter values that may need to be edited to customize the snippet.In most text editors, you hit the tab to advance to the next tab stop.JupyterLab does not yet support tab stops.(If you want to use tab stops in a text editor, visit thepymolsnips project).Use thepymol+ library when you need guidance in editing a snippet.The content of the active part of the snippet is the same in both libraries.The commented code in thepymol+ snip library may annoy experienced users who do not need help with editing.

Alternatively, you can download the repository as a zip file by clicking on the greencode button above.However,git eases the updating of the libraries are a later time.You would navigate to themultimenus_snippets/pymol folder and then entergit pull to update the library.This is far less painful than down downloading the library as a zip file.Repeat forpymol+ if needed.Navigate back to your home directory before runningJupyterLab (e.g.,cd orcd ~/).

Now, fire upJupyterLab.

jupyter lab

Return to Table of Contents

The snippet library is independent of PyMOL.No modification of PyMOL is required.

Return to Table of Contents

The animation at the top of the page conveys the essential knowledge for usage.

Return to Table of Contents

Try theao.py snippet. You should get a result similar to the one should in the animation above.

Return to Table of Contents

Please use theIssues tab above to request support for additional snippets or to ask questions.Alternatively, you can sende-mail to me.

Questions about PyMOL should be directed to thePyMOL Mailing List.

Return to Table of Contents

Snippets of new code are most welcome. Send toe-mail.

• Submit the Python code in a plain text file.
• Write the filenames and function names in camelCase.
• Provide a description of what the code does in one to several sentences, an examples of usage, and any citations or links to further information.

Return to Table of Contents

Use theIssues tab above to report bugs or sende-mail to me.

Return to Table of Contents

I plan to expand the library to cover with examples the 500 commands and 600 settings in PyMOL.

Return to Table of Contents

We use the permissive MIT license.The license information for this project is found in theLicense.txt file above.

Return to Table of Contents

I can be reached via the Issue tab above or via e-mail:blaine-mooers at ouhsc.edu.

Return to Table of Contents

If you use this library to make figures for publication, please see theCitation.md file above.

A paper describing this library was published in April 2021.

@Article{Mooers2021APyMOLSnippetLibraryForJupyterToBoostResearcherProductivity,author    ={Mooers, Blaine HM},journal   ={Computing in Science \& Engineering},title     ={A PyMOL snippet library for Jupyter to boost researcher productivity},year      ={2021},pages     ={47-53},volume    ={23},publisher ={IEEE},doi       ={10.1109/MCSE.2021.3059536},}

Return to Table of Contents

• easypymol

• pymolshortcuts

• pymolsnips

• orgpymolpysnips

• rstudiopymolpysnips

• taggedpymolpysnips

• colabOpenSourcePyMOLpySnips

• colabPyMOLpySnips

• PyMOLwallhangings

• jupyterlabpymolpysnips PyMOL Python snippets for use in JupyterLab with the jupyterlab-snippets extension.

• jupyternbclassicpymolpysnipsplus

• taggedpymolpysnips

• taggedpymolpysnipspymolpysnipsplus

• jupyter-vsc-pymolpysnips

• jupyter-st3-pymolpysnips

• jupyter-emacs-pymolpysnips

• jupyter-ultisnips-pymolpysnips

• jupyter-snipmate-pymolpysnips

• jupyter-neosnippets-pymolpysnips

• jupyter-atom-pymolpysnips

• NIH: R01 CA242845, R01 AI088011
• NIH: P30 CA225520 (PI: R. Mannel); P20GM103640 and P30GM145423 (PI: A. West)