UCBShift is a program for predicting chemical shifts for backbone atoms and β-carbon of a protein in solution. The program implements two mechanisms: a transfer prediction module that employs both sequence alignment and structure alignment to select references for shift replication; and an ensemble decision tree based machine learning module which takes features extracted from a PDB file and makes trustful chemical shift predictions. When combined together, this new predictor achieves state-of-the-art accuracy for predicting chemical shifts in a "real-world" dataset, with root-mean-square errors of 0.38, 0.22, 1.31, 0.97, 1.29 and 2.16 ppm between prediction and experimental values for H, Hα, C, Cα, Cβ and N.
Li, J., Bennett, K. C., Liu, Y., Martin, M. V., & Head-Gordon, T. (2020). Accurate prediction of chemical shifts for aqueous protein structure on “Real World” data. Chemical Science, 11(12), 3180-3191. DOI: 10.1039/C9SC06561J
We recommend users run UCBShift through NMRBox, which provides out-of-box using experience for UCBShift in their virtual machines. You can sign up for NMRBox here: https://nmrbox.nmrhub.org/
- Python (>=3.5)
- Numpy
- Pandas
- scikit learn (0.22, https://scikit-learn.org/stable/)
- Biopython (1.74, https://biopython.org/)
- Joblib (https://joblib.readthedocs.io/en/latest/)
- matplotlib
- blast (2.9.0, https://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs&DOC_TYPE=Download)
- mTM-align (20180725, http://yanglab.nankai.edu.cn/mTM-align/)
- DSSP (2.04, https://swift.cmbi.umcn.nl/gv/dssp/)
We suggest creating new virtual environments (i.e. anaconda) for the code. You can install the required packages using the provided requirements.txt file
pip install -r requirements.txt
However you still need to download and install the external programs manually.
Because the trained models are big, users are directed to here to download all the saved model files. After downloading the models.tgz file, extract them into the models/ folder using the command tar -xzf models.tgz (so that there will be 18 .sav files under models/ folder)
Users can use the trained model "as is" once they have correctly configured the python packages and external programs.
The CSpred.py file is the entrance to UCBShift chemical shift predictor.
The easiest, out-of-the-box way of using UCBShift is running CSpred.py script directly on your desired protein. A [shifts.csv] file will be generated at the same position where you executed the script. The syntax will be something like this:
python CSpred.py your_input_protein.pdbAdvanced options are described below:
usage: CSpred.py [-h] [--batch] [--output OUTPUT] [--worker WORKER]
[--shifty_only] [--shiftx_only] [--pH PH] [--test]
input
positional arguments:
input The query PDB file or list of PDB files for which the
shifts are calculated
optional arguments:
--batch, -b If toggled, input accepts a text file specifying all
the PDB files need to be calculated (Each line is a
PDB file name. If pH values are specified, followed
with a space)
--output OUTPUT, -o OUTPUT
Filename of generated output file. A file [shifts.csv]
is generated by default. If in batch mode, you should
specify the path for storing all the output files.
Each output file has the same name as the input PDB
file name.
--worker WORKER, -w WORKER
Number of CPU cores to use for parallel prediction in
batch mode.
--shifty_only, -y, -Y
Only use UCBShift-Y (transfer prediction) module.
Equivalent to executing UCBShift-Y directly with
default settings
--shiftx_only, -x, -X
Only use UCBShift-X (machine learning) module. No
alignment results will be utilized or calculated
--pH PH, -pH PH, -ph PH
pH value to be considered. Default is 5
--test, -t If toggled, use test mode for UCBShift-Y prediction
If you want to execute UCBShift-Y with more options, you can run ucbshifty.py.
usage: ucbshifty.py [-h] [--output OUTPUT] [--strict STRICT] [--secondary]
[--test] [--exclude] [--shifty]
input
This program executes both sequence-based alignment (using BLAST) and
structure-based alignment (using mTM-align) to find the best alignment for a
specific pdb file with entities in the refDB database, and use the average
chemical shifts from refDB to predict the chemical shifts for backbone H/C/N
atom chemical shifts for the query protein
positional arguments:
input The query PDB file for which the shifts are calculated
optional arguments:
-h, --help show this help message and exit
--output OUTPUT, -o OUTPUT
Filename of generated output file. A file [shifts.csv]
is generated by default
--strict STRICT, -s STRICT
Strict level of shift transfer: 0 - Strict, only the
exact matching residue shifts are transferred 1 -
Normal, transfer the shifts for residues that are the
same or have positive substitution scores (from
BLOSUM62) 2 - Permissive, transfer all shifts
regardless of the likeliness of substitution.
--secondary, -2 If this flag is set, the output will be secondary
shifts (observed shifts-random coil shifts) instead of
observed shifts
--test, -t If this flag is set, the test BLAST database is used,
which means all sequences in the validation set and
test set will not be included in the BLAST search
database
--exclude, -e Exclude mode, another way of analyzing the performance
of SHIFTY++. When selecting sequences going to the
structure alignment, those completely identical
examples are excluded.
--shifty, -y SHIFTY mode, only the top hit from sequence alignment
is considered for shift transfer
A shifts.csv file will be generated by default under the folder where you run the CSpred.py script. For each amino acid in the protein, a line is reported in the generated .csv file that contains the residue number (RESNUM), residue name (RESNAME), UCBShift-X predictions ([atom]_X), UCBShift-Y predictions ([atom]_Y), UCBShift final predictions ([atom]_UCBShift), the TM-score for the best matched sequence from UCBShift-Y of that residue ([atom]_BEST_REF_SCORE), amino acid coverage for the best matched sequence from UCBShift-Y ([atom]_BEST_COV), and whether the residue is matched for the best-aligned protein ([atom]_BEST_REF_MATCH).
You can reproduce the results by preparing all the data and retrain the model on your own machine. Follow PROCEDURE.md under the folder train_model/ for a complete description of how to train the model.
Q: I have run into the following issue:
......
File "/home/shreygupta/soft/ucbshift/ucbshifty.py", line 362, in Needleman_Wunsch_alignment
aligner.substitution_matrix=blosum62
File "/home/shreygupta/.local/lib/python3.6/site-packages/Bio/Align/__init__.py", line 1509, in __setattr__
_aligners.PairwiseAligner.__setattr__(self, key, value)
ValueError: expected a matrix
How can I solve the problem?
A: This is a common issue caused by a higher version of the Biopython package. Please downgrade the biopython to version 1.74 if you run into this error. Alternatively, we suggest using UCBShift through NMRBox. Please see section above.