/CSpred

UCBShift is a program for predicting chemical shifts for backbone atoms and β-carbon of a protein in solution. It utilizes a machine learning module that makes predictions from features extracted from the 3D structures of the proteins.

Primary LanguageJupyter Notebook

UCBShift

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.

Publication

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

Using UCBShift through NMRBox

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/

Software package requirements

Python and python packages

External programs needed

Installation notes

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.

Usage

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.pdb

Advanced 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

Outputs

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).

Reproducibility

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.

FAQs

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.