A python library and command line program for plotting simulated 2D and 3D NMR spectra from assigned chemical shifts from the BMRB

Peak assignments are pulled using the BMRB API (https://github.com/uwbmrb/BMRB-API) and plotted with matplotlib. Spectra produced by this script do not always reflect reality, as many entries do not have 100% assignments. Be sure to know what assignments are contained in the entry beforehand.

If you find this code useful please cite our paper:

Fucci, I. J. and Byrd, R. A. nightshift: A Python program for plotting simulated NMR spectra from assigned chemical shifts from the Biological Magnetic Resonance Data Bank. Protein Sci. 2022, 31 (1), 63–74. https://doi.org/10.1002/pro.4181.

I recommend installing in a virtualenv to avoid any conflicts with your python installation. nightshift is available on the PyPI and can be installed with pip:

pip install nightshift

To install a local version downloaded from GitHub, use:

pip install /path/to/nightshift

You will need to know your protein of interest's BMRB entry number. You can use nightshift's search command to find entry numbers:

nightshift search ubiquitin

We'll use 4493 Solution structure of the designed hydrophobic core mutant of ubiquitin, 1D7 for our examples.

Two major use cases are getting an idea what a amide or methyl spectrum of your protein would look like

To simulate 1H-15N HSQC spetra can be plotted using the --amide flag:

nightshift get 4493 --amide

To show Asn and Gln side chain amides on the spectrum pass the optional --sidechains flag:

nightshift get 4493 --amide --sidechains

A simulated 1H-13C HMQC spetra can be plotted using the --methyl flag, additionally providing the optional proS or proR will filter LV atoms by prochirality:

nightshift get 4493 --methyl --proS

All plots can be filtered based on residue type by passing the --residues or -r flag and providing one-letter amino acid codes. For instance an ILV methyl labeled spectrum can be plotted using:

nightshift get 4493 --methyl -r ILV

For arbitrary correlations use the --custom flag followed by two atom names. Consider yourself warned that labeling schemes and/or experiments to produce these correlations may not (currently) exist. Atoms for custom correlations are specified using standard PDB atom names: H for amide proton, N for amide nitrogen, C for carbonyl carbon, CA for alpha carbon, HA for alpha proton and so on. For particular residues two or more atoms may exist at a position (i.e. CG for Val could be CG1 or CG2). To specify both CG1 and CG2 for Val pass CG:

nightshift get 4493 --custom CG CA -r V

or specify the full atom name to only get those atoms:

nightshift get 4493 --custom CG1 CA -r V

Two special atom names also exist for custom correlations: Hmethyl and Cmethyl. Which correspond to these atoms in MILVAT residues and are the same atoms selected by using the --methyl flag. The flags --proS and --proR can be used with Hmethyl and Cmethyl

This allows for correlations of methyl groups to any other atom to be plotted. For instance Cmethyl to CA:

nightshift get 4493 --custom Cmethyl CA -r ILV

Adding '-' or '+' and any number to the end of a custom atom name allows correlation to the i+/- num residue. For instance correlation of the CO of the i-1 residue to the amide N of the i residue:

nightshift get 4493 --custom C-1 N

The --custom option also allows for 3D correlations to be plotted. The matplotlib window will show 2D slices of the simulated spectrum. Scrolling the mouse wheel will switch between each slice:

nightshift get 4493 --custom H N CA

By default 16 slices are generated, this can be altered with the --slices option (i.e. slices 32 or slices 1 for a 2D projection). The --project parameter can take a value of 1, 2 or 3 which chooses which dimension to project on. For a 3D HNCA (NOTE: you must escape with double quotes):

nightshift get 4493 --custom "H N (CA CA-1)" --project 2 --slices 32

Plus and minus can also be used on 3D correlations:

nightshift get 4493 --custom HA N+1 CA+2 --project 1

By default plots are generated in matplotlib and are interactive. To save directly to an image file use the --output or -o flag and provide a file name and extension (.eps, .pdf, .pgf, .png, .ps, .raw, .rgba, .svg, and .svgz are all acceptable).

Formatting options include:

• --showlegend to add a legend
• --nolabels to remove the residue/atom name and numbers from the plot, also shows the legend
• --offset to add a constant to the indices used by BMRB (to reflect the numbering you are used to)
• --color takes a color such as red which will color all residues one color or a matplotlib colormap name such as viridis or tab20 which will color each residue with a differen color on the colormap

A csv file containing the label and chemical shifts of both atoms can be saved using the --csv flag and providing a file name:

nightshift get 4493 --methyl -r ILV --csv output.csv

this can be opened in other software to generate plots with different formatting. Also the auxiliary script plot_outputs.py can be used to overlay multiple spectra (i.e. different domains of the same protein or a protein complex).

This example is nonsense, but illustrates how it could be done. First, generate two output files:

nightshift get 4493 --amide --csv output1.csv

nightshift get 3433 --amide --csv output2.csv

Then plot their overlay:

nightshift open output1.csv output2.csv

If two labels are the same between the proteins (labels are residue type and sequence number), you can visualize tahe CSP using --showcsp, which will draw a line between the two. This works for 4493 and 3433, but is not very informative.

nightshift open output1.csv output2.csv --showcsp

Also accepts the --showlegend and --nolabels flags. --colors takes a list of color names or list of colormaps and works like --color for individual plots.

• ILV methyl spectrum:

  nightshift get 4493 --methyl -r ILV

• ILV methyl spectrum with proR LV:

  nightshift get 4493 --methyl proR -r ILV

• Amide spectrum of only lysines and arginines:

  nightshift get 4493 --amide -r KR

• 2D HMBC-HMQC (intra-residue methyl-methyl correlations):

  nightshift get 4493 --custom Cmethyl Cmethyl -r LV

• 2D NCO:

  nightshift get 4493 --custom C-1 N

• 2D CAN

  nightshift get 4493 --custom "(CA CA-1) N" --label 1

• 3D HNCACB nightshift get 4493 --custom "H N (CA CA-1 CB CB-1)" --project 2 --label 3 --slices 32

• 3D 15N TOCSY HSQC nightshift get 4493 --custom "H H# N" --slices 64

• Arg/Lys side chain carbon correlations (a la Pritchard and Hansen, 2019)

  nightshift get 4493 --custom CG CD -r R --csv 4493_arg.csv

  nightshift get 4493 --custom CD CE -r K --csv 4493_lys.csv

  nightshift open 4493_arg.csv 4493_lys.csv --showlegend

I have only tested that this works for amide and methyl because of limitations with NMRpipe. It is possible other correllations will work fine. See the cs2pk.tcl documentation. There is a hacky work around where methyl spectra are considered HA/CA spectra. To generate the TALOS file required as input use the --talos flag: nightshift get 4493 --amide --talos 4493.tab

or

nightshift get 4493 --methyl -r ILV --talos 4493.tab

To transfer run the following for amide:

cs2pk.tcl -in 4493.tab -out sim.tab -type hn

and for methyl:

cs2pk.tcl -in <talos.tab> -out <sim.tab> -type haca

Compare against your spectrum visually (assuming the name of the file is test.ft2 and the peak list is test.tab):

specView.tcl -in test.ft2 -multiColor -peak -tab test.tab -pkLab ASS -ass sim.tab -outTab out.tab -xAssVar X_PPM -yAssVar Y_PPM

or automatically without an interface:

ipap.tcl -specName1 test.ft2 -inName1 test.tab -outName1 out.tab -assName sim.tab -xVar X_PPM -xAss X_PPM -yVar Y_PPM -yAss Y_PPM -single -ndim 2 -exit

See the documentation for specView.tcl and ipap.tcl for a full list of parameters.