Restraint conversion: the qconvert procedure

Only the file format ("layout") is converted, not the atom nomenclature. The latter is handled by the AQUA programs, see Names.

The 'qconvert' script consists of a series of operations:

step 1:

step 2:

step 3:

step 4:

Recognized file types are DISGEO, X-PLOR, BIOSYM and DISMAN/DIANA format.

Data types are NOE, HB (hydrogen bond), SS (disulphide), DIS (generic distance) and TOR (torsion angle). Remaining data have type OTH. The script will also recognize the model section of "MR" files, the PDB-styled restraint file format (see 'qhelp mr').

Output files have the same root name (i.e. name minus extension) as the input restraints file, unless the -r option specifies a different root name. The output file name extensions are as follows:

    .raw_noe,  .noe    (un)converted NOE restraints
    .raw_hb,   .hb     (un)converted hydrogen bond restraints
    .raw_ss,   .ss     (un)converted disulphide restraints
    .raw_dis,  .dis    (un)converted generic distance restraints
    .raw_tor,  .tor    (un)converted torsion angle restraints
    .raw               unconverted remaining data
    .raw_text          remaining text lines
    .raw_mdl           first model section (MR files only)

WHAT IF RESTRAINT CONVERSION FAILS

The script does not recognize the file type
Use the -t option to specify the file type, e.g. for a DIANA file:
```
        qconvert  -t  4  file
```
See the qconvert manual page. For unknown file types see below.
The script assigns data types incorrectly
Erroneous assignment of data types puts restraint data into the wrong 'raw' data files, and possibly gives conversion errors (e.g. if torsion angle and distance restraint data are mixed). Assignments are done on the basis of identifiers (DISGEO, BIOSYM) and comment texts, and by checking atom names (HB and SS types) and restraint format (TOR type). Textual and formatting information can be ambiguous, resulting in errors.
There are various ways to correct this:
a) Use the -h option of 'qconvert' to modify the interpretation scheme.
Example:
```
        qconvert  -h  1  file
```
b) Modify the restraints file: organize the restraints into blocks of corresponding type, and precede every block by simple comments such as "# NOE restraints", "# hydrogen bonds" etc. For the rest try to avoid the use of strings such as "NOE", "torsion", "H-bond" on other comment lines and on data lines.
c) The simplest solution might be to insert one or more unique identifiers into the restraints file, and turn off data type interpretation by using the -i option of 'qconvert'. The identifiers can be:
The identifiers may be preceded by one or more comment delimiters (#, ! or *) and spaces. Nothing else should appear on the line.
Note that lines between END_OF_DATA and START_OF.... are skipped, unless they appear to be comment lines, i.e. start with #, ! or *.
Example:
```
        qconvert  -i  file
```
The script should not split the data according to type
You may use solution 2c) described above, i.e. insert one identifier START_OF.... at the beginning of the file, and invoke as 'qconvert -i'.
Alternatively, use the -simple option to skip interpretation of data types and treat all lines as NOE type.
Example:
```
        qconvert  -simple  file
```
The conversion step fails for one or more restraints
You may want to modify the original restraints file. Alternatively, you may modify the unconverted 'raw' file(s) involved, and invoke 'qconvert' once again using the -nosplit option. With this option the file type is still determined automatically (step 1), but modification and splitting are skipped (steps 2 and 3) and the script converts any 'raw' files having the proper root name which it can find.
Example:
```
        first do:   qconvert  file   [result: conversion errors]
        then:       modify 'raw' file(s) by hand
        finally:    qconvert  -nosplit  file
```
It is possible that the conversion script cannot handle your particular realization of a recognized file format. Especially the XPLOR format is more flexible than the Aqua conversion script allows. In that case, adapt the conversion script(s) '$AQUASCRIPTSDIR/conv...'. Alternatively, you may treat the file type as if it is unknown by using the -t option:
```
        qconvert  -t  99  file
```
and proceed as is described in the next section.
The file type is unknown
Unknown formats can still be converted using 'qconvert'. Two conversion scripts, one for distance restraints and one for torsion angle restraints, have to be provided. The names of these scripts should be 'convUSERdistrestr' and 'convUSERtorsrestr' and they should be stored in the working directory.
Note: If you want to use scripts stored in a different directory, then edit the file '$AQUASCRIPTSDIR/qconvr'. Find the line
```
        set script = convUSER$RTYP
```
and insert the proper path.
These conversion scripts should read the input file, and produce a file according to the format decribed in '$AQUADOCDIR/restraint_format.txt' (see Restraint format). The scripts are expected to be written in nawk. The scripts may use the variables TITLE and DATA, which through -v options are set to have the values of, respectively, the title string and the data type. See '$AQUASCRIPTSDIR' for standard conversion scripts which can be copied and used as templates.
Note: If you want to change the invocation of the user scripts (e.g. if you program in another language) you have to modify '$AQUASCRIPTSDIR/qconvr'. Also make sure that '$AQUASCRIPTSDIR/qconvert' calls your new version of 'qconvr'.
IMPORTANT: in addition to defining conversion scripts you have to provide a library with atom name information. This library maps atom names of your file format onto standard Aqua atom names. Set the restraint type of the output file (see Restraint format) in your conversion script to "local". See 'qhelp names' and 'qhelp library' for more details.
FINALLY: If you make or improve conversion scripts I would like to receive a copy! If you agree to make them available, they can be included in a future release. Of course you will be properly acknowledged. Thanks!