This Guide explains the general use of the applications setup_target, setup_run, setup_list and setup_display. A guide to use Automated Setup specifically for CS-Rosetta structure calculation protocols (abrelax, rasrec and autoNOE) is found under these links:
Complete reference of the options for setup_target and other applications can be found here: Application Reference
The setup_target application allows you to generate and modify a fully functional Setup. This is a set of input files (fasta sequence, fragment libraries, restraint data files) and options (number of cycles, automatic mapping of side-chain restraints to centroid atoms, etc.) together with the choice of a structure calculation protocol (abrelax, rasrec, autoNOE).
The information stored in the Setup is sufficient to perform the Rosetta calculation without providing any further target or method specific information. The Setup is stored in a automatically generated directory whose content should not be touched by the user (but which can be moved, copied or rsynced to a remote cluster location in its entirety). The user can control the path for storing Setup directly using -target_dir or he just determines a path of a repository with (-target_prefix) and the Setup will be stored under the name of the target (given by -target). If the option -target_prefix is not given at the cmd-line, the path to the repository is given by the environment variable CS3_BENCH_TARGETLIB, which is set by the initialization script of the csrosetta3/com/init (default is $HOME/cs_targetlib).
The following table shows all situations that can arise:
| options on cmd-line | path of Setup directory |
|---|---|
| -target t000_ | $CS3_BENCH_TARGETLIB/t000_ |
| -target t000_ -target_prefix $HOME/repository | $HOME/repository/t000_ |
| -target t000_ -target_dir input_files | ./input_files |
The CS-Rosetta methods abrelax, rasrec and autoNOE, require at least a fragment library and fasta file.
Hence, the minimal command line to create a Setup is
setup_target -method <method> -target <target> -frags <frag3.gz> <frag9.gz> -fasta <fasta>,
where the placeholders in <,> are replaced by appropriate values. This also means that given a repository a Setup is uniquely defined by the triple (<target>,<method>,<label>).
As an example, we create a Setup using the following cmd-line:
setup_target.py -method abrelax -target 1ubi -label standard -frags frags* -fasta 1ubi.fasta
This will create the setup Setup( 1ubi | abrelax_standard ), which is the short identifier of a Setup. The detailed view of a Setup will look similar to this:
============================================================
STORED: method options as new setup 'abrelax_standard'...
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
Method: abrelax
Choosen Options:
automatic_centroid_mapping True
cycle_factor 10.0
relax False
cst_map_mode simple
nstruct 10000
fasta fragments/1ubi.fasta
frags fragments/frags3.gz fragments/frags9.gz
------------------------------------------------------------
Which shows us the chosen options, automatic_centroid_mapping, cycle_factor, cst_map_mode, relax and nstruct and the loaded fiels, 1ubi.fasta, frags3.gz and frags9.gz. Note, that the files are stored in sub-directory 'fragments'. These sub-directories are specified by the Method plugin (Developer Guide) and cannot be changed by the user.
Calling setup_target with a combination of <method> <target> <label> that selects a Setup that already exists in the repository (or in the path given by -target_dir) will cause loading of the existing Setup before the other cmdline options of setup_target will be interpreted. If further command-line options are given (e.g., -rdc <peg.rdc>) then these will be added to the existing Setup. How exactly this happens depends on the type of option:
| type of option | behavior in modify-mode |
|---|---|
| single value | overwrite |
| multi value | add value(s) |
If a user wants to change values of a multi value option he first has to remove all values of this option (using -remove) and then re-add those values that should stay unchanged. Currently no mechanism exists to remove single values from a multi-value option. Removing a single value option will cause reverting this option to its default setting.
The application setup_target always copies all files into appropriate locations within the Setup directory. If the user attempts to overwrite a file that is already loaded to the Setup (with the same filename)
the application will issue a warning and exit (using CRC checksums). This is to protect from unaware overwriting of content in Setup. One should not lightly override this safety guard, since files (for instance the fragment libraries) are shared between multiple Setups of the same target. If you indeed globally want to change a file (because for instance you found a bug) you can override, in most cases, however, it might be more appropriate to generate a new Setup (with appropriate label) and a new filename for the input file.
You can generate a new Setup with the identifier (<target>,<method>,<label>) also as a copy of (<target>,<old_method>,<old_label>) where one or both of the new identifiers <method> <label> are different from the old ones <old_method> <old_label>. This is simply done by invoking one of
setup_target -target <target> -method <method> [-label <label>] -transfer_method <old_method>,
setup_target -target <target> -method <method> [-label <label>] -transfer_label <old_label>,
setup_target -target <target> -method <method> [-label <label>] -transfer_method <old_method> -transfer_label <old_label>
Omitting the option -label will default to "standard" for <label> and omitting the option -transfer_label means that the source Setup is (<target>,<old_method>,<label>). Accordingly, omitting the option -transfer_method but specifying -transfer_label leads to the copy operation (<target>,<method>,<old_label>)==>(<target>,<method>,<label>).
Following our example from above we use setup_target -target 1ubi together with the options in the first column of the following table to generate copies of our first Setup "Setup( 1ubi | abrelax_standard )":
| options on cmd-line | source Setup | target Setup |
|---|---|---|
| -method abrelax -transfer_label standard -label with_rdc -rdc med1.rdc | Setup( 1ubi | abrelax_standard ) | Setup( 1ubi | abrelax_with_rdc ) |
| -method abrelax -transfer_label with_rdc -remove rdc | Setup( 1ubi | abrelax_with_rdc ) | Setup( 1ubi | abrelax_standard ) |
| -method rasrec -transfer_method abrelax | Setup( 1ubi | abrelax_standard ) | Setup( 1ubi | rasrec_standard ) |
| -method rasrec -transfer_method abrelax -label with_rdc | Setup( 1ubi | abrelax_with_rdc ) | Setup( 1ubi | rasrec_with_rdc ) |
| -method rasrec -transfer_method abrelax -transfer_label with_rdc -remove rdc | Setup( 1ubi | abrelax_with_rdc ) | Setup( 1ubi | rasrec_standard ) |
Note that changing the labels of a Setup has no functional effect (e.g., the label 'with_rdc' is just a name and does not cause any RDC restraints being loaded. Using label-names that reflect the nature of the Setup is soley the users responsibility. Here we have used the modification command -remove (Section 1.4) to keep the name of a respective Setup reflect its content.
The transfer mechanism from 1.5 can be combined with modification of Setup as described in 1.4. Simply use the -transfer_method and -transfer_label options while also giving new values for method-specific options. The effect is that first the transfer causes a new Setup to be generated and second the new Setup is modified as in 1.4. Note, however, that a transfer always succeeds also if the Setup with the target identifier exists already, which will be simply overwritten.
The applications setup_list and setup_display allow to browse Setups in the repository. The application setup_display operates on a single target but offers more detail, whereas setup_list can show a list of all existing Setups in the repository with all Targets, Labels, and Methods.
The application setup_run is used to start a structure calculation. It generates the appropriate file-structure and flag-files in a location (path) of your choice. Additionally the user can specify platform dependent information regarding the executables to be used, the path to the Rosetta database, and the type of jobscript to generate for the queuing system. The type of Rosetta executables is specified with -extras one of default/static/mpi, -comp one of icc/gcc and with -platform linux, macos, or windows. From this the setup_run application will build the extensions such as .mpi.linuxgccrelease or static.linuxiccrelease. The type of job-script is chosen with -job <system>. Available choices are job-scripts for which templates with the name platform.<system>.job are available in the path csrosetta3/flag_library/jobtemplates/. Customized job-templates, following this naming convention, can easily be added to this directory and will show up as additional choices for option -job of the setup_run application. See also the Developer Guide for more information how to customize job-templates.