*********************************************************************
*           _        ____                _   _                      *
*          | |_ _ __|  _ \ ___  ___  ___| |_| |_ __ _               *
*          | __| '__| |_) / _ \/ __|/ _ \ __| __/ _` |              *
*          | |_| |  |  _ < (_) \__ \  __/ |_| || (_| |              *
*           \__|_|  |_| \_\___/|___/\___|\__|\__\__,_|              *
*                                                                   *
* J Yang et al, Improved protein structure prediction using         *
* predicted interresidue orientations, PNAS, 117: 1496-1503 (2020)  *
* Please email your comments to: yangjy@nankai.edu.cn               *
*********************************************************************


Instructions for instaling and running the trRosettaX standalone package.


Overview
=======
trRosettaX is a transform-restrained Rosetta algorithm for protein structure prediction,
with restraints from deep learning and homologous templates.

Requirements
=======

*	[Python (>= 3.6)](https://www.python.org/downloads, already installed in most Linux system)
*	[Tensorflow (1.13 or 1.14)](https://pypi.org/project/tensorflow)
*	[PyRosetta3](http://www.pyrosetta.org/dow/pyrosetta3-download) 
*	[Perl (5.0)](https://www.perl.org/get.html, already installed in most Linux system)
*	[HHsuite](https://github.com/soedinglab/HHsuite)
*	[HHsuite sequence Database](http://wwwuser.gwdg.de/~compbiol/uniclust/2018_08)

*	[HHsuite database for PDB templates](optional, http://wwwuser.gwdg.de/~compbiol/data/hhsuite/databases/hhsuite_dbs)
*	[PDB structure files (optional, available at our website)](https://yanglab.nankai.edu.cn/trRosetta/download)

*	[Pre-trained network models (available at our website)](https://yanglab.nankai.edu.cn/trRosetta/download)


Installation
=======
_Warning_: trRosettaX is based on tensorflow 1.x, which may be not compatible with CUDA11.x. 
To run geometries prediction (step 3) on GPU, the user should install [CUDA 10.0](https://developer.nvidia.com/cuda-toolkit-archive) together with [CUDNN 7.4.x](https://developer.nvidia.com/rdp/cudnn-archive).
Otherwise the geometries prediction would use CPU only (need ~3 min. on the example).  
An example guide: https://gist.github.com/kmhofmann/cee7c0053da8cc09d62d74a6a4c1c5e4

A new environment can be created and activated with conda 
```
# create conda environment for trRosettaX
conda env create -f linux.yml

# acitvate the installed environment
conda activate tRX
```

Before install pyRosetta, the user should obtain the PyRosetta license from (https://els2.comotion.uw.edu/product/pyrosetta).
And the RosettaCommons conda channel (depend on the license information) can be added to the channel lists (see [RosettaCommons Conda Channel](https://www.pyrosetta.org/downloads#h.c0px19b8kvuw)).
Then run
```
conda install -y pyrosetta
```

Usage
========

Step 1. Prepare MSA with the script generate_msa.py

	Generate an MSA (in A3M format) for your protein sequence by HHblits from the HHsuite package.	
	One should download the HHsuite package (https://github.com/soedinglab/HHsuite) and sequence database first.
	
		Recommended databases:
			uniclust2018 (http://wwwuser.gwdg.de/~compbiol/uniclust/2018_08/uniclust30_2018_08.tar.gz)
			uniref2020 (https://ftp.uniprot.org/pub/databases/uniprot/previous_major_releases/release-2020_01/uniref/uniref2020_01.tar.gz)
			BFD (https://bfd.mmseqs.com/bfd_metaclust_clu_complete_id30_c90_final_seq.sorted_opt.tar.gz)
		
	Only one database is needed. The smallest one uniclust30_2018_08 (<10G) is recommended, if there is no special requirement.
	
	
	Usage:
	
		```
		python generate_msa.py -i example/generate_msa/seq.fasta -o example/generate_msa/seq.a3m -hhbin /home/software/hhsuite3/bin -hhdb /library/uniclust30/uniclust30_2018_08  -e_value 0.001 -cpu 2
		```
		
	Args:
		> -i           input FASTA file (*required*)
		> -o           output A3M file (*required*)
		> -hhbin       path to the HHsuite binary files (*required*)
		> -hhdb        path to the sequence database (*required*)
			note:
				write until the ffindex files' prefix. 
				E.g., if there are some ffindex/ffdata files under the directory `/library/uniclust30`, such as `uniclust30_2018_08_a3m.ffdata`,
						then the argument `-hhdb` should be `/library/uniclust30/uniclust30_2018_08`.
		
		> -e_value     e-value used for hhblits (optional, default:0.001)

		> -cpu         number of CPUs to use (optional, default:2)
		
		
Step 2 (Optional). Search for homologous templates with the script search_templates.py 

	This script will run HHsearch to detect homolgous templates. (Can be skipped if only de novo prediciton is needed)
	
	One should first download: 
		1.the HHsuite database pdb70 (http://wwwuser.gwdg.de/~compbiol/data/hhsuite/databases/hhsuite_dbs/pdb70_from_mmcif_latest.tar.gz).
		2.the PDB database, available at our website (https://yanglab.nankai.edu.cn/trRosetta/download)
		
	Usage:
	  
		``` 
		python search_templates.py -i example/search_templates/seq.a3m -o example/search_templates/temp.npz -hhbin /home/software/hhsuite3/bin -hhdb /library/pdb70/pdb70 -pdb_db /library/pdb_files -cpu 2
		```
		
	Args:
		> -i           input A3M file (*required*)
		> -o           output npz file storing the template information (*required*)
		> -hhbin       path to the HHsuite binary files (*required*)
		> -hhdb        path to the HHsuite database (*required*)
			note:
				write until the ffindex files' prefix. 
				E.g., if there are some ffindex/ffdata files under the directory `/library/pdb70`, such as `pdb70_a3m.ffdata`,
						then the argument `--hhdb` should be `/library/pdb70/pdb70`.
		> -pdb_db      path to the pdb database (*required*)
		> -cpu         number of CPUs to use (optional, default:2)
		

	  Only homologous templates will be used, which satisfy probability>60%, E-value<0.001, and coverage>0.3. 

Step 3. Predict the inter-residue geometries with the script predict.py
	
	One should first download network models from our website (https://yanglab.nankai.edu.cn/trRosetta/download)

	Usage:

		```
		python predict.py -i example/predict/seq.a3m -o example/predict/seq.npz -mdir ./model_res2net_202108
		```

	Note that predict.py is a unified program. The default mode of it is de novo prediction without templates. 
	To include homologous templates, one should first prepare the template npz file (with the script in Step 2) and add arguments `-temp_npz`.  
		```
		python predict.py -i example/predict/seq.a3m -o example/predict/seq.npz -mdir ./model_res2net_202108 -temp_npz example/predict/temp.npz
		```

	Args:

		> -i		  input multiple sequence alignment in A3M/FASTA format (*required*)
		> -o		  output npz file containing predicted distograms and anglegrams (*required*)
		> -mdir	      path to pretrained models (*required*)
		> -temp_npz   templates npz file (*required if TBM prediction is needed*)
		> -cont       output csv file containing predicted CB-CB contacts (optional, default not to output)
		> -gpu	      use which GPU (optional, default to "-1", i.e., use CPU only)
			note: 
				The GPU card used here should be consistent with that obtained by the command `nvidia-smi`.
				One should make sure that there is enough memory on the GPU card to use. 
				E.g., one can assign `--gpu 0` if he wants to use the 1st GPU card listed by `nvidia-smi`.
		> -cpu	      number of CPUs to use (optional, default: 2)


Step 4. Structure prediction with trRosetta.py

	This script generates structure models using the predicted inter-residue geometries. 

		```
		python trRosetta.py -npz example/trRosetta/seq.npz -fasta example/trRosetta/seq.fasta -o example/trRosetta/model.pdb
		```
	Args:

		> -npz		   input distograms and anglegrams (*required*, inter-residue geometry predictions)
		> -fasta	   input query sequence (*required*, in FASTA format)
		> -o		   output model (*required*, in PDB format)
		> -pd		   PCUT, min probability of distance restraints (optional, default: 0.05)
		> -m		   {0,1,2}, 0: sh+m+l, 1: (sh+m)+l, 2: (sh+m+l) (optional, default: 2)
		> -orient      {True, False}, True: use orientations, False: not use orientations (optional, default: True)
		> -fastrelax   {True, False}, True: perform FastRelax, False: not perform FastRelax (optional, default: True)
		
	The confidence estimation for the top-predicted model is stored in the file "cscore.txt".
	The predicted local and global lDDT scores for the top-predicted model are stored in the file "model.plddt.npz".

	Note that this script generates one model in each run with default options, which usually works well for easy targets.
	However, for harder targets, we suggest generating more models and select the best based on energy scores. 
	To this end, one can use the script 'run_trRosetta.py' introduced below.



Step 4. (Alternative for trRosetta.py). Structure prediction with run_trRosetta.py

	This script generates diverse models and selects the final models automatically. 
	It is essentially done by running trRosetta.py multiple times with different settings. Thus it is slower than trRosetta.py.

		```
		python run_trRosetta.py -npz example/run_trRosetta/seq.npz -fasta example/run_trRosetta/seq.fasta -o example/run_trRosetta
		```

	args:

		> -npz		   input distograms and anglegrams (*required*,inter-residue geometry predictions)
		> -fasta	   input query sequence (*required*,in FASTA format)
		> -o	       output directory (*required*,storing the output PDB files)
		> -n		   number of output models  (optional, default: 1)
		> -cpu		   number of CPU cores to be used in parallel (optional, default: 2)
		> -orient	   {True, False}, True: use orientations, False: not use orientations (optional, default: True)
		
	The confidence estimation for the top-predicted model is saved in the file "cscore.txt".
	The predicted local and global lDDT scores for the top-predicted model are stored in the file "model*.plddt.npz".	
	Even with '-n 1', multiple models will be generated and the best one will be selected automatically with this script.



Other useful scripts:

	1. npz_2_dist.py
	It converts the distance distribution in the predicted NPZ file into real distance and visualizes the predicted contact and distance maps.
	
		```
		python npz_2_dist.py example/seq.npz seq
		```

	2. pdb2npz.py
	It calculates and visualizes the inter-residue distance and orientations from the input of a PDB structure file. 

		```
		python pdb2npz.py -f example/model.pdb
		```
		
	3. top_prob.py
	It calculates the average probability of the top-predicted distance.

		```
		python top_prob.py example/seq.npz
		```


If you have questions or comments, please contact us at: yangjy@nankai.edu.cn
October 9, 2021


 
