README.md

Rapid generation of high-quality structure figures for publication with PyMOL-PUB

With the rapid progress of fields like protein structure prediction, an increasing number of researchers from different backgrounds require the use of PyMOL for molecular visualization. To be used in publications, the default visualization output of PyMOL typically requires the spatial adjustments, such as rotating and/or zooming the structures, and purposeful emphasis including highlighting important parts and hiding the unimportant parts. Meanwhile, the need for batch visualization has been demonstrated by recent publications in high-impact journals. However, these adjustments and batch protocols require the involvement of many skilled personnel, are expensive, and operate at human speeds, all of which make them worthy of automation. Based on the original design of PyMOL and as an important supplement, we develop a high-level interface in order to generate figures capable of reaching the publication standard. By using our tool, the manual operations can be greatly reduced, and the desired image output can be obtained with a few lines of code or by operations through GUI.

Citation

If you think this repo helps or being used in your research, please consider refer this paper:

@article{chen2024rapid,
    author = {Chen, Yuting and Zhang, Haoling and Wang, Wen and Shen, Yue and Ping, Zhi},
    title = {Rapid generation of high-quality structure figures for publication with PyMOL-PUB},
    journal = {Bioinformatics},
    volume = {40},
    number = {3},
    pages = {btae139},
    year = {2024},
    month = {03},
    issn = {1367-4811},
    doi = {10.1093/bioinformatics/btae139},
    url = {https://doi.org/10.1093/bioinformatics/btae139},
}

Case presentation

Based on three structures with default visualization output

1AY7	1F34	1YCR

an ideal publication-standard figure

can be created using 55 lines of code, which is similar to Figure 1 of Carles Corbi-Verge et al. work.

Furthermore, we provide some high-level visualization usage for displaying physicochemical properties and alignment comparison results (e.g. RMSD) of target structure(s). For example, the following left panel describes the difference between the expected structure and the predicted structure, reported in Figure 1 of Zeming Lin et al. work. Here, to avoid a cluttered information in the structure overlapping parts, we depict solely the predicted structure (center panel), and illustrate the difference between the predicted and anticipated structures by varying the thickness and gradient color of the cartoon representation (see the following right panel).

expected	designed (equal)	designed (improve)

Installation

You can install it using pip:

pip install PyMOL-PUB

Or you can install it from source after installing git:

git clone https://github.com/BGI-SynBio/PyMOL-PUB.git
cd PyMOL-PUB
pip install -r requirements.txt
python setup.py install develop --user

The tool requires Python >= 3.7.3. As the foundation of this tool, we require a PyMOL version equal to 2.5.0. Please refer to the official website for installation protocol details.

Additionally, some well-established libraries are required: biopython >= 1.78, matplotlib >= 3.2.0, numpy >= 1.21.2, pillow >= 8.2.0, scipy >= 1.4.1, sphinx-rtd-theme >= 0.4.3 and PyQt5 >= 5.15.9 (a special dependency required by the GUI).

Note on your PyMOL version

The PyMOL software includes a Linux-distribution version and an open-source version. The two different versions have different installation dependencies. You need to carefully read the respective installation instructions and choose the required version according to your own need. For example, PyMOL distribution versions bundle specific Python environment versions to achieve richer functionality (like PyMOL 2.5.7 with Python 3.9). Here we recommend you to choose the open-source version of PyMOL to directly experience the drawing functionality of PyMOL-PUB.

Customizations and protocols

Publication-standard figure creation

At the figure level, we can customize the target publication format during the initialization of the figure. The supporting figure formats of journal, conference or publisher are:

target	font	math font	dots per inch (dpi)	max columns	width under column occupy (inches)
					1	2	3
Nature	Arial	Linux Libertine & Lucida Calligraphy	300	2	3.54	7.08	-
Science	Helvetica		300	3	2.24	4.76	7.24
Cell	Arial		300	2	3.35	6.85	-
				3	2.17	4.49	6.85
PNAS	Helvetica		600	2	3.42	7.00	-
ACS	Arial		600	2	3.25	7.00	-
Oxford	Arial		350	2	3.39	7.00	-
PLOS	Arial		300	1	5.20	-	-
IEEE	Times New Roman		300	2	3.50	7.25	-

The collected font format are: "Time New Roman", "Helvetica", "Arial", "Linux Libertine" and "Lucida Calligraphy". The TTF files are located in the 'fonts' folder. These font formats will automatically connect to matplotlib when PyMOL-PUB initializes.

The target figure can be set to the Science format and full width by constructing the subsequent object.

from molpub.layouts import Figure
figure = Figure(manuscript_format="Science", occupied_columns=3)

Once the figure has been created, it is possible to insert the generated structure image(s) into it by utilizing the "set_image" function or paint various outcomes, like line chart, bar chart, violin chart, and so on, through the "set_panel" function. The Figure class also provides a grid selection function since publications usually have varying information to display in one figure.

Structure image creation

For the structure image, two types of rendering objectives have been offered: the first aims to accentuate specific region(s), and the second intends to showcase element (deoxyribonucleic acid, ribonucleic acid and amino acid) property information in the structure. The HighlightStructureImage class can offer adequate services for the former, whereas the PropertyStructureImage class is developed for the latter.

Irrespective of the structure visualisation method, as applicable in all cases, the recommended function calling order (not mandatory) is to (1) omit unnecessary parts by "set_cache" function, (2) adjust the structure's spatial orientation by "set_state" function, (3) modify the structure or its parts representation by "set_shape" function, (4) complete coloring of the structure or its parts by highlight coloring or property driven coloring, both called "set_color" function in the corresponding class, and (5) save the image by "save" function.

A highlight structure image example can be:

from molpub.layouts import HighlightStructureImage

# create a structure image based on a structure file "structure.pdb".
image = HighlightStructureImage(structure_paths=["structure.pdb"])
# hide all water molecules.
image.set_cache(cache_contents=["residue:HOH"])
# set A-chain to surface representation and B-chain to cartoon representation.
image.set_shape(representation_plan=[("chain:A", "surface"), ("chain:B", "cartoon")])
# rotate the structure according to the x-axis 240 degrees, y-axis 340 degrees, and z-axis 90 degrees.
image.set_state(rotate=[240, 340, 90])
# set A-chain to "0xF2F2F2" color and B-chain to "0x2D2F82" color.
image.set_color(coloring_plan=[("chain:A", "0xF2F2F2"), ("chain:B", "0x2D2F82")])
# save the structure with the width 1280 and the height 1280 * 0.8 = 1024.
image.save(save_path="structure.png", width=1280, ratio=0.8)

Besides, a property driven structure image example can be:

from molpub.layouts import PropertyStructureImage

# create a structure image based on two structure files "expected.pdb" and "predicted.pdb".
image = PropertyStructureImage(structure_paths=["expected.pdb", "predicted.pdb"])
# set two structures to cartoon representation.
image.set_shape(representation_plan=[("model:predicted", "cartoon"), ("model:expected", "cartoon")])
# rotate the structure according to the x-axis 0 degrees, y-axis 60 degrees, and z-axis 255 degrees.
# and align two structures based on the PyMOL built-in method using the expected structure as a template.
image.set_state(rotate=[0, 60, 255], inner_align=True, target="expected")
# set the color of predicted structure is the rainbow spectrum, starting in red and ending in purple.
image.set_color(target="model:predicted", color_map="rainbow", edge_color="0x000000", gauge_strengthen=True)
# save the structure with the width 1800 and the height 1800 * 0.5 = 900.
image.save(save_path="aligned_structure.png", width=1800, ratio=0.5)

More comparable cases are attached in the cases folder.

Scalable string expression for part selection

We present a string expression to describe two types of selection scheme, one is "all" and another is "type:target,target,...,target", which avoids users from needing to input extensive selection information based on the original PyMOL design.

Here, "type" is selection class, including (1) "position", (2) "range", (3) "residue", (4) "segment", (5) "chain" and (6) "model". "target" represents the selection range under the corresponding "type".

Some examples are shown below:

# select the model called "predicted".
a = "model:predicted"
# select A-chain.
b = "chain:A"
# select segment "NPGP" in all chains.
c = "segment:NPGP"
# select residue "HOH" in all chains.
d = "residue:HOH"
# select range from 10 to 20 and from 50 to 60 in all chains.
e = "range:10-20,50-60"
# select 10-th position in all chains.
f = "position:10"

For types below the chain scale, i.e. type (1) - (4), we provide a built-in chain description mechanism for more accurate selection. For example:

# select range from 10 to 20 in all chains.
a = "range:10-20"
# select range from 10 to 20 in A-chain.
b = "range:A+10-200"

Rotation widget icons

Rotation widget icons describe the rotation of molecular structure, determined by the azimuth angle (for x+y plane) and the elevation angle (for z plane).

There are two styles. In style 1, the widget is defined by direction and the azimuth angle.

direction	azimuth angle
	30	60	90	120	180
+
-

To generate such icon, you can use:

from molpub.layouts import obtain_widget_icon

# rotate turn "right" and degree 30. 
obtain_widget_icon(save_path="temp path", widget_type="rotation", params={"turn": "right", "degree": 30}, dpi=1200)

and you can obtain

Here, the scope of "turn" is {"+", "-"} and that of "degree" is (0, 180].

Sometimes, we need to operate the elevation angle concurrently. A more complex widget attribute setup is (elevation angle, azimuth angle).

elevation angle	azimuth angle
	-180	-120	-90	-60	-30	0	+30	+60	+90	+120	+180
-180
-120
-90
-60
-30
0						N/A
+30
+60
+90
+120
+180

The interface is shown in obtain_widget_icon.

To generate such icon, you can use:

from molpub.layouts import obtain_widget_icon

# rotate elevation 30 and azimuth 30. 
obtain_widget_icon(save_path="temp path", widget_type="rotation", params={"elevation": 30, "azimuth": 30}, dpi=1200)

and you can obtain

Here, the scope of "elevation" and "azimuth" and [-180, 180].

Usage of PyMOL-PUB surface (GUI)

Based on PyQt5, PyMOL-PUB offers a process-based plotting GUI to replace the cost of programming Python scripts. It enables a broader spectrum of users, notably those without Python programming experience. By running the windows.py, you can start your drawing jobs using the PyMOL-PUB's GUI. We provide a demo video that shows how to use the GUI to create the target figure, which can be found on YouTube. You can follow along with the video to learn the operation of the GUI, or refer to the text instructions provided in the PyMOL-PUB technical manual.

Sometimes, you might encounter an issue where GUI fails to launch. It typically arises if the 'molpub' directory, which contains 'windows.py', is not included in the working directory. There are two simple solutions to resolve this issue:

• Find the windows.py file in your system, copy it to another folder, and run the copied script through a command prompt.
• Load the whole project into Python IDE like PyCharm, and execute the windows.py file by pressing the run button in the IDE.

Funding

This work was supported by the National Key Research and Development Program of China (no. 2021YFF1200100), National Natural Science Foundation of China (no. 32101182 and 32201175), and Shenzhen Science, Technology and Innovation Commission under grant no. SGDX20220530110802015. This work was also supported by China National GeneBank.

Yuting Chen and Haoling Zhang were also funded by the Warren L. DeLano Memorial PyMOL Open-Source Fellowship. Their quarterly reports have been made public and can be found here.

Acknowledgements

We thank Dr. Jarrett Johnson from Schrödinger, Inc. for constructive discussions on functional design and implementation mode. We also thank Prof. Yang Zhang from University of Michigan and Dr. Chengxin Zhang from Yale University on the application scope of structure alignment methods.