SPSCAN User Manual


alphabetic index / database / internals / methods

Contents

Introduction
Peak picking and integration of peaks
Assignment
Menue interface
Macro commands
Mouse usage and single-key commands
Tools in detail
Tutorial: HOW TO ...
Project database
Data exchange with XEASY
License

Introduction

SPSCAN supports semi-automatic assignment of NMR spectra of biological macromolecules. The program is written in C++ for UNIX computers with X-Window interface. All NMR-specific code is written from scratch. The graphical interface is based on "GRAFIX" by Wolfgang Köhler.

SPSCAN is designed to be used together with the NMR assignment program XEASY and the structure calculation program DYANA. It reads spectra in XEASY-16bit, NMRPipe and Bruker format, other spectra have to be transformed into one of these formats.

The program was written as a semi-automatic approach with the philosophy:

SPSCAN is recommended for the following tasks:

The complete program documentation includes the following files:
spscan.html (this file)
User manual: gives you an overview about the range of applications and how to use the program. (recomended to read before you start)
spscan.xeasy.html
Data exchange between SPSCAN and XEASY
spscan.project.html
Commands to construct a database of spectra and peaklists, find sequentiall connectivities between fragments and map the fragments to the sequence. (under construction)
spscan.index.html
Alphabetic index with links to all other files.
spscan.methods.html
spscan.pj_methods.html
spscan.d_methods.html
The most important classes and methods of the program. Mainly as a guide to the source code - for those who wnat to add their own routines. Some linke from the manual into these files give details about the implementation of some commands.
spscan.int.html
Installation, hardware requirements, compiler problems, some details of data organization.
macro/*.spm
Example macros, usually with comments.
lib/*.lib
libraries
User documentation has a yellow background (like this); development documentation with lite green background is not relevant for most users.

In addition to the HTML documentation you may read a manuscript that describes the basic features of SPSCAN. It was never published, unfortunately, but is included in this documentation as a PDF file.


Peak Picking and Integration of Peaks

SPSCAN considers peaks as a product of gaussian or lorenzian lineshapes in all dimensions of the spectrum. Thus, a peak is described by position (ppm) and linewidth (lw=twice the distance between peak center and half maximum intensity) in all dimensions, and by the volume (vol), which is the volume of the peak of idealized shape that gives the least squared deviation to the true intensity in the spectrum.

This integration procedure compares favourably with the integration of a rectangular area or ellipsoid around the peak. It has

In addition to ppm[d], lw[d] and vol, the peak is described by a "quality parameter" (qual), which reflects the deviation of the peak from an ideal gaussian or lorenzian shape after deconvolution of all overlapping peaks. The quality parameter can also consider the relative size of the peak, i.e. the volume compared with an expected volume. A threshold for the quality parameter is used to separate local maxima into "peaks" and "noise".

2D Spectra

SPSCAN starts with a 2D peaklist and linewidths. Linewidths are taken either from peaklist entries "#LW float float .." for each peak individually, or from "#LINEWIDTH dim float" entries in the header of the peaklist. If no data is given, the expected linewidth parameter scpa->Lw_e is used as a starting value. The volume of the peaks are iteratively fitted to the spectrum, minimizing the least square deviation between spectrum and the theoretical peak shape. The program can work with a fixed line shape and just determine the volume, or it can adapt linewidth, peak position, or both.

The procedure how to integrate a 2D spectrum or how to integrate a series of 2D spectra is described in the tutorial.

3D Spectra

The basic philosophy behind treatment of three-dimensional spectra is that you always have a two-dimensional spectrum with all the peaks that are expected in the 2D projection of the 3D spectrum. The differences between the 2D and 3D spectrum must be small enough so that the position of the peak in the 2D spectrum is a good starting point to search for peaks in the 3D spectrum. If resolution and signal/noise are high, a 2D projection of the 3D spectrum can be used to pick or adapt the peaks in two dimensions. Preferably, 2D spectra with high resolution in the indirect dimension should be recorded together with the 3D spectra under identical conditions.
Consider that during experiments with powerful decoupling or TOCSY sequences the temperature in the sample can be several K above the value shown on the console. Such differences disturb automatic (and also interactive) assignment of NOESY/TOCSY spectra significantly. Avoid such unnecessary problems and use some suitable signal as an internal temperature sensor.

The following strategy is used to identify peaks in a 3D spectrum: SPSCAN starts with a 2D peaklist and linewidths, as above. For each 2D peak a vector in the third dimension is calculated, which contains the scalar product of the simulated 2D lineshape and the real intensity of the plane. This one-dimensional intensity profile is used to search for peaks in the third dimension. Search for peaks is an iterative process, and in each iteration

This peak picking process is controlled by a large number of parameters. Most of those can be left on their default values. However, the calculation should take into account some knowledge about the spectrum, like the expected number of peaks per strip, sign of peaks, expected linewidth in 3rd dimension, etc. Changes of parameters have an immediate effect on the calculation. A detailed description how to do peak integration of a 3D spectrum is given in the tutorial.

Reduced dimensionality experiments

Two strategies are currently supported to evaluate 4D -> 3D reduced dimensionality experiments:
  1. The spectra are peak-picked in SPSCAN like normal 3D spectra. Then the peak lists are processed without using the the spectrum itself. Central peaks and peak pairs have to be in separate lists, or they must have different sign to distinguish them. These routines are called by "reduced dim: get pairs"/"separate lists" or "center- pair+".
    The procedure can also find peak pairs, when no central peak is detected.
  2. Central peaks are determined, and put int a peaklist. Strips are symmetrized around the central peak(s) before peak pairs are determined. The procedure is described in detail below, for the example of COHNCA-spectra (Szyperski et al. (1995) J. Magn. Resonance B108, 197-203). This procedure may be preferred, if a complete list of central peaks is available.

All peaks have to be assigned in the two "base" dimensions of the strips.
If you start with an unassigned reference list, renumber it, and assign it automatically with residue "SRD". Do that before you pick 3D peaks in the spectra. You can read these assignments in XEASY if you set "*new_atom_numbers: true" and load a sequence of "SRD" residues.)
If your peaklist is already assigned in XEASY, but not to SRD residues, the program will fail to assign the "CA+HA ..." resonances correctly, because these atoms do not exist. It will, however, assign the CA, HA, ... resonances correctly.

Automatic assignment schemes are available for several types of reduced dimensionality experiments. The user does not have to assigne each peak individually. Peaklists can be written for several combinations of dimensions.

If you want to compare the projected dimension of a spectrum with a "normal" dimension of another spectrum using XEASY, you can create a "pseudo-spectrum", which has one plane for each central peak of the reduced dimensionality spectrum. These planes are shifted with respect to each other and calibrated in such a way that they appear like normal spectra, exccept that they are quasi-symmetric to the offset.

see also: internals documentation; parameters for reduced dimensionality; menu "red-dim"

Integration parameters

Click "integrate"/"parameters" to pop up a window to change parameters. Parameter changes take immediate effect and can be made during a calculation.

The following parameters are important for integration and should be adapted to the respective spectrum:

linewidth (float scpa->Lw_min[ ], Lw_e[ ], Lw_max[ ])
The linewidth of a peak is limited to the range between Lw_min and Lw_max. If no linewidth is given, Lw_e is used as a starting value, if no linewidth can be read from the peaklist.
With the small button left to the linewidth field you can swithch linewidth adjustment on and off. For indirect dimensions with very poor resolution, switch adjustmant off and leave the linewidth at the value of the 2D or set it to 3/4 of the ppm-difference between planes.
number of peaks (int scpa->Nr_sc_exp, Nr_sc_max, Nr_sc_min)
expected, maximum, minimum number of peaks in a scan
pick mode: (int scpa->Search_pnb)
positive, negative, all, fold +/-, fold -/+, fold all
"fold +/-" means that peaks which are unfolded in both loaded dimensions (or folded an even number of times) are picked only if positive, while peaks that are folded an uneaven number of times (sum of folds in both dimensions) are only picked if negative. "fold -/+" is the other way round.
"fold all" picks all peaks and then does the following: First, peaks folded inone of the two base dimensions are unfolded, and their volume is inverted. Then peaks that still have a negative volume are cpnsidered to be folded - according to their position in the upper or lower half of the strip they are folded over the nearest border. There is no possibility currently implemented to fold peaks in scan-dimension according to their volume.
peak shape: gauss, lorenz
as indicated.
iterations (int scpa->Nr_runs)
If the linewidth and position of the strips is ok, 2 - 3 iterations are sufficient to deconvolute overlapping peaks. If linewidth and position has to be adapted to the spectrum, 5 - 7 iterations are appropriate.
Maximum change [in ppm] (float scpa->Max_d_ppm[3], bool scpa->Limit_d_ppm)
A limit for the distance (in ppm), by which peaks can be shifted during adaptation to the spectrum.
If the "apply" button is pressed, this feature is activated (scpa->Limit_d_ppm=true). The ppm values of the peaks are restricted to range of value before the first iteration +/- scpa->Max_d_ppm[d]. If several integrations/searches are performed without reloading the peaklist, the peak positions can be shiftedby this amount each time when a new integration command is invoked.
In Max_d_ppm[i] i is the dimension of the peaklist, i=2 is the scan_dimension (In contrast to Lw_e ... ).
Minimum relative distance (float scpa->Min_dist, bool scpa->Limit_dist)
If the "apply" button is pressed (scpa->Limit_dist=true), peaks cannot degenerate. The square of the distance between two overlapping peaks cannot become smaller than scpa->Min_dist times its initial value. The useful range for Min_dist is about 0.3 ... 0.8, default is 0.5

See filter to limit ppm changes in internals documenation.

A complete list of integration parameters is given in the "internals" documentation.

For 2 D Integration only the following parameters are used:

Parameters to evaluate reduced dimensionality experiments

There is a separate parameter window for parameters to evaluate reduced dimensionality experiments. It is called from "integrate"/"parameters" - "red dim p."
float F_dc_freq, F_dc_exmt
The factors between the ppm scales of 4th and 3rd dimension. F_dc_freq is the factor resulting from the frequency of the nuclei involved: it can be set with the "nuclei" menu below. F_dc_exmt is the additional factor introduced in the experiment by application of different time steps in direct and projected dimension (in the lierature usually 1/F_dc_exmt is given).
float Off_dc
Offset for ppm of 4th dimension, i.e. the ppm value corresponding to degenerate symmetric peaks
float Ri_ppm_min, Ri_ppm_max
The range in which peaks in the 4th dimension may be found, in ppm calibration of the projected dimension. This range influences which of the two possible values are written to a peaklist, and it restricts the search range in search1::search_pairs.
Again, a complete list of parameters is given in the "internals" documentation.


Assignment

see also: assignment manager

Introduction to SPSCAN assignment handling

SPSCAN uses assignment numbers for resonances. The translation between assignment numbers and fragment number, fragment type and atom name is done by an "assignment_manager". Different peaklists can have different assignment_manager, if that is necessary. Assignment modes can be changed with "assign"/"reassign"- as a consequence the assignment numbers in the peaklist change.

SPSCAN supports following assignment modes:

A line
#ASSIGN_MODE 5 <proton list> <sequence list> <residue name>
in the peak list header tells SPSCAN to use the correct assignment mode. If you load a peaklist that has no such line, use "assign"/"get assignment".

Inames

Dimensions of a spectrum or peaklist are associated with an identifier of up to 7 characters, called an "iname". The spectra are labelled by the user, peaklists take the inames from the respective dimensions of the spectrum. The following rules are recommended for naming spectra dimensions:

Residue mapping

Fragment numbers can be exchanged with each other and with the real residue number in the sequence. It is important to realise that mapping is done in a different way than in XEASY. SPSCAN tries to resolve the atom name and the fragment number from the old atom numbers. It looks in the mapping list whether the fragment number has to be changed. Then it determines the new atom number from the new fragment number, the fragment type and the atom name. If this is not possible, it tries to map the atom name. It replaces the atom number in the peaklist.

Thus, if a fragment is mapped in SPSCAN, the assignment numbers in the peaklists are changed - in contrast to XEASY, where the fragment numbers in the proton list are changed. There are two options: you can map fragments for a single peaklist with peaklist::reassign, or you can map all peaklists that are registered in the project file.

Change of atom names

When a residue SS is mapped on THR or VAL, the atom QB or HB2 must be changed to HB. Such changes are defined in the file atom.lib as
#FORMAT atom_name_mapping
ALL   QB    THR   HB
ALL   CG    THR   CG2
ALL   QG    THR   QG2
ALL   QG    LEU   HG
ALL   QB    VAL   HB
ALL   HA    GLY   QA
...
which is read into a class atom_map_list. Other information can be in the same library, after another #FORMAT ... line.
If the old atom name (2nd column) does not exist in the new assignment, and the 1st and 3rd column match old and new residue name, the new atom name (4th column) is used. "ALL" matches any residue name. Mappings for specific residues must be listed before "ALL" mappings to take effect. (The first matching entry is valid, a match with ALL has the same priority as an exact match.)

Automatic assignment schemes

The most primitive assignment scheme is to assign peaks in a peaklist using their "id" number as the fragment number and the iname of the respective dimension of the peaklist as the atom name. This is done with the routines assign_to_inames_2D and assign_name_all(iname[2], ...), which are called from "Integration: assign"/"... to inames". This scheme is useful to create initial pseudo-residues, e.g. from HN/N cosy peaks. It is analogous to "ar" in XEASY.

Other primitive automatic assignment routines are available for many types of experiments. They are based on the idea, that for each strip the assignment in two dimensions is known, and it is possible to determine the assignment in the 3rd dimension from volumes and positions of the peaks in the strip.

For all assignment commands: first, provide the peaks in the list with a unique fragment number using "assign"/"id from assignment".

All assignment routines can be called as macro commands - sc_assign for "normal" peaklists and rd_assign for lists of pairs resulting from reduced dimensionality experiments. Some of the routines can also be called from the "assign" menu of the interface. Details of implementation are described in the methods section.


Menue interface

Integration:
"integrate" - load spectrum and parameters, start integration
"peaklist" - load and save peaklist
"statistic" - display peaklist data
"modify pl" - edit peaks and organisation of peaklist
"assign" - modify assignments
"display spec" - show and edit strips from current spectrum
"write spectrum" - save to spectral file
general:
"quit" - exit button
"break" - interrupt long calculations
"status?" - inquire what the program is doing
"macro" - run a macro
reduced dim:
"get pairs" - evaluate lists of peak pairs
"HN_CO/CA" - processing of projected HNN<CO,CA> spectrum
"write red-dim" - write peaklists from projected spectra
special:
"tools" - determination of coupling constants, linewith comparison, ...
"check" - several checks for consistence of a single peaklists
"project" - combine information from all spectra of a sample. The submenues lead to modules with their own interface.

Most of the routines that are build into SPSCAN can be started from pulldown menus. When you click on one of the buttons with a triangle on the right you get a submenu with the routines. If you use the left button, the menu is temporary, with the middle button you get permanent submenus (to remove, press right button on the main menu).

All of these routines can also be started from a macro (although for some of them it does not make much sense). Some routines, which are not so frequently used, can only be called as macro commands

Integration:

All commands in the "Integration" group access the same parameter set (scpa), spectrum (scpa->subspec) and peaklist (scpa->pl). The peaklist has to be saved to a file before changes can take effect in other parts of the program.

"integrate"

"parameters"
Edit integration parameters: Opens a popup window to change scan parameters scpa.

write
read
save and load the parameters as *.scpa text file.
check
incompatible parameters are reset. e.g if Lw_max is smaller than Lw_min
defaults
reset parameters to default values. The command evaluates the inames of the spectral dimension, and if you want to use default parameters you have to use this command after loading a spectrum in a different permutation or with different nuclei in some of the dimensions.
red dim p.
Another popup window is opened for parameters of reduced dimensionality experiments.
done
closes the window. Even if the window is open, however, changes of the parameters take immediate effect; for example it is possible to change parameters during a "do search" run.

"spectrum"
Load a spectrum: Opens a popup window.
new spectrum
Lets you select a new *.3D.param file (XEASY spectrum format)
load mini
loads parameters and creates scpa->subspec, but loads only a single point from the spectrum
load
loads the spectrum in the size indicated in the second and third column.
In the first column of edit windows you can set the new dimension into which the corresponding dimension of the spectrum is loaded. The lower fields are changed in such a way that the permutation is consistent. In the other fields the borders can be given in points or ppm.

"3D"
Start search / integration of 3D spectrum. What is done depends on the parameters set. If you did not load a spectrum and peaklist before, you will be asked for.
"2D"
Start integration of 2D spectrum, or of a plane in a pseudo-3D spectrum. Whether ppm and lw are adapted, must be set in the parameters.
"clean"
Deletes spectrum and peaklist for integration.

"peaklist"

"read new list"
"add list"
read peaklist scpa->pl as a chained list, i.e. several 3D peaks are connected with one "strip" position. If peaks that belong to one strip are not immediately together in the list, strips must be build with "modify_pl" - "combine + reference".
The peaklist should be loaded after loading the spectrum - then it is automatically brought into the right permutation.
"write list standard"
Writes scpa->pl into a file. The behaviour depends on whether a 2D or 3D integration was performed. The format is defined in g_form.
"write reference list"
Only one peak per strip is written into a file.

Display peaklist data - "statistic"

Display diagrams with the distribution of several parameters of the peaks. These statistics are used to optimize integration and peak picking parameters. The display is done by GNUPLOT, which has to be installed as "gnuplot".
"volume", "log volume", "lw 1", ...
A number of variables in the peaklist scpa->pl can be displayed either as a x/y scatter plot or as a distribution (bar plot). If a new variable is selected, the old plot window is automatically deleted.
"set range"
opens interactive window to change borders of the plot
"clear"
removes the gnuplot window

Edit peaks and organisation of peaklist - "modify pl"

"assign diagonale"
peaks that are less than half their linewidth away from the diagonale in scan_dim, are assigned in scan_dim same as the matching peak_dim value. Calls void peaklist2::assign_diagonale(void)
"fix + assign diag."
In addition to the above, sets ppm in scan_dim exactly to diagonale position.
"renumber"
strip-numbers are set to 1,2,...
"check linewidth"
A warning is printed for linewidths outside Lw_min .. Lw_max. Zero linewidths are set to Lw_e.
"adapt linewidth"
A linewidth outside Lw_min .. Lw_max is set to the relevant border. Zero linewidth is set to Lw_e (not to Lw_min). see also: macro command "spm normalize_lw"
"get linewidth from other list"
Get linewidth information for peaks that have linewidth == zero from another peak list. If a linewidth different from zero exists, it is not changed.
(The routine calls void peaklist2::get_linewidth(...). It compares assignment numbers, so both lists must be assigned in the same way. If that is not the case, create a temporary list with "reassign". If you modify a SPSCAN peaklist in XEASY, keep the unmodified peaklist that has #LW ... entries and use it as a reference for the modified list - which has lost linewidth entries after passage through XEASY. Remaining zero linewidths should be set with"check lw".)
"combine + reference"
Entries with identical assignment in both peak_dimensions are combined, the 3D peaks are put into one strip. If peaks are too far apart, a warning is printed, and the strips are not combined. The command should always be executed when XEASY peaklists were loaded.
"clear all 3D peaks"
All peaks are deleted, but the entries in the peaklist that define the strip positions are retained.
"color"
Define the color entry of peaks in the list (for display in XEASY; SPSCAN does not use the color information). For example, newly picked peaks and peaks below a quality threshold can be color coded.
"remove some peaks"
Delete peaks above or below a certain volume, quality, or color.
"status"
Display the name of the current peaklist in scpa->pl, number of strips and number of 3D peaks.

Change assignment - "assign"

"check dimensions"
gives the possibility to change the inames (dimension identifier names) after the peaklist has been loaded. This is neccessary to set the name of the indirect dimension in reduced dimensionality experiments. It may also be neccessary before an "assign to iname" command.
"2 peak_dim to id+iname"
calls scpa->pl->assign_to_inames_2D. To generate initial assignment to fragments after renumbering the list in assignment mode 1 or 4. They also work in mode 5, if the strip ID is identical with the fragment number (set with "id from assignment", below).
"scan_dim to iname"
calls scpa->pl->assign_to_inames_scp. Tries to resolve the fragment number from the assignment in the two base dimensions of hte peak, and assigns the 3rd dimension to an atom with the name of the 3rd dimension of the peaklist and this fragment number.
"pairs to iname 3/4"
calls scpa->rdpa->px_pl->assign_to_inames_scp. Same as above for the list of pairs, it needs a fourth iname to assign the reduced dimension.
"get assignment"
Associates the peaklist with a new assignment manager. Assignment numbers in the peaklist are not changed. This command has the same effect as changing or inserting the "#ASSIGN_MODE ..." line in the peaklist before loading. Calls scpa->pl->assign()
"reassign"
Command to change assignment numbers of peaklists. The peaklist must currently have a valid assignment, i.e. it must be possible to resolve the fragment number and atom name for each resonance.
You can do two things with this command: (i - map residue numbers? NO) change assignment numbers in a peaklist in such a way that the same assignment - e.g. "5 HB2" is encoded with assignment numbers from a different proton list. (ii - map residue numbers? YES) map reidue numbers, e.g. set all "SRD 309" assignments to "ALA 54". In this case you have to set "do atom mapping? YES" to set "HB2" of "SRD" to "QB" in "ALA", for example. See differences in assignment between SPSCAN and XEASY
"id from assignment"
Set the strip ID-number to the residue number of the resonances that define the strip. If the residue number for the two dimensions is different, print a warning. If the residue cannot be determined, set ID to a unique value (user has to enter starting value). The command is also used to set initial fragment numbers to completely unassigned pealists.
see also: macro assignment commands for particular types of experiments.

"display spec"

"3D tool"
A tool to select strips with particular properties (low quality of peaks, stong overlap, high number of peaks, ...) and to display these strips in all 3 orientations, modify peaks interactively and selectively repeat integration.
This tool always uses the spectrum and peaklist that has been loaded with "integrate"-"spectrum" and "peaklist"-"read new list".
"adjust colors"
Pops up a window with sliders to change colors of the spectrum. (analogeus to XEASY "cw")
The color changes made here are global to the program. Other ways to change the colors of the spectral displays are
any spectrum
you can select any spectrum and display it. In a 3D spectrum the first dimension is x, the third is y, and the second dimension is displayed as the indirect dimension (for XEASY strip compatibility).

"write spectrum"

"as current"
saves the current state of the loaded spectrum to a file in XEASY 16-bit format. The command is used to transform NMRPipe and Bruker spectra.
"peaks only"
saves a spectrum of the current size, which contains only the peak shapes of the peaks currently in scpa->pl. (Only made for debugging)
"residual 3D"
A spectrum is written, from which the peaks in scpa->pl are substracted. Useful to compare real and idealized peakshape and to find peaks that have not been picked.
... full size
spectrum is saved in its original size, not in the size that is loaded by SPSCAN.
... 2D
analogous commands for 2D spectra / 2D integration. Pseudo-3D's cannot be saved.
SPSCAN loads only truncated spectra for integration, if there are no peaks near the border. Thus a 2048 x 1024 spectrum may become 1673 x 977. Such spectra are not well divided into submatrices, and may be slow to work with. To get a defined part of the spectrum, load it with "spectrum" - "load" after giving the wanted borders. The write routine will then take these borders for writing.

general:

"quit"

exit SPSCAN.

"break"

Processing of macro files, and some of the long routines like peak picking/integration can be interrupted with this button.

"status?"

Some routines with long calculation times give information about their current status. This information is printed to the shell.

"macro"

Load and run a macro file. (see macro commands)

reduced dim:

These three menues contain commands to evaluate 4D -> 3D projectes experiments (reduced dimensionality spectra). The two dimensions which define the position of the strip are "normal" dimensions, and the two projected dimensions give raise to peak pairs with or without central peak along the strip.

The commands use additional parameters (scpa->rdpa) and a number of additional peaklists are used.

"get pairs"

center- pair+
assumes that negative peaks in the list are central peaks, positive peaks should become part of a peak pair. Calls run_pairs_B.
separate lists
requires two separate lists, one with central peaks and one with peak pairs. Calls run_pairs_A.
scan spectrum
This command uses the spectrum that is loaded for the "integration:" commands above to search for peak pairs. It needs a complete list of central peaks. Calls rd_param::run_pairs_C.

"HN_CO/CA"

A collection of commands to process a projected HNN<CO,CA> spectrum and create a pseudospectrum HNNCA. see also the tutorial for use of these routines.
get central peaks
Loads "COHNCA-.scpa" and starts the search for central peaks with main_t_window::do_search1.
make pseudo-spectrum
spio->make_pseudo3D()
Creates a new spectrum, which consists only of individual strips. The command produces the striplist rdpa->stl, which is neccessary to adapt other lists to this pseudospectrum.
assign as Cp
rdpa->stl->assign_Cp. The command can only assign to "Cp" if the pseudoresidue is SRD or SSP. Otherwise it assigns to "C".
write striplist
scpa->rdpa->stl->write_pl_xe_lw3(). The list "stl" defines the relation between assignment in the two peak_dim's and corresponding ppm in the pseudo-spectrum. It can be used in XEASY to create strips for the pseudospectrum.
get paired peaks
Searches for positive peak pairs in the spectrum. The list with central peaks must be in scpa->pl. Loads "COHNCA+.scpa" and runs scpa->rdpa->run_pairs_C.
assign as CAp and CA
scpa->rdpa->px_pl->assign_CA_CAp_1().
propose n/n+1
scpa->pl->propose_COHNCA_cn(). If scpa->pl doesn't exist, it is created from scpa->rdpa->px_pl. When the command is executed after "get paired peaks", a list for the "normal" spectrum is written. If a pseudo-CA peaklist has been loaded before, a sorted list for the pseudo-spectrum is written.
write pseudo peaklist
From the current list of pairs a peaklist is produced which contains only the entry with higher ppm. The peaklist is adapted to the pseudospectrum:
read striplist
Reads peaklist to rdpa->stl. This list provides the relation between assignment in the two peak_dim's and corresponding ppm in the pseudo-spectrum. It is overwritten by the creation of a new pseudo-spectrum.

"write red-dim"

Write peaklist with peak pairs in different formats.
"4D"
write a standard 4D peaklist
central peaks (3D)
3D peaklist is written with the two dimensions of the strip and the center of the pairs in 3rd dimension.
difference (3D)
3D peaklist is written with the two dimensions of the strip and the projected dimension as 3rd dimension. ppm in the projected dimension is calculated from parameters rd_param::Off_dc, F_dcv_freq and F_dc_exmt.
Only peaks are written to the list that are between rd_param::Ri_ppm_min and Ri_ppm_max. Calls rd_param::projected_124D
central + diff (2D)
2D peaklist is written with the center of the pair and the projected dimension as above.
write pairs as 3 peaks
Whenever a pair is found, central peak and both zero and double quantum peak of the pair are written into one list with their original position. The peaks are assigned to resonances "CA+HA", "CA-HA" ... as used by XEASY (assign fragments as SRD). This list can be edited and transformed into a normal peaklist with XEASY. It cannot be sensibly interpreted by SPSCAN.
unused central peaks
Write peaklist with central peaks that were not included into one of the pairs. Side effect: changes rdpa->c_pl
unused paired peaks
Write peaklist with peaks from the "paired peaks list" that were not included into one of the pairs. Side effect: changes scpa->pl

"tools"

NOAH lineshape comparison
Start NOAH tool.(lineshape extraction for assignment possibilities which NOAH has regarded as ambigeous)
ecosy tool
Start ecosy tool.
save lists
Save the result of work with ECOSY tool or NOAH tool. If the assignment of a peak was defined on the basis of lineshape, this information is put to the peaklist. Consequently, the peaklist must be saved after operation. This peaklist is different from scpa->pl, the peaklist used for integration!
resume operation
If the tool still exists, and was unmapped for some reason, work continues at the current position. If no tool exists, a new one is constructed and the peak number of the *.ass list has to be entered, where the check should continue (the number of the current peak is displayed)
delete tool
If the peaklist is saved the tool can be deleted to free the occupied memory.

Several checks on peaklists - "check"

This menue covers some simple tests whether the assignments in a peaklist are self-consistent.
valid assignment numbers
Checks whether all assignment numbers in the peaklist can be resolved from the proton list. If the peaklist is not in #ASSIGN_MODE 5, you will be prompted for the sequence- and proton list.
pal_list::check_assignments_exist in peaklist3.cc
valid protons
Checks whether all proton names in the proton list do exist in the library gives as "*residue_library:". If unexisting protons do not appear in the peaklist, they are deleted. If they appear in the peaklist it is tried to map them.
proton_list::check_protons_exist in assign.cc
ppm deviations
This is a lineshape comparison for peaks that are assigned to the same resonance, but picked at slightly different positions. Just try - Comments for improvement wanted!
pseudo atoms
The proton list is checked for pseudoatoms. The library defined in "*residue_library:" is used to resolve the protons that are replaced by the pseudoatom. The peaklist is checked whether peaks are assigned to the pseudoatom and the respective protons. Considering this information a check for obvious errors is made. A proposal for handling the case is offered for interactive decision, if the program cannot decide what to do.
The program assumes that pseudoatoms can represent 2 or 3 protons. In case of 3 protons it is further assumed, that these are always degenerate, and only the pseudoatom may be assigned.
The proposal of the program, what to do if assignments are made both to the pseudoatom and to one or more of the represented protons depends on the chemical shift determined from the peaklist. Thus the routine works properly only if for each proton and pseudoproton the chemical shift range is narrow.
check_tool::pseudoatoms in check.cc
lineshapes
not implemented yet
save peaklist
The peaklist of this check_tool is independent of other peaklists and has to be saved here!
save protonlist
Saves the proton list if it has been changed.
delete checktool
deletes peaklist, proton list, and frees the occupied memory

Organize data in a project - "project"

see Project Database.
If you do not find this menu, start "spscan -d". As many functions in this menu are under development, the menu is normally disabled in some releases.
edit
opens a command menu to add/remove peaklists and spectra, check sequence, proton list, and assignment numbers, print the spectra and lists that are involved in the project, ...
organize db
opens a command menu to find sequential connections between fragments, display the relevant spectral details and edit these connections, map connected fragments to the sequence, ...
simulate peaklists
produce simulated peaklists with the ppm values from the atom list
peaklist manipulations
opens a command menu to compare two peaklists. The peaklists can be merged, differences between the peaklists can be found, and assignments can be taken over between the lists.

Macro commands

  • Menu replacement (action)
  • Input / Outpt (read, write)
  • Assignment schemes (sc_assign, rd_assign)
  • Transformation of UXNMR or NMRPipe spectra (access)
  • Miscellaneous (spm, combine , spec , 1D ) Macro files are processed by the class command_handler. Macro commands can be read from a file with extension *.spm or they can be entered interactively on the command line. (commands that occupy several lines like "combine peaklists" cannot be entered interactively)

    Syntax:
    command variable_argument <or another variable argument> [optional argument]

    Menu replacement

    action <menu> <submenu> ...

    The command "action" can be used to replace interactive menue commands. It calls all menus with submenus, i.e. those with a small triangle on the right side. It has at least two arguments: the menu and submenu names. Names which include spaces have to be set in "..." or '...' Further arguments have to be given to feed dialoge boxes and confirm boxes, or to provide filenames. The command does not check, whether menu and submenu names are valid. If execution of the command does not produce an output, you cannot see whether something has been done (if menu names are misspelled, the command is echoed as normal, and ignored).

    SPSCAN is designed as an interactive program. The "action" command follows the same route as the interactive commands selected from the pulldown menues. As a consequence, the arguments for some macro commands depend on the context of the command in the macro program or on particular features of the lists used. Be careful!

    Valid arguments to confirm boxes are y, Y, n or N. All other arguments are ignored, the box pops up and the argument counter is not incremented. If you try to write over an existing file, the confirm box tries to use the next argument in the macro line to find out whether or not to overwrite the file.

    Dialog boxes have two arguments with a special meaning:

    • "?" leads to the popup of the dialog box
    • "." sets the default arguments for the current and all following entries in the current dialog box (not in the complete macro line) and supresses popup.
    All other arguments to dialog boxes are exactly what you would type into the fields, separated by white space. If the number of arguments is too small, the dialog box pops up with the previous arguments already set.

    To load or save a file the filename must be given as an argument, either with the full path or relative to the default directory for the file type. The extention must always be given. Loading or saving a file does not change the working directory.

  • Input and Output

    read scpa|rdpa|spec|pj_peaks filename
    Read the specified file. see command_handler::read. pj_peaks reads a peaklist to pj->current_pl.
    write pj_peaks filename
    writes pj->current_pl to the named file

    Assignment schemes

    sc_assign
    Applies some assignment schemes to scpa->pl that use the id of the strip, and the position and volume of the peaks in one strip to define the assignments in the 3rd dimension. The first parameter is whether only peaks that are unassigned in the 3rd dimension will be assigned (n) or whether all peaks are assigned in the 3rd dimension (y).
    clear atomname [atomname ...]
    Set all atoms to unassigned which are assigned to atomname in scan dimension (regardless of which residue).
    prot y|n [tolerance]
    assign the peaks in scan dimension to intraresidual atoms that are known from the proton list.
    CA_CAp y|n
    assign the peak with the larger absolute volume as CA, the one with the next biggest volume as CAp.
    CA_CB y|n
    assigns two peaks as CA and CB on the basis of their ppm position.
    CAp_CBp y|n
    assigns two peaks as CAp and CBp on the basis of their ppm position. If one of the peaks is allready assigned to CA or CB and "n" is set, these two commands assign the other peak to the missing C atom.
    CA+CB- y|n
    Assignment of CBCANH experiment on the basis of volume. CA=large positive, CAp=small positive, CB=large negative, and CBp=small negative
    CAp+CBp- y|n
    The same as before but CBCA(CO)NH, now the bigger peaks are CAp and CBp.
    toc y|n .
    Simple assignment scheme for N-edited TOCSY experiment. Linewidths in 3rd dimension are necessary.
    rd_assign
    Applies some assignment schemes to scpa->rdpa->px_pl that use the id of the strip, and the position and volume of the pairs in the strip to define the assignments in the 3rd and 4th (projected) dimension. The first parameter is whether only pairs that are unassigned in the 3rd/4th dimension will be assigned (n) or whether all pairs will be assigned (y).
    cohnca y|n
    Assignment of COHNCA-experiment pairs: central=Cp, projected: big=CA, small=CAp.
    CA_CB y|n
    Assignment of HA&HB/CA&CB-NHN experiment
    CAp_CBp y|n
    Assignment of HA&HB/CA&CB(CO)NHN experiment.
    to_center y|n
    Assignment of projected dimension as derived from assignment of central peak.

    Transformation of UXNMR or NMRPipe spectra

    access
    creates a header to access spectral files in UXNMR or NMRPipe format. The spectral data themselves are not transformed. This has the consequence that after creation of the access header calibration of the spectrum for SPSCAN and for the other program becomes independent. If the data are changed without changing the format (i.e. phase correction, baseline correction, ...) the changes are automatically taken over by SPSCAN. Only if you change the format of the data (number of points, transpose, ... you have to repeat "access" before you can read the files.

    uxnmr [filesname1 [...]]
    If filesname1 is given, it is the UXNMR 2rr or 3rrr file. procs, proc2s, and proc3s files must be in the same directory as filesname1, otherwise the parameters have to be entered by hand.
    pipe [filesname1 [...]]
    filesname1 is a text file that was created with "showhdr -verb pipefile >filesname1". The file filesname1 can be deleted when the access header has been written.
    pipe interactive
    Do not use a header file. Enter all parameters to access the data file interactively (normally not recommended).
    trafo
    a series of transformation commands that use sconv.spio/sconv.subspec, i.e. they do not interfer with the spectrum that is used for integration.

    'access uxnmr' and 'access pipe' create files "*.param" of a few hundred bytes that allow SPSCAN to read NMRPipe or Bruker spectral data files. XEASY cannot read these files, but you can read the full spectrum into SPSCAN and write it out as a XEASY 16-bit spectrum. You can use the macro pipe2xeasy.spm, or you can adapt pipe2xeasy_a.spm to get an automatic conversion. The result is a short *.3D.param file and a *.3D.16 file of half the size of the original data file.

    read [filename [full]]
    read a spectrum to sconv.spio/sconv.subspec. If you do not use "full" you have to use the "load" button (not "load mini") to get the spectrum. Changes that you make in the size of the file will be considered, i.e. you can use this command also to extract a subspectrum from a larger spectrum.
    scale [factor | . ]
    Scale spectrum sconv.subspec by factor. If factor is not given, a factor 2n is determined for which about 50% of the pixels are between -100 and +100.
    perm [std] | [w1 w2 w3]
    Allows to change the permutation between dimensions of the loaded spectrum and "w" dimensions. "access perm std" sets the order of "w" dimensions equal to the loaded spectrum. "access perm" pops up a window to enter the order of dimensions. Consider that you have to give the dimensions as "0 1 2" and not "1 2 3"!
    write [filename]
    Write spectrum as in xeasy 16bit format.
    write_xeasy [filename]
    similar to the interface command "write spectrum" / "as current", but spectrum is written in inverse permutation as usual in xeasy.
    You also can make a conversion interactively by loading a (UXNMR or NMRPipe) spectrum with "integrate"/"spectrum" and write it out in xeasy 16bit format with "write spectrum"/"as current". In this case you do not have the possibility to scale or change the order of dimensions.

    (The description above is valid for version <= 1.0.60; earlier versions have "access" commands read, scale, perm, write, write_xeasy that use tt->spio).

    Potential problems
    If you have problems to read NMRPipe files correctly, try to replace "Transposed" with "Not Transposed" or vice verse in the header.

    Miscellaneous

    spm
    assign <mode> <default residue> <proton list> <sequence list>
    roesy_volume_correction_1 <carrier frequency [ppm]> <spin lock field strength [Hz]> <spectrometer frequency [MHz]>
    jump_return_correction <carrier frequency [ppm]> <delay between jump-return pulses [s]> <length of 90 degree pulses [s]> <spectrometer frequency [MHz]>
    average_linewidth <mode> <original_peaklist> [<new_peaklist.peaks>]
    Averages linewidth (mode&1) and/or position (mode&2) of all peaks with the same assignment number in the same dimension. Modifies an existing original_peaklist file.
    normalize_lw set linewidth at or bejond the border of the allowed range to expected linewidth.
    handle_overlap (uses scpa->pl)
    take_assignments (uses a local copy of the peaklist, which is loaded temporarily.)
    deviations
    Determine devations between two assigned peaklists. To find out parameters, use interactively.
    combine
    A collection of commands that extract information from several lists with corresponding peaks, for example relaxation experiments or H/D exchange experiments. Routines are in command.cc. All commands use a global command_peaklists * cl.
    You can easily restrict the range of peaks that are used on the source-code level with "user_filter()", which is defined in command.cc. You can modify combine_custom or use combine_standard as a target to define your own routines.
    The peaks in the different lists must be assigned in the same way; the #ASSIGN information in all but the first list is ignored. The order of peaks in the list need not be the same. Peaks that are not in the first list are ignored, i.e. the program searches for a match for all peaks that it finds in the first list.

    peaklists<number> ...
    number filenames follow on the next lines as 'add filename time [<factor>])
    load peaklists
    target
    defines which parameter is used. Valid arguments are "volume", "F1", "F2", "F3". If no "combine target ..." command is given, volume is used by default.
    Only for "standard", "nolifi", and "plot_graf" output formats the target can be different from "volume". Other output formats ignore the target or produce nonsense if the target is not "volume".
    assign < mode > < default residue > < proton list > < sequence list >
    It is always assumed that all peaklist have the same assignment scheme. If you dont use this command, the assignment scheme of the first peaklist loaded is used. If this peaklist was written by SPSCAN, things are ok. With this command you set the assignment scheme that is used to interpret the assignment numbers in the peaklists independent of the assignment of the first peaklist, for example if this list was produced with xeasy. The assignment stored with the individual lists is not changed.
    nolifi < output filename >
    writes peaklists in "nolifi" input format. nolifi is a small fortran program for the non-linear fit of data with constant weight to a function y(x)=A+B*exp(-C*x)
    Unassigned peaks are not written to the file.
    fitrel < output filename > [< relative error in percent >]
    writes peaklists in "fitrel" or "varrel" input format. These programs consider different weights for each peak, depending on the error given for the volume. The absolute error for fitrel is calculated from volume and quality, assuming that the quality value in the peaklist results from a 2D integration and represents the relative error in percent. If < relative error > is given, the same relative error is used for all peaks.
    standard < output filename >
    writes peaklists in a text format format which can be read by a number of standard programs, e.g EXCEL.
    custom < output filename >
    see source code comments.
    plot_graf < output filename > < xmin > < xmax >
    Write peak volume vs. time for display with the program "graf", 6 plots per page. graf (written by P. Guentert) is a program that creates postscript plots from data and functions, similar to gnuplot.
    coupling_1 < output filename > < Tau > [< reliability range factor stdf(=1.0) >]
    This command allows to calculate 3J(13C-31P) coupling constants from the ratio of peak volumes with and without 31P decoupling in a constant-time 13C-1H COSY experiment as described by Legault et al., FEBS Lett. 362 (95) 156.
    To use the command, the peaklist from the decoupled experiment has to be loaded to the first position and the peaklist from the non-decoupled experiment to the second position of the list of peaklists. Use coupl.spm as a template macro. coupling_1 is a specialized command: First, all peaks assigned in 13C-dimension as "C1'" are considered, and the average and standard deviation of the volume ratios is calculated (these should not depend on 31P decoupling). Second, peaks assigned as "C2'" or "C4'" are considered. The volume ratio is corrected by the average ratio for C1' and used to calculate the coupling constants. The standard deviation of C1' times stdf is used to estimate the range of reliability.
    (void command_peaklists::combine_coupling_1(char * output, float tau, float stdf) in combine.cc, no further documentation)
    make_lol < output filename > [< distance(=3.0) > ]
    All peaks in the first peaklist are translated into lower distance constraints.
    (The command command_peaklists::combine_make_lol in combine.cc can be used as a target to construct distance constraints from several lists)
    kill
    Delete the list of peaklists to free memory. When you call another 'combine peaklists', the old lists are automatically deleted.
    During the execution of macro files, interruption by interface commands (e.g. to change parameters) may produce undefined behavior. Dialoge boxes may try to use arguments of the current macro command as input. The only interface functions that produce a defined behavior during macro execution are "break", "status" and "statistics".

    Mouse usage and single-key commands

    buttons and editable fields
    in all cursor windows
    in all spectral windows
    in lineshape windows
    check tool
    NOAH tool
    ecosy_tool

    General

    The interface is based on "grafix", written by Wolfgang Koehler. It may be useful to read how to handle the interface.

    Mouse and Keyboard Commands in all cursor windows

    mouse movement
    updates the right column in the group window
    left mouse button press
    mouse movement, left button pressed
    move the cursor
    middle mouse button press
    select nearest object
    mouse movement, middle button pressed
    move selected object
    You do not see the object moving. Only when you release the middle mouse button the object disappears at the old and reappears at the new position. The final position of the objects is different for peaks and large objects. Peaks are moved to the position of the cursor. Boxes are moved by the distance the cursor is moved.
    right mouse button press - draw - release
    span a box between the two mouse positions. The box is automatically selected.
    a, A
    If a peak is selected, assign the peak interactively. (calls draw_peak::assign_interactive()
    g, G
    display of "chemical shift" group window on / off
    CTRL-g
    assign crosshairs interactively
    CTRL_G
    modify crosshair names
    j, J
    merge two entries of the chemical shift group (e.g. correlate Hnoe and Htoc)
    CTRL o / O
    clear / set follow_ch. follow_ch=true lets the spectral window follow the crosshair, i.e. when the crosshair leaves the displayed area, the window is centered as above. (not tested for 3/4D)
    Q, q
    query. Print some information about selected draw_object.
    R, r
    redraw.
    S, s
    set current coordinates as default coordinates. You can always zoom back to the default coordinates with CTRL-Z.
    z / Z
    zoom in / zoom out. works on a selected box (the box you just defined is always selected)
    Zoom in does exactly what you would expect: enlage the interiour of the box to fill the whole window. Zoom out reverses this process: the contents of the whole window is put into the box, and the surrounding is shown in addition.
    The box is drawn with the right mouse button before the "z" command.
    CTRL-Z / SHIFT+CTRL-Z
    tries to return to the original size (if this was defined) / zooms to the full size, if this can be determined.
    CTRL C
    Unmap the window (in some cases the main window of the window)
    [DEL]
    Try to delete selected draw_object (delete only if kill_notify returns true).
    Right, Left
    go with selection foreward/backward through draw_objects.
    -
    Unselect draw object.

    Mouse and Keyboard Commands in all spectral windows (spec_window)

    In addition to the above, the following actions are performed:
    I / i
    activate / inactivate automatic adaptation of indirect dimensions. The plane will be adapted automatically to the crosshair position.
    l, L
    edit contour levels.
    If you do not select "use only two colors", the color of the contours is exactly the color that a point of this level would have in an intensity plot, i.e. it can be changed with CTRL + cursor keys.
    o, O
    center the window around the crosshair position (the crosshair be set in an other window; even if it is invisible in the target window the new area will be displayed)
    p, P
    select plane interactively
    CTRL P
    adapt plane to crosshair position now (leave "indirect" status unchanged).
    r, R
    restore plane that was defined with the last "show" command.
    CTRL R
    re_read. Necessary to make visible the changes described below
    1, 2, 3, 4
    use of intensity or countour plot mode. 1 uses always intensity mode; 4 uses always contour mode; 2 and 3 detect the mode according to the size a spectral point in pixels of the screen: overview plots are shown in the faster intensity mode, zoomed details are shown as contours. Default is 2.
    The change takes effect only after the next re-read (CTRL-R).
    CTRL Up / Down
    Increase / decrease base of logarithm for color determination (shift)
    CTRL Right / Left
    Increase / decrease factor for intensity --> color conversion (scale)
    Page_Up / Page_Down
    show next / prevoius plane
    Home / End
    show first (zero) / last plane
    F1 (only in spectral windows that are not part of a tool)
    pop up a table to select commands for peaklist display etc.

    Mouse and Keyboard Commands in lineshape windows (ls_window)

    In addition to the actions in all cursor windows, the following actions are performed:
    m / M
    show real intensity ratio of the lineshapes / norm lineshapes to same maximum size (=default)
    Mouse movement with middle button pressed will scale the selected lineshape in y-dimension, but not move it in x dimension.

    Special Commands

    check_tool, spectral window:
    l, L
    Replace the lineshape that gave rise to this display, by the lineshape at the current cursor position. If the lineshape is no longer displayed, the command is ignored.

    check_tool, lineshape window:
    b, B
    back, show previous resonance
    c, C
    continue, show next resonance
    d, D
    display peak, show spectrum around the selected lineshape. (if no lineshape is selected, the command is ignored)

    ECOSY tool
    see below
    NOAH tool
    see below
    The default action is always to foreward the event to the parent class.

    Tools in detail

    ECOSY Tool
    NOAH Tool
    INFIT Tool
    3D Tool
    Assignment Tool

    3D Tool

    3D Tool displays strips from the current spectrum, that is loaded for integration. The tool is called with "display spec"/"3D tool". It shows and changes the current integration peaklist.

    Handling of folded peaks is different in 3D tool compared with the other spectral displays. You should not try to change folding via the assignment window.

    INFIT Tool

    HOW TO USE
    Keys and mouse usage
    INFIT is a text-oriented C-program which is delivered with the XEASY package. It compares the envelope of time domain data for back-calculated experimental and simulated signals (T. Szyperski, P. GŁntert, G. Otting, and K. WŁthrich, J. Magn. Reson. 99 (1992) 552-560 ). The signal is simulated assuming Fourier transformation with a window-function: f(t) = sin ((180-phi)*(t/taq)+phi) where taq = aquisition time; phi = 180/SSB on X32.
    INFIT reads *.slc files (that can be stored from the xeasy slice window) and calculates coupling constants from in-pase splittings of the signals. The result of each individual fit is written to a text file in graf format, that can be transformed to postscript with GRAF and displayed or printed. The procedure is a bit clumpsy.
    "INFIT Tool" uses some core routines of the INFIT program and provides a very convinient interface to the program: Infit tool of SPSCAN has the same problems to optimize the linewidth as INFIT has.
    The current implemetation of INFIT-tool works only with 2D spectra (I don't think it makes much sense to extract in-phase splittings from 3D spectra)

    HOW TO USE

    1. "tools" - "infit tool"
    2. Load a peaklist. The peaklist must have dimension ID's (#INAME ...) and it must be assigned (#ASISGN_MODE ...)
      It is important that the dimension ID's match EXACTLY those of the spectrum, otherwise the program constantly pops up stupid confim boxes.
    3. chose the orientation of the peaklist (usually the acquisistion dimension as x)
    4. Load the spectrum in which you want to measure the splittings.
    5. Press "n" (name). A dialogue box will pop up. You have to enter
      • The atom for which you want to determine the splitting, e.g. "HN 15"
      • If you want to get the splitting from a particular crosspeak, the assignment of this crosspeak in w1, e.g. "HA 14". The crosspeak must exist in the peaklist. If you do not enter a valid crosspeak, or if the crosspeak does not exist, all crosspeaks of the peaklist will be displayed, one after the other. You move foreward and backward with the spacebar and SHIFT-space.
      • If not the first atom is HN and the coupling partner HA of the same residue, you have to give the coupling partner.
    6. The part of the spectrum that contains your selected peak should appear in the left third of the window. The splitting of the peak should be visible in x-dimension. You can check the dimensions with "g". The vertical cursor should have the color of your best-resolved (usually acquisition) dimension. Re-size the window with "z" or SHIFT-"z" to a convinient scale. The scale will will be preserved when you move to other peaks.
      Draw a box with the right mouse button around the signal.
    7. press "a" (add). All slices along the x-axis that are in the box will be added and displayed in the middle window. If there are already slices displayed there, the new slices will be added to the old ones. The new range is the biggest common range.
    8. press "c" (calculate). The right window will display the sum of squared deviations between simulated and experimental peak shape as a function of the coupling constant. The central window will display both the experimental and simulated shape.
    9. the error range of the coupling constant is the range where the sum of squared deviations is smaller than twice the optimum value. To shift this range, put the cursor on the respective position and press "<" or ">".
    10. press "w" (write) to write the coupling constant to the list and continue with (4), or press "x"="w"+"n".
    11. continue with (5)
    12. when you are through with your resonances, select "tools" - "save lists" from the SPSCAN main menue and save the coupling constants to a *.cco file.
      INFIT tool writes the same format as ECOSY tool: only the borders of the reliable range are used by DYANA; the last number with the optimum coupling constant is currently not used by other programs.

    Keys and mouse usage

    a
    add shape
    The box in the left window is used to extract a lineshape, which is put to the middle window.
    c
    calculate
    All lineshapes in the middle window are added, and the INFIT routine is started to calculate an in-phase splitting. Intermediate result are printed to the shell, and the result is shown in the right window.
    n
    next resonance
    Select a new resonance. By default this is HN of the following residue.
    w
    write coupling
    The values (lower and upper limit, optimum value) for the current resonance are written to the internal list of coupling constants.
    x
    x=w+n. Write coupling and go to the next resonance
    [space bar]
    next peak
    The area around the next peak in the peaklist is shown in the right window.
    <, [
    shift lower limit to the cursor position in the right window
    >, ]
    shift upper limit to the cursor position in the right window
    =, |
    shift optimum value to the cursor position in the right window. (Currently the optimum value is written to the *.cco list as the 8th column, but it is not used by any of the structure calculation programs, so you can safely ignore this value)
    In addition you have all other keys and mouse buttons available as in general cursor windows. For example you can select individual lineshapes with the middle mouse button and delete them with [DELETE] button.

    ECOSY Tool

    HOW TO USE
    layout
    Sign of coupling
    Coupling partners
    lineshape extraction
    3D spectra
    Keys and mouse usage

    HOW TO USE
    1. make sure that your spectrum and your peaklist have dimension ID's (and that these ID's match)
    2. your peaklist must be assigned, the program must know that, i.e. it must have a "#ASSIGN_MODE ..." line. If not, add by hand or get assignment.
    3. Load the spectrum (load mini)
    4. "tools" - "ecosy tool"
    5. select the orientation of the spectrum
    6. The tool window should pop up, and the first peak be displayed. Select the area for extraction of the lineshape by pressing the right mouse button in one corner of the area, and releasing it in the opposite corner. Repeat the procedure for the other area.
    7. If necessary - edit the relative position of the lineshapes, or the range, as described below. Press "x" to write the coupling constant and go on to the next peak.
    8. If all peaks in the peak list have been considered, the program prints ">>> ready". Save the coupling list with "tools" - "save lists". (you can abort saving the peaklist if you did not make changes in it).
    9. Remove the tool window and free the memory with "tools" - "delete tool".
    Layout
    Three lines in the upper left show the two resonances that define the current peak, and the passive coupling partner. These data can be edited with "e".
    At the end of the first of these lines is a short status information, which shows the mode of operation. The mode can be edited with "OoAaDdHh-" as described below.
    The three lines in the middle show the two resonances of the selected coupling, the coupling as determined from the relative position of the two lineshapes with the correct sign, and the relative scaling factor used for the two lineshapes.

    Below are three windows. A spectral window that shows the peak, a lineshape window with the two lineshapes, and a window with the quality of the fit between the lineshapes as a function of the relative position. The windows in the center and in the right appear only after you have selected two areas for lineshape extraction.

    In the spectral window you can select areas, and use them for extraction of the "fixed" lineshape - "1", and the "variable" lineshape - "2". Areas can be shifted - as any other object - with the middle mouse button. After shifting you have to press "1" or "2", respectively, to re-extract the lineshape and start a new fit. If you want to restore the automatically determined position and range after an erroneous manual change, select one of the areas with the middle mouse button (without moving) and press "1" or "2", respectively.

    In the central window you can shift and resize the "variable" lineshape with the mouse while holding down the middle mouse button. You cannot select or move anything else. With "j" you set a border of the allowed range for the coupling constant to the current relative position.
    You can also take the borders in the right window with the middle mouse button and drag them to another place. (You can catch these lines only at their ends) You can also put the cursor (with the left mouse button) to another minimum and press "s" outside the right window to adapt the lineshape to this relative position.

    Sign of coupling
    For passive couplings the sign of the coupling is determined from the sign of the other passive coupling and the relative position of the lower left corner of the two boxes. The sign of the other passive coupling is indicated in the status line, and can be changed with "-" (XK_minus). For vicinal protons the sign is assumed to be negative, for other protons it is assumed to be positive, in heteronuclear spectra it is not changed by the program.
    The group window always shows the position of the "variable" lineshape with respect to the "fixed" one. The correct sign is given in the status line of the tool.

    Coupling partners
    The passive coupling which is observed is assumed to be the coupling between the atom that defines the peak in the dimension in which the lineshape is taken, and an indirect coupling partner. The atom name and fragment number of this indirect coupling partner is resolved from the assignment in x and y dimension, if a *.ecosy_c list has been loaded ("i") which defines this relation. When the name or relative position of the coupling partner is edited, the list is adapted. It can be stored with "I".

    lineshape extraction
    Lineshapes are extracted from an area defined by a box, where pixels of the spectrum on the edge of the box have the same weight as pixels inside the box. That means, when a box includes only 10% or 90% of a pixel doesnt make a difference.
    Lineshapes are extracted along the longer axes of the box, where the length is measured in pixels (of the spectrum). Two modes can be selected: In normal mode (o) all pixels intensities along the short axis of the box are added up. In optimized mode (O) first a profile is determied along the short axis, by adding all "short" lineshapes with the sign of their maximum. Then negative parts of the profile are set zero, the profile is normalized, and lineshapes along the long axis are weighted with this profile. This mode is less sensitive to asymmetric settings of the boxes by a factor of about 3.
    The "fixed" lineshape is extracted from an area which is twice as long as the box. For automatic determination of the best fit the "variable" lineshape is shifted through all positions where it iscompletely inside this long area. For manual fits it can also be partially outside.

    3D spectra
    Ecosy tool supports to extract lineshapes from 3D spectra, but it uses only the plane of the spectrum which is nearest to the z-dimension of the peak. Collection of several planes in z-dimension is not implemented.
    Keys and mouse usage
    Only the left and middle windows and the top display field recognize the following key events. (The left window only reacts to standard lineshape window commands.)
    W, w
    write the curent coupling. It is written to the terminal and to an internal list. To create a file, use "tools" - "save lists".
    F, f
    foreward - go to the next peak
    B, b
    backward - go to the previous peak
    X, x
    =w+f. Write coupling and go to the next peak.
    - (minus)
    change the sign of the "other" passive coupling
    1 / 2 in in spectral window
    Use selected box as fixed and variable box, respectively, to extract the lineshapes. (the "old" boxes become invisible during the next redraw)
    right mouse button in spectral window
    The first two boxes that are created will automatically be interpreted as fixed and variable box to extract the lineshapes.
    A / a
    display / do not display peaks for which the program cannot determine exactly one passive coupling partner. default: A (display all peaks)
    D / d
    display / do not display diagonale peaks. default: d (no diagonale peaks)
    O / o
    optimization of lineshape on / off. see lineshape extraction. default: O (on)
    H / h
    propose / do not propose a reliability range for the coupling
    CTRL H
    remove an existing reliability range (set to 2.0 Hz, do not display)
    I, i
    Write, read indirect coupling list. To "activate the memory" of the tool, it is necessary to read a coupling list (which may be empty).
    J, j
    set a border of the reliability range to the current shift
    You have to move the cursor into the left or central window, the right widow responds only to "ordinary" ls_window commands!
    E, e
    edit assignments. This will not affect the assignments in the peak list, only the assignments that are written to the *.cco list.
    S, s
    adapt the "variable" lineshape to the "fixed" one using the current position of the shift cursor.
    In addition, mouse and key events are handled as described for spectral windows and lineshape windows

    NOAH Tool

    NOAH is a program written by Christian Mumenthaler in the group of Prof. Wüthrich at ETH Zürich; it is integrated in the DYANA package. The program makes assignments of crosspeaks in an unassigned NOESY peaklist on the basis of chemical shift data (proton list). Some assignments cannot be made on the basis of the peaklist alone. In this case NOAH may suggest several assignment possibilities, which can be stored in a file with the extension ".ass" with the DYANA command "write ass filename ambiguous". (This can be done after the standard "noah" macro.) The "NOAH tool" of SPSCAN is used to resolve such ambiguities, if possible, on the basis of lineshapes in the NOESY spectrum.
    HOW TO USE
    layout
    Keys and mouse usage

    HOW TO USE
    1. make sure that your spectrum and your peaklist have dimension ID's (and that these ID's can be matched)
    2. The assigned peaklist (NOAH output; noah.1.peaks in the standard macro) must have a "#ASSIGN_MODE ..." line in the list. If not, add by hand or get assignment.
      DYANA (1.4) does not keep these lines. You can copy
      #INAME 1     Hnoe
      #INAME 2        H
      #ASSIGN_MODE 6 /home/gaudi/rwg/B18/B18-40.prot /home/gaudi/rwg/B18/B18-40.seq SSP
      
      or something like that from the original peaklist if this was produced with SPSCAN.
    3. special: "tools" - "NOAH lineshape comparison"
      • load list with ambigeous assignments (NOAH output *.ass)
      • load assigned peaklist (NOAH output)
      • load the spectrum (if a spectrum has been loaded for integration, this is used)
    4. The tool window with lineshapes should pop up. For each peak up to three assignment possibilities are shown at the same time in different rows, the lineshapes in all dimensions are shown in columns. You can now select assignment possibilities as described below, or skip with "u".
    5. If all peaks in the *.ass list have been displayed, the program prints ">>> ready". Save the peaklist, because this containes the assignments that you have changed.
    6. Remove the tool window and free the memory with "tools" - "delete tool".
    Layout
    The first status line displays the number of the ambigeous peak and its assignment in the peaklist, if it is assigned there (if you you use the NOAH output list, it should not be assigned).
    The second status line shows the total number of assignment combinations considered possible by NOAH, and the number of combinations that are still valid (the differnce you have just disabled).

    Below, up to 3 rows of lineshape windows are displayed. Each row shows a possible assignment of the peak, with one column for each dimension. At the bottom of the lineshape window the assignment is displayed. "no ass." means that NOAH has not assigned any peaks to that resonance. The lineshape of the ambigeous peak is displayed in red (Col_peak=5). The lineshapes of peaks with this assignment are displayed in green, cyan, or orange. Peaks with green lineshape have no overlap with other peaks (overlap_category 0), cyan = 1 and orange = 2 (strong overlap).

    Keys and mouse usage in the lineshape windows of NOAH tool
    CTRL C
    Unmap the tool, not only the window where the pointer is in.
    d, D
    display peak, show spectrum around the selected lineshape. (if no lineshape is selected, the command is ignored)

    In the spectral window that you get with "d" you can use "p" to replace the lineshape that gave rise to this display by the lineshape at the current cursor position. If the lineshape is no longer displayed, the command is ignored.

    x, X
    Take this assignment possibility (where the pointer is in) as the correct one in both dimensions. The assignment possibilities for the next peak will be displayed.
    y, Y
    Take this assignment possibility as the correct one in the dimension of the window where the pointer is in. All other assignment possibilities for that dimension become invalid. If there is only one assignment possibility in the other dimensions, this command is identical to the one above.
    n, N
    Reject the assignment possibility in the particular dimension. It will become invalid, and a reduced set of possibilities is displayed. If rejection leaves only one possibility valid, the valid one is assumed to be correct, and the assignment possibilities for the next peak will be displayed.
    If more than one possibility is valid and you go on to the next peak, nothing os stored, i.e. information about possibilities that have already been excluded is lost.

    Lineshapes can be selected and resized as in other lineshape windows.

    Keys and mouse usage anywhere in the NOAH tool
    u, U
    leave this peak undecided and continue with the next peak.
    p, P
    continue with a particular peak number.
    Up, Down
    display other assignment possibilities, if more than 3 (or the number that is displayed) exist.

    Assignment Tool for 2D spectra

    Assignment tool is a spectral display window that shows the relevant resonances of a project (see screenshot). You can go through all (unassigned) peaks of a NOESY list, and just click on the resonance to assign the peak. You can also shift a resonance (equiv. to xeasy "mr"), pick new peaks, etc.
    A major advantage compared with an automated assignment is the possibility to "split" peaks. In crowded 2D spectra, many NOESY peaks are composed of two or more components, although they have only one maximum. Knowing the resonance positions, many of those peaks can immediately be recognized, and the two components can be assigned. This is particularly obvious, if the components are expected short range NOEs.
    In addition, Assignment Tool provides an automatic lineshape comparison with previousely assigned peaks, which works in exactly the same way as the NOAH tool described above. The possible assignments are selected interactively.
    HOW TO USE
    layout
    Keys and mouse usage

    HOW TO USE
    1. Display a spectrum with "display spec" - "any spectrum".
    2. Set the crosshair to the peak you want to analyse (left mouse) and press "F5".
      If you want to display a particular area in the assignment window, draw the area with the right mouse button before pressing F5. The crosshair has to be within this area. If no area is selected, the default area is 0.2 x 0.2 ppm centered on the crosshair position.
    3. If the peaklist is not yet displayed, select a peaklist with "F1".
    4. Select a peak with the middle mouse button, or pick a new peak with the left mouse button after choosing
    Layout of Assignment Tool The spectral window is surrounded on two sides by a frame that indicates the position of known resonances. The upper right corner is used for some display- and control fields.
    To compare the lineshapes of peaks, a separate window is opened.
    Keys and mouse usage in Assignment Tool The spectral window in the lower left is basically a normal spec_window and supports all standard mouse and key actions.
    The last peak that was selected stays "selected" for assignment operations, until another peak is selected. When the displayed area changes, the new central peak is automatically selected.
    The "frame" of the window supports the following mouse actions:
    right mouse button (pressed over a resonance)
    assign the selected peak to that resonance
    middle mouse button (pressed over a resonance)
    adjust all peaks that are assigned to that resonance to the position of the resonance. This is done in both dimensions and for all peaks of the current peaklist, regardless whether they are displayed in the selected area or not.
    move mouse with middle mouse button pressed
    Move the position of the resonance, then adjust all peaks assigned to it (see above). The effect of moving a resonance itself is only local; a permanent effect is acheived via the peak positions.
    right mouse button (pressed over a resonance)
    In peak picking mode, you can create an assigned peak by pressing the right mouse button over the two resonances that define it.
    Both frame and spectral window support the following key actions:
    u, U
    unassign selected peak (in both dimensions)
    m, M
    toggle color marks on resonances on/off

    some comments:
    When you look at your 1H-1H spectrum and peaklist in a magnified window you may realize systematic deviations between assignments in x and y dimension. Because both dimensions use the same resonance list, there is no way to "correct" this. There is no other choice than calibrating your spectrum accurately.


    Bugs and Limitations


    alphabetic index / program documentation / database / internals / methods
    Dr. Ralf W. Glaser
    FSU Jena, Institut fuer Molekularbiologie
    Winzerlaer Strasse 10
    D-07745 Jena, Germany
    Tel.: +49-3641-65-7573
    Fax: +49-3641-65-7520
    E-mail: Ralf.Glaser@uni-jena.REMOVSPMTAG.de