INSTALLATION AND IMPLEMENTATION OF DEMO-EM SUITE (Copyright 2021 by Zhang Lab, University of Michigan, All rights reserved) (Version 1.0, 2021/07/26) 1. What is DEMO-EM Suite? The DEMO-EM Suite is a composite package of programs for protein structure modeling from cryo-EM denisty maps. The Suite includes the following programs: a) DEMO-EM: A hierarchical program for protein structure aseembly using experimental or predicted domain models b) FUpred: A deep-learning based program for domain boundary prediction c) ThreaDom: A threading template based program for domain boundary prediction d) DomainDist: A deep residual neural-network algorithm for inter-domain distance prediction e) I-TASSER: A deep-learning based program for single-domain protein structure modeling f) DeepMSA: A program for multiple sequence alignmnet generation g) SPICKER: A clustering program for structure decoy selection h) FASPR: A program for protein side-chain packing i) LOMETS2: A meta-approach included in I-TASSER for threading templates identification j) ModRefiner: Construct and refine atomic model from C-alpha traces k) NWalign: Protein sequence alignments by Needleman-Wunsch algorithm l) PSSpred: A program for Protein Secondary Structure PREDiction 2. How to install the DEMO-EM Suite? a) download the DEMO-EM Suite 'DEMO-EM-1.0.tar.gz' from https://zhanggroup.org/DEMO-EM/standalone_package/ and unpack 'DEMO-EM-1.0.tar.gz by > tar -zxvf DEMO-EM-1.0.tar.gz The root path of this package is called $pkgdir, e.g. /home/yourname/DEMO-EM-1.0. You should have all the programs under this directory. You can install the package at any location on your computer. b) Download DEMO-EM library files from https://zhanggroup.org/DEMO-EM/standalone_package/ A script 'download_lib.pl' is provided in the package for automated library download and update of the libraries. The library needs about 150GB of the disk space. We recommend putting the library files under the path /home/yourname/ITLIB. c) Third-party software installation: While the majority of programs in the package 'DEMO-EM-1.0.tar.gz' are developed in the Zhang Lab herein the permission of use is released, there are some programs and databases (including blast, nr, uniclust30, uniref90 and metaclust) which were developed by third-party groups. A default version of blast and nr are included in the package. It is user's obligation to obtain license permission from the developers for all the third-party software before using them. In addition, your system needs to have Java, python2, python3 (which supports pytorch >1.1.0) installed. To use DeepMSA, you need download uniclust30, uniref90 and metaclust from http://gwdu111.gwdg.de/~compbiol/uniclust/2017_04/uniclust30_2017_04_hhsuite.tar.gz , ftp://ftp.uniprot.org/pub/databases/uniprot/uniref/uniref90/uniref90.fasta.gz , and https://metaclust.mmseqs.org/2017_05/metaclust_2017_05.fasta.gz. after you unpack them, put the entire folder to the DEMO-EM library folder, (i.e. where the folder you put your PDB, MTX, DEP folders). Then rename the folder uniclust30_xxx_xxx to uniclust30, uniref90_xxx to uniref90, metaclust_xxx to metaclust. Then use $pkgdir/contact/DeepMSA/bin/esl-sfetch to create .ssi index for uniref90 and metaclust, here $pkgdir means the path where you put the DEMO-EM suite package. For example, if the uniref90 database in uniref90 folder is named as uniref90.fasta, then go to uniref90 folder, run $pkgdir/contact/DeepMSA/bin/esl-sfetch --index uniref90.fasta, you will find a new file named as uniref90.fasta.ssi after the command done. Then do the same thing to metaclust database. If you use different version of uniclust30, uniref90 or metaclust, please go to $pkgdir/run_DEMO-EM.py, change the variables: $hhbdbdir = "$libdir/uniclust30"; $jacdbdir = "$libdir/uniref90"; $hmsdbdir = "$libdir/metaclust"; $hhbdb = "$libdir/uniclust30/uniclust30_2017_04"; $jacdb = "$libdir/uniref90/uniref90.fasta"; $hmsdb = "$libdir/metaclust/metaclust.fasta"; 3. Bug report: Please report and post bugs and suggestions at the message board: http://zhanglab.dcmb.med.umich.edu/forum ####################################################### # # # 4. Installation and implementation of DEMO-EM # # # ####################################################### 4.1. Introduction of DEMO-EM DEMO-EM is a hierarchical method to assemble multi-domain protein structures from cryo-EM density maps. It starts with query sequence and cryo-EM density maps, with individual domain structure constructed with FUpred, ThreaDom and I-TASSER. Next, the multi-domain complex structure is constructed by a progressive rigid-body domain assembly and atomic-level flexible structural refinement process under the guidance of cryo-EM density maps and deep-learning distance profiles. Large-scale benchmark tests have shown significant advantage of DEMO-EM over traditional homologous template based approaches for high-accuracy multi-domain protein structure modeling, especially for the case with medium-to-low resolution denisty maps and without homologous full-length structures. 4.2. How to run DEMO-EM? a) Main script for running DEMO-EM is $pkgdir/run_DEMO-EM.py, where "$pkgdir" is the location of run_DEMO-EM.py script. Run it directly without arguments will output the help information. b) The following arguments must be set (mandatory arguments). One example is: "$pkgdir/run_DEMO-EM.py protein_name input_dir sequence density_map_path resolution [Options]" protein_name is the name of the folder containg the protein sequence and cryo-EM density map input_dir is the directory which contains the query folder sequence is the directory of your query sequence density_map_path is the directory of your cryo-EM density map resolution is the resolution of the cryo-EM density map c) Other arguments are optional whose default values have been set. User can reset one or more of them. One example of command line is: "$pkgdir/run_DEMO-EM.py protein_name input_dir sequence density_map_path resolution -libdir libdir" -template [no, yes], flag of using analogous templates to guide the assembly. The default value is "no". -deepdist [no, yes], flag of predicted distance by DomainDist to guide the assembly. The default value is "yes". -fullmodel [no, yes], flag of using initial full-length model generated by LOMETS to guide the assembly. The default value is "no". Modeller is required if it is set to "yes". -expdom Provide the experimental domain information including domain definition and PDB of domain models if some experimental domain models are available. See the websever or the following explanation of the format. -quick [no, yes], flag of LOMETS-based quick domain modeling. The default value is "no". Modeller is required if it is set to"yes". -light [no, yes], (default: no) this option runs quick modeling of I-TASSER -libdir means the path of the template libraries for I-TASSER. The default directory is "$pkgdir/ITLIB". You must use this option to change the path if you did not put it in the default directory. -java_home means the path contains the java executable "bin/java" (your system needs to have Java installed) -runstyle default value is "serial" which means running I-TASSER simulation sequentially. "parallel" means running parallel simulation jobs in the cluster using PBS/torque job scheduling system. "gnuparallel" means running parallel simulation jobs on one computer with multiple cores using GNU parallel -run [real, benchmark], "real" will use all templates, "benchmark" will exclude homologous templates with sequence identify >0.3 -python2 path to python 2, for example /usr/bin/python -python3 path to python 3 for distance prediction, need to support pytorch 1.1.0, for example /usr/bin/python3 d) Where are the final predicted results?     The following results are included in "/input_dir/protein_name": "fmodel*.pdb" the final model created by DEMO-EM "dom*.pdb" the domain model predicted by I-TASSER "score.txt" inclides the correlation coefficient (CC) score, the itegrated integrated Fourier Shell Correlation (iFSC), and the estimated TM-score "CC_score.txt" the CC score of each residue in the final model "FUpred.info" the predicted domain boundary "seq.ss" the secondary structure predicted by PSSpred NOTE: a) Outline of steps for running DEMO-EM by 'run_DEMO-EM.py': a1) Prase user provided information a2) run 'LOMETS2' to determine the protein type and generate a initial full-length model according to the threading templates a3) run 'ThreaDom' or 'FUpred' to predict the domain boundary a4) run 'I-TASSER' to predict the model of each domain. If the protein is predicted as a single-domain protein, the full-length model will be directly generated by I-TASSER. a5) run 'assembly' to assemble all domain models into a full-length model and perform the flexible refinement. If the protein is predicted as a single-domain protein, only the flexible refinement will be performed. b) 'seq.fasta' is the query sequence file in FASTA format, which is the only needed input file except for the cryo-EM density map. This file should be put in "./input_dir/protein_name" before running this job. c) If working on a cluster with multiple nodes, it is recommended to set $runstyle="parallel". You need have PBS server installed in your system. Parallel jobs will run faster since jobs are distributed among different nodes. The default setting $runstyle="serial" will run all the jobs on a single computer. d) If the job has been executed partially and encounter some error, you can rerun the main script without modification. It will check the existing files and start from the correct position. e) If you set "-fullmodel" or "-quick" to "yes", you need to download the Modeller from https://salilab.org/modeller/ and install it in "$pkgdir/modeller". Instead of using this option, you can set "-light" to "yes" to use the fast I-TASSER for domain modeling. f) If you want to provide the experimental models for some domains, please prepare the file in the following format: The file starts with the domain definition of the query sequence in the first line. The experimental domain information starts from the second line with the residue index range of the domain wirten in the first line. See the detailed explanation and example at https://zhanggroup.org/DEMO-EM/explanation_expdom.html 4.3 System requirement: a) x86_64 machine, Linux kernel OS, Free disk space of more than 150G. b) Perl, python, and java interpreters should be installed. c) Basic compress and decompress package should be installed to support: tar and bunzip2. d) If you are using computer clusters, job management software PBS server should support 'qsub' and 'qstat'. If using other job management software, such as SGE and Slurm, some changes should be made following the instructions at: http://zhanglab.dcmb.med.umich.edu/bbs/?q=node/3561 4.4. How to cite DEMO-EM and DEMO-EM Suite? Xiaogen Zhou, Yang Li, Chengxin Zhang, Wei Zheng, Guijun Zhang, and Yang Zhang. Progressive and accurate assembly of multi-domain protein structures from cryo-EM density maps. Submitted, 2021. ####################################################### # # # 5. Installation and implementation of FUpred # # # ####################################################### 5.1. Introduction of FUpred FUpred is a contact map-based domain prediction method which utilizes a recursion strategy to detect domain boundary based on predicted contact-map and secondary structure information. Large scale benchmark analysis shows that FUpred has significantly better ability of domain boundary prediction than threading-based method and machine learning-based methods. Particularly, our method has obviously excellent performance in detecting discontinuous domain boundary than current methods. 5.2. How to install FUpred program? When you unpack the DEMO-EM Suite, the FUpred program is already installed in $pkgdir/FUpredmod. 5.3. How to run FUpred program? Usage: $pkgdir/FUpredmod/run_FUpred.pl protein_name input_dir To run FUpred, you need to prepare following input files: 'protein_name'--Mandatory, the name of the folder containg the sequence and density map 'input_dir'-----Mandatory, the directory which contains the query folder Output files of FUpred include: 'FUpred.info'---The predicted domain boundary 'FUpred.2c'-----The FUscore for continuous domain detection 'FUpred.2d'-----The FUscore for discontinuous domain detection A detailed readme file can be found at https://zhanglab.dcmb.med.umich.edu/FUpred/download/FUpred/readme.txt 5.4. How to cite FUpred? If you are using the FUpred program, you can cite: Wei Zheng, Xiaogen Zhou, Qiqige Wuyun, Robin Pearce, Yang Li and Yang Zhang. FUpred: Detecting protein domains through deep-learning based contact map prediction. Bioinformatics, 36: 3749–3757, 2020. ####################################################### # # # 6. Installation and implementation of ThreaDom # # # ####################################################### 6.1. Introduction of ThreaDom ThreaDom (Threading-based Protein Domain Prediction) is a template-based algorithm for protein domain boundary prediction. Given a protein sequence, ThreaDom first threads the target through the PDB library to identify protein template that have similar structure fold. A domain conservation score (DCS) will be calculated for each residue which combines information from template domain structure, terminal and internal gaps and insertions. Finally, the domain boundary information is derived from the DCS profile distributions. ThreaDom is designed to predict both continuous and discontinuous domains. 6.2. How to install ThreaDom program? When you unpack the DEMO-EM Suite, the ThreaDom program is already installed in $pkgdir/ThreaDommod. 6.3. How to run ThreaDom program? Usage: $pkgdir/ThreaDommod/runThreaDom.pl protein_name input_dir -libdir libdir To run ThreaDom, you need to prepare following input files: 'protein_name'--Mandatory, the name of the folder containg the sequence and density map 'input_dir'-----Mandatory, the directory which contains the query folder 'libdir'--------Mandatory, the path of the template libraries Output file of ThreaDom include: 'protein_name.sd'---The predicted domain boundary A detailed readme can be found in th package. 6.4. How to cite ThreaDom? If you are using the ThreaDom program, you can cite: Yan wang, Jian Wang, Qiang Shi, Ruiming Li，Zhidong Xue, Yang Zhang. ThreaDomEx: a unified platform for predicting continuous and discontinuous protein domains by multiple-threading and segment assembly. Nucleic acids research. 45: W400-407, 2017. ####################################################### # # # 7. Installation and implementation of I-TASSER # # # ####################################################### 7.1. Introduction of I-TASSER I-TASSER (Iterative Threading ASSEmbly Refinement) is a method for high-accuracy protein structure and function prediction. Starting from a query sequence, I-TASSER first generates inter-residue restraints by multiple deep neural-network predictors. It then identifies structural templates from the PDB by multiple threading approach LOMETS2, with full-length atomic models assembled by contact-map guided replica-exchange Monte Carlo simulations. 7.2. How to install I-TASSER program? When you unpack the DEMO-EM Suite, the I-TASSER program is already installed in $pkgdir/I-TASSERmod. 7.3. How to run I-TASSER program? The I-TASSER main script is $pkgdir/I-TASSERmod/runI-TASSER.pl. The running option of this program is similar to run_DEMO-EM.py. By running the program without argument, you can print all the running options. A detailed readme can be found in th package. 7.4. How to cite I-TASSER? If you are using the I-TASSER program, you can cite: 1. Wei Zheng, Chengxin Zhang, Yang Li, Robin Pearce, Eric W. Bell, Yang Zhang. Folding non-homology proteins by coupling deep-learning contact maps with I-TASSER assembly simulations. Cell Reports Methods, 1: 100014 (2021). 2. Y Zhang. I-TASSER server for protein 3D structure prediction. BMC Bioinformatics, 9: 40 (2008). 3. A Roy, A Kucukural, Y Zhang. I-TASSER: a unified platform for automated protein structure and function prediction. Nature Protocols, 5: 725-738 (2010). 4. J Yang, R Yan, A Roy, D Xu, J Poisson, Y Zhang. The I-TASSER Suite: Protein structure and function prediction. Nature Methods, 12: 7-8 (2015) ####################################################### # # # 8. Installation and implementation of DeepMSA # # # ####################################################### 8.1. Introduction of DeepMSA DeepMSA is a new open-source method for sensitive MSA construction, which has homolo- gous sequences and alignments created from multi-sources of whole-genome and metagenome databases through complementary hidden Markov model algorithms. 8.2. How to install DeepMSA program? When you unpack the DEMO-EM Suite, DeepMSA program is already installed. 8.3. How to run DeepMSA program? The DeepMSA main script is $pkgdir/contact/DeepMSA/scripts/build_MSA.py. The running option of this program is similar to that in runI-TASSER.pl. By running the program without argument, you can print all the running options. 8.4. How to cite DeepMSA? If you are using the DeepMSA program, you can cite: C Zhang, W Zheng, S M Mortuza, Y Li, Y Zhang. DeepMSA: constructing deep multiple sequence alignment to improve contact prediction and fold-recognition for distant-homology proteins. Bioinformatics 36: 2105-2112 (2020). ####################################################### # # # 9. Installation and implementation of LOMETS2 # # # ####################################################### 9.1. Introduction of LOMETS2 LOMETS2 (Local Meta-Threading-Server) is meta-server approach to protein fold-recognition. It consists of 11 individual threading programs: CEthreader, mCEthreader, eCEthreader, MUSTER, PPA, dPPA, dPPA2, sPPA, wPPA, wdPPA, wMUSTER. The mCEthreader and eCEthreader are variances of CEthreader which includes different scoring functions. The last 7 programs are variances of MUSTER which includes different optimized energy terms. 9.2. How to install LOMETS2 program? When you unpack the DEMO-EM Suite, LOMETS2 programs are already installed. 9.3. How to run LOMETS2 program? The LOMETS2 main script is $pkgdir/I-TASSERmod/runLOMETS.pl. The running option of this program is similar to that in 'runI-TASSER.pl'. By running the program without argument, you can print all the running options. 9.4. How to cite LOMETS2? If you are using the LOMETS2 program, you can cite: Wei Zheng, Chengxin Zhang, Qiqige Wuyun, Robin Pearce, Yang Li, Yang Zhang. LOMETS2: improved meta-threading server for fold-recognition and structure-based function annotation for distant-homology proteins. Nucleic Acids Research, 47: W429-W436 (2019) S Wu, Y Zhang. LOMETS: A local meta-threading-server for protein structure prediction. Nucleic Acids Research, 35: 3375-3382 (2007). ####################################################### # # # 10. Installation and implementation of SPICKER # # # ####################################################### 10.1. Introduction of SPICKER SPICKER is a clustering algorithm to identify the near-native models from a pool of protein structure decoys. 10.2. How to install SPICKER program? When you unpack the DEMO-EM Suite, SPICKER program is already installed at $pkgdir/I-TASSERmod/spicker45d 10.3. How to run SPICKER program? To run SPICKER, you need to prepare following input files: 'rmsinp'---Mandatory, length of protein & piece for RMSD calculation; 'seq.dat'--Mandatory, sequence file, for output of PDB models. 'tra.in'---Mandatory, list of trajectory names used for clustering. In the first line of 'tra.in', there are 3 parameters: par1: number of decoy files par2: 1, default cutoff, best for decoys from template-based modeling; -1, cutoff based on variation, best for decoys from ab initio modeling. par3: 1, closc from all decoys; -1, closc clustered decoys From second lines are file names which contain coordinates of 3D structure decoys. All these files are mandatory. See attached 'rep1.tra1' for the format of decoys. 'CA'-------Optional, native structure, for comparison to native. Output files of SPICKER include: 'str.txt'-----list of structure in cluster; 'combo*.pdb'--PDB format of cluster centroids; 'closc*.pdb'--PDB format of structures closest to centroids; 'rst.dat'-----summary of clustering results; A detailed readme file can be found at http://zhanglab.dcmb.med.umich.edu/SPICKER/readme 10.4. How to cite SPICKER? If you are using the SPICKER program, you can cite: Y Zhang, J Skolnick, SPICKER: Approach to clustering protein structures for near-native model selection, Journal of Computational Chemistry, 25: 865-871 (2004). ####################################################### # # # 11. Installation and implementation of FASPR # # # ####################################################### 11.1. Introduction of FASPR FASPR is a method for structural modeling of protein side-chain conformations. Starting from a backbone structure, FASPR samples the side-chain rotamers for each amino acid from the Dunbrack 2010 rotamer library with the atomic interaction energies calculated using an optimized scoring function extended from EvoEF2, where side-chain packing search is performed using a deterministic searching algorithm combining self-energy checking, dead-end elimination theorems, and tree decomposition. 11.2. How to install FASPR program? When you unpack the DEMO-EM Suite, FASPR program is already installed at $pkgdir/Assbmod/bin/FASPR 11.3. How to run FASPR program? Usage: FASPR input.pdb output.pdb To run FASPR, you need to prepare following input files: 'input.pdb' Mandatory, input pdb file for side-chain packing. '-s' Optional, the sequence of the input.pdb Output files of FASPR include: 'output.pdb' output pdb file of the FASPR with side-chain packaged. A detailed readme file can be found in the FASPR package 11.4. How to cite FASPR? If you are using the FASPR program, you can cite: Xiaoqiang Huang, Robin Pearce, Yang Zhang. FASPR: an open-source tool for fast and accurate protein side-chain packing. Bioinformatics (2020) 36: 3758-3765. ####################################################### # # # 12. Installation and implementation of ModRefiner # # # ####################################################### 12.1. Introduction of ModRefiner ModRefiner is a standalone program for atomic-level protein structure construction and refinement. It includes two steps: (1) construct main-chain models from C-alpha trace; (2) build side-chain models and atomic-level structure refinement. 12.2. How to install ModRefiner program? When you unpack the DEMO-EM Suite, ModRefiner program is already installed at $pkgdir/I-TASSERmod/ModRefiner.pl 12.3. How to use ModRefiner program? ModRefiner supports following four options: a) add side-chain heavy atoms to main-chain model without refinement > ModRefiner.pl 1 ID MD IM ON b) build main-chain model from C-alpha trace model > ModRefiner.pl 2 ID MD IM RM ON c) build full-atomic model from main-chain model > ModRefiner.pl 3 ID MD IM RM ON d) build full-atomic model from C-alpha trace model > ModRefiner.pl 4 ID MD IM RM ON ID: the path of the DEMO-EM package, e.g. '/home/yourname/DEMO-EM-1.0' MD: directory which contains the initial model, e.g. '/home/yourname/DEMO-EM/5.0/example' IM: the initial model to be refined, e.g. 'mode1.pdb' RM: reference model that refined model is driven to, e.g. 'combo1.pdb'. Only CA trace is needed and the length can be not full which will make the refinement of the missing region flexible. If you don't have the reference model, use the name of IM instead. ON: the output name of the refined model, e.g. 'model1_ref.pdb' By running the program without argument, you can print a brief description of how to use the program. 12.4. How to cite ModRefiner? If you are using the ModRefiner program, you can cite: D Xu, Y Zhang. Improving the Physical Realism and Structural Accuracy of Protein Models by a Two-step Atomic-level Energy Minimization. Biophysical Journal, 101: 2525-2534 (2011) ####################################################### # # # 13. Installation and implementation of NWalign # # # ####################################################### 13.1. Introduction of NWalign NW-align is simple and robust alignment program for protein sequence-to-sequence alignments based on the standard Needleman-Wunsch dynamic programming algorithm. The mutation matrix is from BLOSUM62 with gap opening penalty=-11 and gap extension penalty=-1. 13.2. How to install NWalign program? When you unpack the DEMO-EM Suite, NWalign program is already installed at $pkgdir/bin/align. 13.3. How to use NWalign program? > align F1.fasta F2.fasta (align two sequences in fasta file) > align F1.pdb F2.pdb 1 (align two sequences in PDB file) > align F1.fasta F2.pdb 2 (align Sequence 1 in fasta and 2 in pdb) > align GKDGL EVADELVSE 3 (align sequences typed by keyboard) > align GKDGL F.fasta 4 (align Seq-1 by keyboard and 2 in fasta) > align GKDGL F.pdb 5 (align Seq-1 by keyboard and 2 in pdb) By running the program itself, it will print out the usage options of the program. 13.4. How to cite NWalign? There is no published paper associated with this program. If you are using the NWalign program, you can cite it as Y Zhang, http://zhanglab.dcmb.med.umich.edu/NW-align ####################################################### # # # 14. Installation and implementation of PSSpred # # # ####################################################### 14.1 Introduction of PSSpred PSSpred (Protein Secondary Structure PREDiction) is a simple neural network training algorithm for accurate protein secondary structure prediction. It first collects multiple sequence alignments using PSI-BLAST. Amino-acid frequency and log-odds data with Henikoff weights are then used to train secondary structure, separately, based on the Rumelhart error back propagation method. The final secondary structure prediction result is a combination of 7 neural network predictors from different profile data and parameters. 14.2 How to install PSSpred program? When you unpack the DEMO-EM Suite, NWalign program is already installed at $pkgdir/PSSpred 14.3 How to use PSSpred program? $pkgdir/PSSpred/mPSSpred.pl seq.txt $pkgdir $libdir Please note that 'seq.txt' should be in current directory and the script will generate two files 'seq.dat' and 'seq.dat.ss' in the current folder. Here, $pkgdir is the root path of DEMO-EM package. 14.4 How to cite PSSpred? If you are using the PSSpred program, you can cite: http://zhanglab.dcmb.med.umich.edu/PSSpred