How to write a ShakErr plugin

The main component of the plugin syntax is control statements which define plugin parameters and code. The general format is
{SHKRPLGN}:{KEY}:VALUE
The {SHKRPLGN} keyword specifies that the line contains control statement. Below is the list of keys and values that ShakErr will understand. The very first line of plugin file must be
{SHKRPLGN}:{TYPE}:REFINE|ANALYZE
This defines one of the two types of the plugins, refinement and analysis. GUI will not import the plugin file if this record is missing, not the first line or uses incorrect value (i.e. not REFINE|ANALYZE).
{SHKRPLGN}:{TITLE}:<title>
Plugin name.
{SHKRPLGN}:{DESCRIPTION}:<description>
Brief description of the plugin.
{SHKRPLGN}:{INPUT}:<type>;<Title>;<Default value>
If any INPUT records are present, the dialog will be generated to request parameters from user. At this time, only text controls are supported. Parameters will be passed to the analysis script (see code record below) as command-line parameters 2 and higher (the first parameter is always the name of the pdb-file).
{SHKRPLGN}:{CODE}:BEGIN|END
This statement specifies the boundaries of the script that will be executed when the plugin is invoked. Any script must use the model pdb file as the first argument. For refinement scripts, second argument shall be the reflection mtz-file, third the refined pdb-file. In addition, the fourth parameter will be passed to the script defining the shake id. If the refinement plugin is to be used on multi-processor system, this fourth parameter allows to generate unique names for interim files.

For analysis plugins, output (passed to stdout) should contain only numbers. There could be more than one though. In fact, you can have any combination of numbers in the output, and the plugin will produce the matching grid which will contain average values and errors.

Example

The example below calculates the buried surface area upon interaction. Two inputs are defined, the receptor chain and ligand chain. These will be used as $2 and $3 in the bash script that runs AREAIMOL to do the calculation. Notice that CCP4 setup scrpits are sourced. PDBSET is used to generate the two structures for AREAIMOL to compare, and its output is processed to generate a single line with signal number on it.

{SHKRPLGN}:{TYPE}:ANALYZE
{SHKRPLGN}:{TITLE}:ASA
{SHKRPLGN}:{DESCRIPTION}:Buried surface area calculation
{SHKRPLGN}:{INPUT}:text;Receptor chain;A
{SHKRPLGN}:{INPUT}:text;Ligand chain;G
{SHKRPLGN}:{CODE}:BEGIN
#!/usr/bin/env bash
. /sware/ccp4-6.1.1/setup-scripts/sh/ccp4.setup
pdbset xyzin $1 xyzout complex.pdb << eof > /dev/null
select chain $2 $3
eof
pdbset xyzin $1 xyzout protein.pdb << eof > /dev/null
select chain $2
eof
areaimol xyzin complex.pdb xyzin2 protein.pdb << eof | grep 'TOTAL AREA DIFFERENCE' | cut -d: -f 2
DIFFMODE COMPARE
MODE NOHOH
SMODE OFF
REPORT CONTACT YES RESAREA NO
PNTDEN 10
PROBE 1.4
END
eof
rm protein.pdb
rm complex.pdb
{SHKRPLGN}:{CODE}:END