Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mooerslab/jupyterlabpymolpysnips
Python snippets for PyMOL to be run in Jupyterlab via the jupyterlab-snippets-multimenus extension.
https://github.com/mooerslab/jupyterlabpymolpysnips
biomolecular dna-structure grayscale jupyter jupyter-notebook jupyterlab ligand literate-programming mmcif moleclar-graphics molecular molecular-representation notebook pdb protein-structure python ribbon-diagram rna-structure snippets
Last synced: about 1 month ago
JSON representation
Python snippets for PyMOL to be run in Jupyterlab via the jupyterlab-snippets-multimenus extension.
- Host: GitHub
- URL: https://github.com/mooerslab/jupyterlabpymolpysnips
- Owner: MooersLab
- License: mit
- Created: 2020-11-15T17:18:53.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-05-09T11:39:27.000Z (9 months ago)
- Last Synced: 2024-05-09T12:44:10.929Z (9 months ago)
- Topics: biomolecular, dna-structure, grayscale, jupyter, jupyter-notebook, jupyterlab, ligand, literate-programming, mmcif, moleclar-graphics, molecular, molecular-representation, notebook, pdb, protein-structure, python, ribbon-diagram, rna-structure, snippets
- Language: HTML
- Homepage:
- Size: 8.76 MB
- Stars: 19
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeOrientation/rotate.py
- License: LICENSE
- Citation: Citation.md
Awesome Lists containing this project
README
# jupyterlabpymolpysnips: Templates for writing and running PyMOL in Jupyter Notebooks.
[](https://opensource.org/licenses/MIT)
[](https://doi.org/10.5281/zenodo.4429717)
There are many ways to get PyMOL running in JupyterLab. For details on installing both, go to the [GitHub Page](https://mooerslab.github.io/jupyterlabpymolpysnips/) associated with this project.
Go to this project's [GitHub Page](https://mooerslab.github.io/jupyterlabpymolpysnips/) for a list of the snippets and their descriptions.
* [Motivation](#motivation)
* [New to scripting in PyMOL](#new)
* [Tech Stack](#technology-stack)
* [Installation](#installation)
* [Configuration Setup](#configuration-setup)
* [Usage](#usage)
* [Testing](#testing)
* [Requests for new snippets and text editors](#requests)
* [Bug reports](#bugreports)
* [Roadmaps](#roadmap)
* [License](#license)
* [Contact Information](#contact-information)
* [How to cite](#citation)
### Use jupyterlabpymolpysnips to be more productive while running PyMOL in Jupyter
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**.
[Return to Table of Contents](#table-of-contents)
### Why run PyMOL in a Jupyter Notebook?
#### Streamlines the management of images for a project
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.
#### Ease the sharing of images with collaborators
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.
#### Facilitates combining PyMOL with other software in molecular structure analysis
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.
[Return to Table of Contents](#table-of-contents)
### But I will miss the interactive viewport in PyMOL!
1. 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](https://github.com/MooersLab/pymolshortcuts) 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](#table-of-contents)
If you are not ready to write PyMOL scripts, please consider using [PyMOL shortcuts](https://github.com/MooersLab/pymolshortcuts) 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.)
## Application Description
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**.
[Return to Table of Contents](#table-of-contents)
| Technology | Version | Description |
|--------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------|
| [PyMOL](https://pymol.org/2/) | 2.4.0 | Molecular graphics program |
| Python | 3.7-3.8 | Programming language |
| [JupyterLab](https://pypi.org/project/jupyterlab/) | >=2.0 | A IDE for editing Jupyter Notebooks. |
| [jupyterlab-snippets](https://github.com/QuantStack/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. |
## or use this alternate set of programs
You may have to create a new conda env to install the older version of JupyterLab.
| Technology | Version | Description |
|--------------------------------------------------------------------------------------------|----------|----------------------------------------------------------------------------------------------------|
| [PyMOL](https://pymol.org/2/) | >2.4.0 | Molecular graphics program |
| Python | 3.7-3.8 | Programming language
| [JupyterLab](https://pypi.org/project/jupyterlab/) | >2.2.0 | A IDE for editing Jupyter Notebooks. Version 3.0 does not work with jupyterlab-snippets-multimenus |
| [jupyterlab-snippets-multimenus](https://github.com/QuantStack/jupyterlab-snippets ) | 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](https://pymolwiki.org/index.php/Main_Page)); 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,
```bash
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.
[Return to Table of Contents](#table-of-contents)
Installation of the snippet library
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:
```bash
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](https://github.com/MooersLab/pymolsnips)).
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**.
```bash
jupyter lab
```
[Return to Table of Contents](#table-of-contents)
The snippet library is independent of PyMOL.
No modification of PyMOL is required.
[Return to Table of Contents](#table-of-contents)
The animation at the top of the page conveys the essential knowledge for usage.
[Return to Table of Contents](#table-of-contents)
Try the **ao.py** snippet. You should get a result similar to the one should in the animation above.
[Return to Table of Contents](#table-of-contents)
Please use the **Issues tab** above to request support for additional snippets or to ask questions.
Alternatively, you can send [e-mail](#contact-information) to me.
Questions about PyMOL should be directed to the [PyMOL Mailing List](https://pymolwiki.org/index.php/PyMOL_mailing_list).
[Return to Table of Contents](#table-of-contents)
Snippets of new code are most welcome. Send to [e-mail](#contact-information).
- 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](#table-of-contents)
Use the **Issues tab** above to report bugs or send [e-mail](#contact-information) to me.
[Return to Table of Contents](#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](#table-of-contents)
We use the permissive MIT license.
The license information for this project is found in the *License.txt* file above.
[Return to Table of Contents](#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](#table-of-contents)
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.
```bibtex
@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](#table-of-contents)
## Related Repos
- [easypymol](https://github.com/MooersLab/EasyPyMOL/edit/master/README.md)
- [pymolshortcuts](https://github.com/MooersLab/pymolshortcuts)
- [pymolsnips](https://github.com/MooersLab/pymolsnips)
- [orgpymolpysnips](https://github.com/MooersLab/orgpymolpysnips)
- [rstudiopymolpysnips](https://github.com/MooersLab/rstudiopymolpysnips)
- [taggedpymolpysnips](https://github.com/MooersLab/taggedpymolpysnips)
- [colabOpenSourcePyMOLpySnips](https://github.com/MooersLab/colabOpenSourcePyMOLpySnips)
- [colabPyMOLpySnips](https://github.com/MooersLab/colabPyMOLpySnips)
- [PyMOLwallhangings](https://github.com/MooersLab/PyMOLwallhangings)
- [jupyterlabpymolpysnips](https://github.com/MooersLab/jupyterlabpymolpysnips) PyMOL Python snippets for use in JupyterLab with the jupyterlab-snippets extension.
- [jupyternbclassicpymolpysnipsplus](https://github.com/MooersLab/jupyternbclassicpymolpysnipsplus)
- [taggedpymolpysnips](https://github.com/MooersLab/taggedpymolpysnips)
- [taggedpymolpysnipspymolpysnipsplus](https://github.com/MooersLab/taggedpymolpysnipspymolpysnipsplus)
- [jupyter-vsc-pymolpysnips](https://github.com/MooersLab/jupyter-vsc-pymolpysnips)
- [jupyter-st3-pymolpysnips](https://github.com/MooersLab/jupyter-st3-pymolpysnips)
- [jupyter-emacs-pymolpysnips](https://github.com/MooersLab/jupyter-emacs-pymolpysnips)
- [jupyter-ultisnips-pymolpysnips](https://github.com/MooersLab/jupyter-ultisnips-pymolpysnips)
- [jupyter-snipmate-pymolpysnips](https://github.com/MooersLab/jupyter-snipmate-pymolpysnips)
- [jupyter-neosnippets-pymolpysnips](https://github.com/MooersLab/jupyter-neosnippets-pymolpysnips)
- [jupyter-atom-pymolpysnips](https://github.com/MooersLab/jupyter-atom-pymolpysnips)
## Update history
|Version | Changes | Date |
|:-----------:|:------------------------------------------------------------------------------------------------------------------------------------------:|:--------------------:|
| Version 0.3 | Added funding and update table. Corrected typos in README.md file | 2024 May 9 |
## Funding
- NIH: R01 CA242845, R01 AI088011
- NIH: P30 CA225520 (PI: R. Mannel); P20GM103640 and P30GM145423 (PI: A. West)