Throughout this text, a menu-item will be denoted <item>. A cascaded menu-item by <item>-<sub-item>. A button will be denoted by [button-item]. {entry} denotes an entry field for a specific parameter; Italics denote a value entered by the user in an entry field, or the value of an option such as a radio-button or a check-button.
If procTool has been properly installed it can be started at the command line by typing:
procTool
The procTool interface-window will pop up (see Fig. 1).
Fig. 1: The procTool window.
On top is a menu-bar with <File> <Conversion> <Processing> and <Tools> . There are also several shortcut [buttons] on the righthand side of the menubar. Below the menu-bar is a general window area, that displays information about the current file and status and with entry fields for the directories, and project related parameters. Below that, 4 tabs (Conversion, Processing, Xeasy, and History) are located which each contain entry fields for various parameters as well as buttons. The tabs can be closed or opened by clicking on the open/close buttons on the right side. Finally, at the bottom a help bar is present. Moving the mouse over specific items in the procTool window, displays a short help text in this bar.
ProcTool uses text with red fonts for important information relating to the current status. Text with steel-blue fonts is used for giving information, text with green fonts indicates 'action' (usually on buttons). All other text is black. Entry fields can be activated by moving over the appropriate box and clicking the mouse. Sometimes, entry fields contain a cascade pulldown with options to choose from.
We start by filling out the general area, just below the menu-bar. ProcTool is best used by using three different subdirectories: one for the raw NMR data (e.g Varian), one for the processing scripts (PROC) and one for the processed data (DATA). It is advisable to choose one of the predefined names for these in the {NMR data}, {Data}, and {Scripts} entry fields. It is assumed that the directory with the raw NMR data exist (choose "." if it is the current directory). The advocated directory-tree is:
my_directory
Varian /Bruker
PROC
DATA
The PROC and DATA directories will be created atomatically when needed. A {Root name} (e.g. hsqc15N) should be specified. All processed data will start with this name and have different extensions depending upon the stage and way of processing. The dimensionality of the data can be selected by the radiobuttons [1D], [2D], [3D], or [4D]. We are now ready to save the data for the first time (see section 2).
A new start can be made by choosing <File>-<New> or by using the [New-File] icon-button in the menu bar.
The program can be quit by choosing <File>-<Quit> or by using the [Quit] icon-button in the menu bar.
Settings can be saved by selecting <File>-<Save>
or by using the [Save-File] icon-button in the menu bar. If the data
were not saved before, you will be prompted for a file name. The suggested
default name is {Root name}.pt.
If you want to save an existing file under a different name, choose <File>-<Save
as>. The extension .pt is recommended.
Settings can be restored from file by selecting <File>-<Open>
and clicking the appropriate file or by using the [Open-File] icon-button
in the menu bar. The procTool program can also be started by typing
the procTool command with the -file fileName argument. FileName
will then be immediatedly loaded, as if selected by <File>-<Open>.
Data can also be imported from pre-existing procTool files by choosing
<File>-<Import settings>-<..>. This mechanism
allows for pre-existing procTool files to serve as templates for specific
experiments. Upon importing the {Current directory} and {Current
file} parameters are not changed. This behavior is different from the
<File>-<Open> command discussed in section 2.2,
because this command will restore all settings, including the{Current
directory} and {Current file}parameters.
<File>-<Import settings>-<From user>
allows for selection of an aribitrary procTool file, typically one created
by the user on a prior occasion.
<File>-<Import settings>-<From default>
allows for selection of a procTool file located in the $TOOLS/PROCTOOL_1.5/Scripts
directory. This location is intented for default settings corresponding to
experiments that are used frequently.
<File>-<Import settings>-<From project>
allows for selection of a procTool file grouped within a specific project
(see also below: project management).
The conversion tab allows entry of the parameters needed for conversion to the nmrPipe format.
The different axis-related parameters fields can be cleared by choosing the appropriate option under the <Clear> menu item.
There is an easy conversion tool available that employs the settings contained in the NMR parameter files (acqus for Bruker or procpar for Varian files).
Choose <Conversion>-<Extract> or use the [Extract] icon-button in the menu bar. A window will pop-up. Note that if the spectrometer type is incorrect or the {NMR data} in the general area is set wrong, an error message will be generated.
Figure 2. The extraction window
Figure 2 shows an example of the extraction window for a Varian dataset. The varian parameters (i.e. sw, sw1, np, dfrq, etc) have been read from the procpar file and can be used to fill or calculate te appropriate values of procTool using tcl syntax (NB. A dollar sign precedes the variable in order to denote its value: $dfrq, $sw, $sw1).
Carrier setting (xCAR, yCAR, zCAR, or aCAR) of any axis can be switched off by choosing the off option. The x-axis calibration can be set relative to H2O and temperature by setting the temperature option. Calibration of the x-, y-, or a-axis is calculated relative to the {xCAR} value, using the gama-ratios of the appropriate nuclei. Note that in order for this calculation to be correct, it requires an exact setting of the {xOBS}, {yOBS}, etc fields, employing the appropriate expressions ($sfrq, $dfrq, etc in case of Varian, $sfo1, $sfo2, $sfo3, etc in case of Bruker).By pressing [Update all] the procTool parameters are updated according
to the expressions entered. An empty expression leaves the procTool parameter
unchanged. Pressing [Default] restores default expressions for the
different procTool parameters. This will in general only be approximately
correct, as every individual experiment requires different conversion parameters.
However, the current expressions are saved when saving the procTool file.
Thus, once set correctly the conversion expressions are restored upon reading
a procTool file.
Pressing [Dismiss] closes the window.
A highly similar window appears in case of Bruker files. The available parameters are now those of the bruker acqus file (i.e. l1, d1, in0, cnst1, ...etc) which are all listed in the acqus text window.
Choose <Conversion>-<Calibrate>. A window will
pop-up (cf. Fig. 3). Note that if the spectrometer type is incorrect
or the {NMR data} in the general area is set wrong, an error message
will be generated.
Figure 3. The calibration window
Figure 3 shows an example of the calibration window for a Varian dataset. The varian parameters (i.e. sw, sw1, np, dfrq, etc) have been read from the procpar file.
Calibration of any axis can be set as descriibed above in section 3.1. By pressing [Update] the procTool {xCAR}, {yCAR}, etc values are calculated and updated.
Pressing [Done] closes the window.
A highly similar window appears in case of Bruker files. The corresponding parameters are now those of the bruker acqus file (i.e. l1, d1, in0, cnst1, ...etc) which are all listed in the acqus text window.
This option allows for extraction of interleaved recorded 2D-experiments,
such as encountered for relaxation experiments. The experiment is treated
as a pseudo-3D experiment. Hence, in the conversion tab, the [Interleaved
z-axis] button is selected. The {Interleave size} parameter should
be set to the number of successive fids of one 2D experiment.
Relaxation experiments are usually recorded in an interleaved manner,
e.g. real-fid(t1=0,tau1), imaginary-fid(t1=0,tau1),
real-fid(t1=0,tau2), imaginary-fid(t1=0,tau2),
..., real-fid(t1=0,taun), imaginary-fid(t1=0,taun),
real-fid(t1=1,tau1), imaginary-fid(t1=1,tau1),
real-fid(t1=1,tau2), imaginary-fid(t1=1,tau2),
..., real-fid(t1=1,taun), imaginary-fid(t1=1,taun),
... etc. In short, real and imaginary fids are recorded in succession,
then tau is incremented, then t1.
In this example, the appropriate value for {Interleave size} would
be 2.
The x- and y-axis parameters are set as described above. The z-direction
parameters are set as follows:
{zN} total number of 2D planes
{zT} total number of 2D planes
{zMODE} real
{zSW} 1
{zCAR} 1
Depending on the specifics of the platforms used for recording tthe
data and processihng the data (e.g. SUN -> LINUX, SGI->LINUX,
SUN->SGI, LINUX->LINUX) a byte swap may be required. Set the appropriate
value of {ByteOrder}
A conversion script can be generated and viewed by the [Create & show] button. Pressing the [Execute] button creates a script and performs the actual conversion . The files in nmrPipe format will be stored in the sub-directory DATA (or whatever was choosen in the general tab for {Data}), and have the extension of the {out} entry-field (e.g. .fid).
Figure 4: The processing tab.
The processing tab (cf. Figure 4) can be used to generate and execute (UNIX) nmrPipe processing scripts. Depending the dimensionality of the experiment, there are up to four text-window areas (for the x-axis, y-axis, z-axis, and a-axis) where nmrPipe processing functions can be entered. Each processing function should be written on a single line. They can be entered by clicking the mouse at the desired position and typing the function name and parameters. Note that only the nmrPipe function name (e.g. FT or PS) with its appropriate parameters have to be typed in. procTool will automatically insert the "nmrPipe -fn" in the UNIX processing scripts.
Figure 5: The processing pull-down menu.
Each axis text-window has a pull-down menu (cf. Figure 5) which contains the most commonly used nmrPipe processing functions. Using these menus, the text will be inserted after the cursor.
Each of the individual windows can be cleared by choosing <Processing>-<Clear>-<axis> or by choosing the <clear> option in the processing pull-down menu.
After entering the processing function for two axes (e.g. x and y), an xy processing can be performed. A xy-processing script can be generated and viewed by the [Create & show] button in the "xy-script" section. Pressing the [Execute] button creates this script and performs the actual xy processing. The files in nmrPipe format will be read and written in the sub-directory DATA (or whatever was choosen in the general tab for {Data}), and have the extension of the {in} entry-field (e.g. .fid) and {out} entry-field (e.g. .xy.ft2). For 3D and 4D files, only the first xy plane is processed.
For 3D and 4D files, the first xz-plane can be processed using the {in} and {out} entry fields and [Create & show] and [Execute] buttons in the "xz plane script" section.
For 3D and 4D files, all xy-planes can be processed using the {in} and {out} entry fields and [Create & show] and [Execute] buttons in the "xy-planes script" section.
For 3D and 4D files, any arbitrary axis can be processed in the "any-axis script" section by choosing the appropriate [read and processes] radio button and using the {in} and {out} entry fields, and [Create & show] and [Execute] buttons . Data can be transposed to a different axis upon writing by choosing the appropriate [write] radio button
Figure 6: The process all popup window.
A complete processing script, including conversion if required and/or intermediate file removal, can be generated using the <Processing>-<Process all> menu item or by using the [Procall] icon-button in the menu bar. This will popup the process all window (cf. Figure 6) with selection buttons for the different options. The script can be generated and viewed by the [Create & show script] button. Pressing the [Execute] button creates a script and performs the processing. [Dimiss window] dismisses the window.
Figure 7: The projections popup window.
Projections of 3D and 4D files can be generated using the <Processing>-<Projections>
menu item. This will popup the projections window (cf. Figure 7) with buttons
for the different scripts. The script for xy or xz projections can be generated
and viewed by the [Create & show script] button. Pressing the
[Execute] button creates a script and performs the projection. Note
that for the projections to work, the labels (i.e. xLAB, yLAB, zLAB, and aLAB)
have to be unique.
[Dimiss window] dismisses the window.
Scripts can be displayed with <Processing>-<Show nmrPipe scripts>-<..>. A summary of nmrPipe processing functions can be displayed with <Processing>-<nmrPipe commands>. nmrDraw can be started with <Processing>-<nmrDraw>.
The Xeasy tab allows the creation and execution of a conversion script from nmrPipe to XEasy format. This option requires the external program p2x.
The history tab contains a logging of the procTool file and actions. The history can be cleared with <Tools>-<History>-<Clear> . Contents of the tab can be edited by the user; information can be appended. To add a time stamp use <Tools>-<History>-<Append timestamp>.
The <Tools> menu contains miscaleneous menu commands to view directories, remove files from the DATA directory, setup additional procTool parameters, view the source code, and show a summary etc.
The expression editor can be used to calculate any arbitrary expression.
Enter the expression and press return, the result will show next to the entry
field.
Proctool is designed to work together with two additional programs (i.e.
Samples and nmrManage) to achieve some simple form of project management.
The samples program is designed to collect and store some essential information
pertaining to the samples used to record the spectra. The appropriate sample
name can be entered in the {Sample} parameter field in the general
tab. At startup, procTool scans the Samples directory to generate a list
of options. You can, however, choose any abitrary name.
The samples program can be called from the procTools program by choosing
button [Tools]-<Samples> (on the far left in the menubar).
Look here for more details on the samples program.
The nmrManage program is designed to group sets of related procTool files
and sample files in one place in socalled projects, without actually moving
or copying data. Thus, it is an indirection mechanism (pointer mechamism).
The project name can be selected in the {Project} parameter field
in the general tab. At startup, procTool scans the projects directory to
generate a list of options. You can, however, choose any abitrary name. Using
the <File>-<Add to project> command, the current
procTool file can be added to the project. Note that this command will open
the nmrManage program.
The nmrManage program can also be called from the procTools program by
choosing button [Tools]-<nmrManage> (on the far left
in the menubar). Look here for more details
on the nmrManage program.
There is an internal help facility: button [Help]-<Commands> (on the far right in the menubar) gives an overview of the commands and the parameters, <Help>-<About> shows the about text, <Help>-<Version> shows the version history, and <Help>-<Tutorial> shows the tutorial through your web-browser.
Version 1.5.1: No bugs reported. Undoubtly this will change!
This program and its related software is provided "as is". The author makes no warranties, either express or implied, as to any matter whatsoever with respect to the software. In particular, any and all warranties of merchantability and fitness for any particular purpose are expressly excluded. In no event will the KUN, the Laboratory of Biophysical Chemistry, the NSRIM Center, or the author be liable for any loss of profits, any incidental, special, exemplary, or consequential damages of any nature whatsoever (including without limitation, loss of use or other commercial or research loss) arising out of or relating to the use or performance of the software.
This program may not be distributed without prior permission.
(C) Geerten W. Vuister 1999-2007
Laboratory of Biophysical Chemistry IMM, Radboud University Nijmegen, The Netherlands Email: g.vuister@science.ru.nl http://proteins.dyndns.org
Last update: 20 April 2007