There are many ways to get PyMOL running in JupyterLab. For details on installing both, go to the GitHub Page associated with this project. Go to this project's GitHub 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 the ao.py snippet in JupyterLab 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 in PyMOL 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 into PyMOL.
You can store the images generated by PyMOL in one Jupyter 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 in JupyterLab 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.
-
There is nothing stopping you from running the PyMOL GUI next to your JupyterLab session. You can adjust the molecule's orientation manually, run the get_view command, copy the output in the command history window from PyMOL, and paste it into a cell in the Jupyter Notebook. The one line of settings returned by the rv shortcut is much easier to use. The rv shortcut is in the pymolshortcuts.py script.
-
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.
If you are not ready to write PyMOL scripts, please consider using PyMOL shortcuts to enhance your productivity in PyMOL interactive sessions.
For example, the above ambient occlusion effect can be invoked at any time by entering AO at the PyMOL prompt if the pymolshortcuts.py file has been loaded.
These shortcuts can also be invoked in a Jupyter Notebook by submitting them as arguments to the cmd.do() method, (e.g., cmd.do("AO") to generate the ambient occlusion effect.)
The jupyterlabpymolpysnips library contains 260 code fragments (i.e., templates or snippets) written in Python to run PyMOL in JupyterLab via PyMOL's Python API. This API is only available for recent versions of PyMOL that depend on Python3. This API is available for both the incentive and open-source versions of PyMOL.
| Technology | Version | Description |
|---|---|---|
| PyMOL | 2.4.0 | Molecular graphics program |
| Python | 3.7-3.8 | Programming language |
| JupyterLab | >=2.0 | A IDE for editing Jupyter Notebooks. |
| jupyterlab-snippets | 0.4.0 or 0.4.1 | Required extension |
| Node.js | >=10.0.0 | Required by Jupyter and many extensions. |
| git | 2.25.1 | Eases the downloading and updating of the libraries. |
You may have to create a new conda env to install the older version of JupyterLab.
| Technology | Version | Description |
|---|---|---|
| PyMOL | >2.4.0 | Molecular graphics program |
| Python | 3.7-3.8 | Programming language |
| JupyterLab | >2.2.0 | A IDE for editing Jupyter Notebooks. Version 3.0 does not work with jupyterlab-snippets-multimenus |
| jupyterlab-snippets-multimenus | 0.4.0 | Required extension |
| Node.js | >=10.0.0 | Required by Jupyter and many extensions. |
| git | 2.25.1 | Eases the downloading and updating of the libraries. |
Some of the snippets are limited to Python3 code. Suppose you use an outdated version of PyMOL that relies on Python2. In that case, you can buy a license to the current version of PyMOL; install a free, open-source version of PyMOL that depends on Python3 (See the PyMOL 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 program 2to3 automates this process. Note that multiple versions of PyMOL can operate side-by-side on a computer, so you do not have to delete that old version of PyMOL.
JupyterLab can use the jupyterlab-snippets extension to make the snippets available via the snippets pull-down menu. Conda, pip, or the extension manager in Jupyter Lab can install the extension.
Assuming that JupyterLab, jupyterlab-snippets, and PyMOL are already installed, run the following commands one line at a time,
jupyter --path
cd ~/.local/share/jupyter # change as per output from prior line. Use cd ~/Library/Jupyter on the Mac.
mkdir snippets
cd snippets
git clone https://github.com/MooersLab/jupyterlabpymolpysnips.git pymol
git clone https://github.com/MooersLab/jupyterlabpymolpysnipsplus.git pymol+When you open JupyterLab, you will find a snippet pull-down menu on the JupyterLab menu bar. There will be a pymol sub-menu and a pymol+ sub-menu under this pull-down.
JupyterLab needs to be version >=2.2.0 for jupyterlab-snippets to run. The current version of JupyterLab is 3.3.4.
You can install Node.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.
Alternatively, you can use the jupyterlab-snippets-multimenus package. The package will appear on the menu bar as separate pull-down menus: pymol and pymol+. 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 that JupyterLab, jupyterlab-snippets-multimenus, and PyMOL are already installed, run the following commands one line at a time:
jupyter --path
cd ~/.local/share/jupyter # change as per output from prior line. Use cd ~/Library/Jupyter on the Mac.
mkdir multimenus_snippets
cd multimenus_snippets
git clone https://github.com/MooersLab/jupyterlabpymolpysnips.git pymol
git clone https://github.com/MooersLab/jupyterlabpymolpysnipsplus.git pymol+The snippets in the pymolpysnips+ 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 the pymolsnips project).
Use the pymol+ 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 the pymol+ 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 green code button above.
However, git eases the updating of the libraries are a later time.
You would navigate to the multimenus_snippets/pymol folder and then enter git pull to update the library.
This is far less painful than down downloading the library as a zip file.
Repeat for pymol+ if needed.
Navigate back to your home directory before running JupyterLab (e.g., cd or cd ~/).
Now, fire up JupyterLab.
jupyter labThe snippet library is independent of PyMOL. No modification of PyMOL is required.
The animation at the top of the page conveys the essential knowledge for usage.
Try the ao.py snippet. You should get a result similar to the one should in the animation above.
Please use the Issues tab above to request support for additional snippets or to ask questions. Alternatively, you can send e-mail to me.
Questions about PyMOL should be directed to the PyMOL Mailing List.
Snippets of new code are most welcome. Send to e-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.
Use the Issues tab above to report bugs or send e-mail to me.
I plan to expand the library to cover with examples the 500 commands and 600 settings in PyMOL.
We use the permissive MIT license. The license information for this project is found in the License.txt file above.
I can be reached via the Issue tab above or via e-mail: blaine-mooers at ouhsc.edu.
If you use this library to make figures for publication, please see the Citation.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},
}-
jupyterlabpymolpysnips PyMOL Python snippets for use in JupyterLab with the jupyterlab-snippets extension.
| Version | Changes | Date |
|---|---|---|
| Version 0.3 | Added funding and update table. Corrected typos in README.md file | 2024 May 9 |
- NIH: R01 CA242845, R01 AI088011
- NIH: P30 CA225520 (PI: R. Mannel); P20GM103640 and P30GM145423 (PI: A. West)