pymolshortcuts

This repository for pymolschortucts.py that contains 215 functions in 25 categories mapped to short-names that work like aliases (the table below is incomplete). These shortcuts include many convenience functions that make working in PyMOL more productive and fun! Some shortcuts save the many hours of work required to assemble a new script file while other shortcuts save only a few minutes but lower motivational barriers. You do not need to understand Python to be able run the script.

A paper about this project was publisehd in January 2020 in Protien Science. Access to the PDF is open; you do not need a subscription to Protein Science to download it.

To cite the software, use the following citation if you use bibtex.

@article{mooers2020shortcuts,
  title={Shortcuts for faster image creation in PyMOL},
  author={Mooers, Blaine HM},
  journal={Protein Science},
  volume={29},
  number={1},
  pages={268--276},
  year={2020},
  publisher={Wiley Online Library}
}

The Google Scholar genearted ENDNOTE file (scholar.enw) is above with the other files.

Quick overview

To get a quick overview of this project, scroll down through this README.md file and watch the animations. To learn more, see the pdfs of in the slideshow folder:

• mooers23jul2019ACAPyMOLshortcuts.pdf (20 minute talk at the American Crystallographic Association annual meeting in Covington, KY)
• mooers18oct2019RNAcornbeltPyMOLShortcuts4RNA.pdf (9 minute talk at the Cornbelt RNA meeting at the U of Missouri in Columbia, Missouri)
• mooers26Oct2019SWTCCPyMOLshortcuts.pdf (20 minute talk, Southwest Theoretical and Computational Chemistry (SWTCC) annual meeting at the U of Oklahoma in Norman, OK)

The animation below demonstrates the photorealistic effect from the ambient occlusion shortcut applied to a protein by entering two letters, AO. This shortcut executes 16 lines of code with the entry of two letters!

The animation below demonstrates the submission of two shortcuts, sc311 and sc113, separated by a semicolon on the command line. They generate symmetry mates that fill five unit cells. The unit cells form a L shape. Each symmetry mate appears as a separate object in the menu in the panel to the right of the vv. These can be removed by entering the shortcut rmsc.

The variant file pymolschortuctsNobs4.py lacks a few functions that depend on the Python module beautifulsoup4 that is not shipped with PyMOL. Choose this variant file if you do not know how to add beautifulsoup4 to your version of PyMOL.

Selecting the right pymolshortcuts.py script

Have Open Source PyMOL or incentive version => 2.0.

If you want to use the shortcuts with a version of PyMOL that has a Python interpreter to which you can add an external module (generally any Open source PyMOL or the incentive version equal to or greater than 2.0), download the pymolshortcuts.py script.

Have incentive version < 2.0 or do not want to mess with installing an external module

If you have an incentive version less than 2.0 or you do not want to bother with installation of the datetime module, download the pymolshortcutsNoDateTime.py. This version of the script lacks the functions that depend on the datetime module. By using this version You will not get error messages about this module not being found.

How to install the date time module

These instructions are only for the users of pymolshortcuts.py

The Python program pip is available for all installing external modules. The recommended way of using pip when more than one Python interpreter is on our computer is to import it as a module on the command line with the path of the python interpreter for which you are making the install. For example, to install the datetime module in the macports Python3.7, use sudo -H /opt/local/bin/python3.7 -m pip install --upgrade datetime. The minus m flag means import the following module. Depending on your configuration of macports, you may not need to use sudo -H.

Download the script file

Before you download the script file, be sure that you have set your system to show file extensions. Both Mac and Windows operating system hide the file extension by default.

On the Mac, do the following

• Open a new Finder window.
• In the menu bar, select Finder > Preferences.
• Check the box Show all filename extnesion

On Windows, do the following:

• Search for File Explorer Options in Start search box and open the Folder Options box.
• Uncheck the box next to Hide extensions for known file types".

To download all of the files, git clone the repository. Otherwise, left-click on one of the files above and left-click "Raw". The raw file will be displayed in your browser. Select save under the file pull-down of your browser. Your browser may add .txt after .py. Delete .txt by backspacing over it. Then save the file to your home directory. Your browser may try to append the .py with .txt again via a popup gui but do not select this option.

Installation

To have the shortcuts always available in PyMOL, add the command 'run ~/pymolshortcutsNobs4.py' (recommended for most users) or 'run ~/pymolshortcutsbs4.py' (for advanced users) to the .pymolrc, pymolrc or pymolrc.pml file in your home directory. This command will to load the functions in the script on every startup of PyMOL so you do not have to think about doing so again.

The pymolrc file is an optional file. You may have to create it with a text editor if you have not done so already. If you do not have text editor, you can use PyMOL's built-in text editor. Go to File --> Edit pymolrc. The functions will be loaded into memory but will not be executed despite the use of the command run. You may want to store the script pymolshortcuts.py in a safer place than your home directory. I store mine in /Users/blaine/Scripts/PyMOLScripts/.

Configure the script for access to all shortcuts

Configuraton: application start commands

A number of shortcuts open external programs. The commands that work on the Mac OS are active by default. These are not path dependent. They should work irregardless of the nonconventional location of your applications, as long as they are in your PATH. They are found around line 500 in the pymolshortcuts.py script file.

The commands for Mac OS need to be commented out and the commands for Linux or Windows need to be uncommented. Do not use a word processor to edit this file. Visual Studio Code is an excellent, free, and intuitive text editor that is platform independent. Install one of the Python in-plugins via the marketplace to get syntax highlighting of the pymolshortcuts.py script file

Configuraton: paths to local directories and urls of some webpages

Around line 500, there are also paths to local directories of pdb files and webmail sites that need to be customized.

Do not have PyMOL or do not want to mess with your existing PyMOL?

Note that is possible to have multiple versions of PyMOL on one computer. On the Mac, you can give the package in Applications a different name. I append the version number to the stem of the file name: e.g., PyMOL233.app for version 2.3.3. Avoid trouble down the road by NOT introducing whitespaces into the file name.

Download incentive version of the current PyMOL

The incentive version of PyMOL is easiest to install due to the availability of installers. You can use the incentive version for 30 days for free without buying an annual license.

Open source alternatives

Mac

See the instructions on the PyMOL Wiki page for installing on the Mac.

There are many ways of installing PyMOL on the Mac. I suggest using the install command below instead for installing pymol on the Mac with macports. I have used fink, anaconda, homebrew, and macports. I have the fewest problems with macports, followed by fink. The main barrier to using macports is the need to install the Xcode related command-line tools. The protocol for doing so varying with the version of the Mac operating system and the version of Xcode installed on your computer. Expect to spend at least an hour installing the command line tools and then macports. If this sounds like too much trouble, download the 30-day trials of the incentive version.

Open source version of pymol via macports works fine. It is missing a few minor thrills found in the incentive version like the ability to import background images into the viewport. You can have your favorite protein rocking over a scene from your last vacation. This is cool but not essential for serious work. Note that the install of pymol via macports on the Mac (sudo port install pymol +python37) allows specification of the version of the Python interpreter. PyMOL can be installed with versions 2.7, 3.5, 3.6, and 3.7 of Python. This is handy if you have a module written for only Python3.5 that you want to import into PyMOL to do something unique and creative without writing a new plugin for PyMOL. However, only one version of macports PyMOL can be active at a time. You could just run sudo port install pymol +pythonXX whenever you want to switch versions of pymol because the install goes very quickly. The proper way to switch ports is to enter sudo activate . Of course, you have to have the corresponding macports Python interpreter installed prior to installing pymol. Open source version of pymol via macports works fine in my hands. It has only a few minor frills missing that the incentive has.

Linux

See the PyMOL Wiki page for Linux Installs. The install protocol varies with the flavor of Linux. Install protocols for seven flavors of Linux are listed on the PyMOL Wiki. I have had success with installing recent versions of PyMOL on Ubuntu and Centos 7. The webpage also describes installing PyMOL from source. From my past experience, this is more successful on Linux than on MacOS.

Windows

See the PyMOL Wiki page for installing PyMOL on Windows. The protocol varies with the flavor of Linux. I have had success with installing recent versions of PyMOL on Ubuntu and Centos 7.

If all of the above is overwhelmning, you do have a 30-day free-trial period with which you can use the incentive version of PyMOL.

Listing the shortcuts in PyMOL's command history window

Enter SC at the upper PyMOL> prompt the to get a list of shortcuts printed to the command history window. Use the help function to see the documentation for each shortcut. For examples, enter help PW to print the documentation for the shortcut PW to the command history window. The documentation has four sections: a description of what the shortcut does, an example of running the shortcut, the corresponding pml code with one command per line for easy reuse in a script file, and all of the commands on a single line for re-use on the command line as horizontal script.

The shortcut PW takes one or more search terms and the sends them to the PyMOL Wiki. A browser tab opens for each search term, so multiple searches are run in parallel while you continue your work in PyMOL. You can inspect the results of the searches when there is a natural break in your work in PyMOL. Other search functions can submit parallel searches of PubMed, Google, bioRxiv, Research Gate, GitHub, and more. See the tables below.

Another class of shortcuts launch your favorite full-featured text editor from within PyMOL. You have to install the text editor and edit the file path to the executable.

Another class of shortcuts opens the manuscript or grant application that you are working on in Overleaf. You have to edit the script by pasting in the appropriate link to the specific document.

Another class of shortcuts saves files with timestamps embedded in the filename to avoid overwriting png, pdb, pse, and other types of files written out from PyMOL. These save function names begin with s, (e.g., spse filename saves the current session with date and time to nearest second embedded in the file name). You can delete the unwanted version(s) at a latter time. These functions are useful if you do not have these files under version control.

Count files.

Data analysis program, open from withn PyMOL.

H-bonds

Image editing program, open from within PyMOL.

Many models (NMR and crystal packing).

Molecular graphics program, open from within PyMOL.

Molecular representation, additional styles.

Molecular surfaces, color by biophysical properties.

Molecular symmetry generation.

Object selection.

Orient molecule with viewport axes.

Pairwise distances.

Save files with date and time in stem of filename.

Script writing aids.

Send search term to searchable website.

Static images of various molecular scenes. Can serve as templates.

Static images of various molecular scenes. Require coordinates on local computer.

Structure validation.

Terminal, open from within PyMOL.

Text editor, launch from with PyMOL.

Webapp,open from within PyMOL.

Website, static, open from within PyMOL.

Word processor, open from within PyMOL.