• Run the program
• Integrate a 2D spectrum
• Integrate a series of 2D spectra
• Pick peaks and integrate a 3D spectrum
• Correlate spectra and dimensions of a spectrum
• Change assignments in XEASY peaklists
• Change assignment of one resonance
• Create a pseudospectrum for evaluation of reduced dimensionality experiments
• Evaluate an ECOSY Spectrum and write a list of couplings
• Adjust calibration of several spectra

Run the program:

• SPSCAN needs a number of resources to run correctly (or to start up at all). To get them, it reads ~/XEasy, ./XEasy, ~/.Spscan, and ./.Spscan with increasing priority (if they exist). If you use both XEASY and SPSCAN, I recommend to put all resources into the XEasy files, and not to create ".Spscan" files: Many reource settings have to be identical for XEASY and SPSCAN. Check that resources are defined e.g. as "*peaks_path: ...", not "XEasy*peaks_path:" or "Spscan*peak_path:".
  The important resources are described under user customizability.
• It is important for spscan to run properly, that your spectra and peaklists have dimension identifiers (inmaes) for the dimensions set.
  SPSCAN may load spectra in a different way than XEASY, and than peaklists without inames may not be loaded in the correct permutation. Some routines check whether the first character of the iname is H, N, or C to find the correct dimension. Moreover, one of the automatic assignment routines requires that the name of the atoms is used as the name of the dimension, for example N, HN and CA for a HNCA spectrum and peaklist.)
  The easiest way to set the inames in a spectrum is with the "ca" command in XEASY. If you load a peaklist to the spectrum, and write it back to disk, it will automatically take the inames from the spectrum.
• spscan
  The most recent "stable" version is available as /opt/group/bin/spscan

Command line options

-m macroname

Start handling the macro macroname. Continue normally.

-x macroname

Start handling the macro macroname and exit after completion of the macro.

-h macroname

As above, and hide all windows.
I cannot recommend to use this option: If the macro needs any interactive input the program will end up in an infinite loop, because it expects input which cannot be given. However, "-h" it is a way to run long macro jobs "nohup" in background.

-p

Suppress automatic loading of a project file, although such a file is declared in the resources.

-d

Enable menue for "project" - commands (sequential connection, automatic creation of proton list, mapping ...) in executables where this menue is disabled by default.

Integrate a 2D spectrum:

• select "integrate"/"spectrum" ...
• if the spectrum is a pseudo-3D, make sure that the pseudo-dimension is dimension 3. If this is not already the case, put the pointer over the first field of the pseudo-dimension, hit "ESC" "3".
  ( In the 2D routines peak dimensions 1 and 2 must always match dimensions 1 and 2 of the loaded spectrum. Do not change "scan perm" in the parameter window! )
• click "load mini"
• select "integrate"/"parameters" and set some of the parameters. (For 2D most of the parameters are irelevant)
  
  • the first two lines: linewidth ranges
  • "peak shape"
  • number of iterations: At least 5 to get the linewidth and to correct the position; 2 - 4 depending on overlap, if position and linewidth are approximately correct.
  • "Max. ppm change, peak dim 1|2": the borders within which the position of the peak can be shifted
  • "Minimum relative distance" which prevents overlapping peaks to degenerate.
• select "peaklist"/"read new list" ... Load
  (If the spectrum or peaklist don't have dimension ID's, or these cannot be match, you have to select the correct dimensions. )
  
• click "parameters" - ... change if necessary, - "done"
  Most of the parameters listed in the window have no effect on processing of 2D spectra.
• pull "integration 2D" - ...
  "adapt lw & ppm" if you have a hand-picked list or a list that was created in another spectrum A typical calculation with 1024x1024 points and 100 peaks takes about 5 mins.
• pull "write pl" - "xeasy 2D lw" - enter filename - "Save"
• (as a check only) pull "write spectrum" - "residual 2D" - enter filename - "Save"
• Start XEASY, load the new peaklist and spectrum and have a look whether the fits are good. Check whether peaks in the list became degenerate, .
• If everything is ok, write a macro for the other spectra. It may not be useful to adapt the linewidth - so load the peaklist that you get for the spectrum with the best signal/noise to integrate all other spectra.

Integrate a series of 2D spectra:

• Integrate the spectrum with the best signal/noise as described above.
• Adjust parameters ('integrate' 'parameters') such that linewidth adaptation is off (Fig.) and that 'Max. ppm change' is set to a value which is slightly larger than the maximum difference in peak position between the spectra.
• If everything is ok, write a macro for integrating the other spectra. It may not be useful to adapt the linewidth - so load the peaklist that you get for the spectrum with the best signal/noise to integrate all other spectra, and adapt only ppm values, or nothing.
  For an example, see ccs_new.spm.
• Start the macro with "macro" - "Load"

Pick peaks and integrate a 3D spectrum

• prepare a 2D peaklist with all positions where you expect peaks in your 3D spectrum. If the position of the peaks is off by more than a linewidth, shift the peak positions in the projection of the 3D spectrum. You can also read in a 3D peaklist from another spectrum that shares two dimensions with the current spectrum.
• start SPSCAN
• click "integrate"/"spectrum"
  Load the spectrum (if the selection box does not pop up automatically, press "new spectrum"). Change the permutation (the first column of blue fields) such that the dimension in which the program has to scan for peaks, is dimension 3 (this dimension is also referred to as the "scan" dimension, in contrast to the two "peak" dimensions which define the known position of the strip).
• click "load mini" in the spectrum box.
• click "integrate"/"parameters"
  Give estimates for the following parameterts:
  • minimum, expected, and maximum linewidth in ppm (linewidth = distance of points with half maximal intensity) in all 3 dimensions.
    If the natural linewidth is much smaller than the resolution in one of the dimensions, set min=expected=max to about 3/4 resolution, and set adapt=off in this dimension.
  • minimum, expected, and maximum number of peaks per "scan"
  • pick mode
  • "(Small_vol) base": the volume below which peaks become a smaller weight
  • "Max. ppm change, peak dim 1|2": the borders within which the position of the strip can be shifted
  Set:
  • "keep existing peaks" off (= button up look)
  • "search additional peaks" on
• "write" the parameters to a file, and press "done".
• "peaklist"/"read new list" Load the peaklist. (2D or 3D, as described above).
• "integrate"/"3D"
  This routine takes quite a lot of time. If the program is compiled to print out debugging information you can see what is done. In any case you can inquire with "status?" what is going on. You can also "break" the current computation.
  For each iteration the spectrum is re-loaded from disc. During this time the machine is practically locked - don't become nervous. (If the lines are slow it may be an advantage to copy the spectrum to a local disc, e.g. to /tmp/... on gefjon. Please don't forget to delete it there, afterwards.)
  When the calculation is finished, the program prints ">>> ready".
• write out the peaklist with "peaklist"/"write list standard".
• Check whether the parameters you selected were approximately correct: have a look at "statistic"/"lw 1", "lw 2", and "lw scan" (to use "statistic", gnuplot has to be installed on the system). You should get something like a gaussian distribution of linewidths in the expected range, and only a few peaks at the min or max border. If necessary, repeat the calculation with improved parameters.
  (If the parameters have been changed considerably, it may be better to start re-load the original peaklist, because peaks might have been shifted in the wrong direction during the adaptation with wrong parameters)
• Have a look at the resulting peaklist. (use XEASY, or "display spec"/"3D tool" if you like it) If the peak positions are not exactly centered, something went wrong, and the volumes will also not be correct. (If all your peaks are shifted by half a pixel, then you have different "traditional_calibration" settings for SPSCAN and XEASY.)

This doesn't matter if you integrate all peaks with SPSCAN. But if you integrate some peaks "by hand" it my be worth to have a look, and apply a correction factor if neccessary.

Peaks with an obvious splitting can not (yet) been integrated with SPSCAN.

Integration of hand-picked 3D peaklists

• number of peaks (4th blue row) is irrellevant.
• "keep existing peaks" on (= button down look)
• "search additional peaks" off
• "Max. ppm change in scan_dim for fixed peaks" must be set.

related commands: spm average_linewidth

Adjust calibration of several spectra

The fine-adjustment of calibration is done with the following steps:

• load spectrum and peaklist, pick peaks as descibed above.
• click "display spec"/"3D tool"
• check some of the positions
  • use "next" or "show strip (id)" to display a strip
  • select "original ppm from peaklist" and load the peaklist of a spectrum for which you want a good match. This gives green lines from the current peak position to the peak position in the reference list.
  • all planes follow the crosshair - when you click the left mouse button in a display, the other two views of the spectrum display the new crosshair position. So you can search through the strip area to find the peak(s).
  • if the strip is not well positioned, select the peak with the middle mouse button and drag it to the correct position.
• select "check position 1/2" (below "exit")
  You see the difference between the strip positions in the current and in the reference peak list. The strips that you have seen are shown in light blue, the other peaks in yellow. The green lines mark zero difference. The crosshair shows the suggested adaptation.
  • You can shift the crosshair with the left mouse button.
  • You can get information about individual peaks with the middle mouse button (select a peak) and "q".
• select "change according to cursor". This shifts the spectrum, the current peaklist, and all peaklists of the project that refer to this spectrum.

Change assignments in XEASY peaklists:

The following situation may arise in XEASY: You have worked with two spectra in parallel, and inserted different atoms or assigned atoms from one residue to different fragments numbers. As a result, the peaklist from the two spectra cannot be used with the same proton list, and it is difficult to combine the information from the two peaklists. In XEASY this situation cannot be improved by mapping the fragments of both lists to the real sequence, since this does not change the assignment numbers in the peaklist, which remain incompatible.

SPSCAN offers a possibility to reassign the peaklists, i.e. to change the assignment numbers so that they correspond to a new proton list. You can also exchange fragment numbers without getting your proton lists mixed up. This allows, for example, to assign backbone, side chains, and aromatic rings independently and combine the information at the end.

The routine works in the following way: it uses the original XEASY proton list to resolve the fragment number and atom name. Then it searches in the new (target) proton list for the first entry that matches both values, and changes the assignment number to the number of this atom. If it does not find a matching atom and you have set "do atom mapping ?" = "y", it searches an atom mapping library for a valid conversion. Atoms for which no match is found become unassigned, and a message about the old status of the atom is printed out.

At the same time, you can change fragment numbers: set "do residue mapping ?" = "y".

• spscan
• "load mini" any spectrum with matching dimensions. (You dont need it, but SPSCAN should know how to load the peaklist.)
• peaklists: "read peaklist" - "new 3D full list"
  load your peaklist
• You must have a line in your peaklist that specifies the current assignment:
  #ASSIGN_MODE 5 proton list sequence list residue name
  If your peaklist was written by XEASY, and doesn't have such a line, select "assign"/"get assignment", use mode 5, and load sequence and proton list.
• select "assign"/"reassign"
  enter the wanted assignment mode (mode 5) and all additional information that is required, i.e. the new sequence and proton lists, as well as possible mapping files.
• select "peaklist"/"write list standard" to save the new peaklist.

Change assignment of one resonance

Situation:

You want to change the assignment of a single resonance in a peaklist or in all peaklists of a project, e.g. all peaks that are currently assigned as LEU 105 HB3 should be assigned to LEU 105 HG.

Background:

The assignment numbers in the peaklist(s) are changed, the proton list is not immediately effected.

Procedure A: Make changes in a single peaklist

1. 'project' 'peaklist manipulations'
2. peaklist manipulations: 'load peaklist 1' (the peaklist must have a valid '#ASSIGN_MODE ...' line)
3. peaklist manipulations: 'change assignment of a resonance'
4. Enter the two assignments either as <atom name> <residue number> or as < assignment number>. To replace an intraresidual resonance you can omit <residue number> in the second line, if you have entered <atom name> <residue number> in the first line.
   Repeat this step until you have replaced all resonances.
5. peaklist manipulations: 'save peaklist 1'
6. peaklist manipulations: 'exit'

Procedure B: Make changes in all peaklists of the project

1. 'project' 'edit'
2. edit project: 'change assignment of a resonance'
3. Enter the two assignments either as <atom name> <residue number> or as < assignment number>. To replace an intraresidual resonance you can omit <residue number> in the second line, if you have entered <atom name> <residue number> in the first line.
   Repeat this step until you have replaced all resonances.
4. edit project: 'exit'

Exchange two assignments:

Change one of the assignments to an unused assignment number, e.g. 'HG 105' to '10599'; 'HB3 105' to 'HG 105'; '10599' to 'HB3 105'.

Evaluate reduced dimensionality experiments and create a pseudospectrum

Before you start, you need a N-HN cosy list with the starting positions of the strips where you are searching for peaks. All entries in this list must be assigned, if they are not, use "assign"/"2 peak dim to inames" with residue SRD. In addition, you have to copy COHNCA-.scpa and COHNCA+.scpa into the current scpa_path and adapt the linewidth parameters (by reading the files in the parameter window, making the changes, and writing them out again).

• Load the spectrum with C as dimension 3.
• "read peaklist" - "new 2D reference list" - Load the cosy peaklist.
• "HN_CO/CA" - "get central peaks"
  This loads COHNCA-.scpa and starts the search for central peaks. It will be better if you do that by hand and check the parameters:
  • Integration: "integrate" - "parameters", "read" - load COHNCA-.scpa
  • Adapt the min, expected and max linewidth
  • Set "(Small_vol) base" to the average expected volume of the central peaks
  • Set "Max. ppm change ..." such that the peak center will always be found from the current position
  • Integration: "integrate" - "3D"
• "HN_CO/CA" - "make pseudo-spectrum"
  The program asks for some parameters and creates a new spectrum, which consists only of individual strips. The command produces a striplist rdpa->stl, which is neccessary to adapt other lists to this pseudospectrum.
  (This step is not neccessary to get assignments. The pseudo-spectrum is created to display strips in XEASY, which have a "normal" CA dimension. It must be loaded such that "pseudo" is the indirect dimension. Maximal distance in planes (for display of peaks) must be 0 - otherwise you see peaks that have no relation to the strip. The commands "fp" and "bp" in XEASY load next and previous strips instead of neighbouring planes.)
• "HN_CO/CA" - "assign as Cp"
  Assigns all peaks in rdpa->stl as "Cp" (=C n-1) in C dimension. This works only if the pseudoresidue is SRD or SSP. Otherwise they are assigned as "C".
• "HN_CO/CA" - "write striplist"
  Writes rdpa->stl. This is a list of central peaks with the dimensions of the pseudospectrum. It is used to define strips for the pseudospectrum in XEASY, and it can be read back with "HN_CO/CA" - "read striplist", if other peaklists should be adapted to the pseudospectrum.
• "HN_CO/CA" - "get paired peaks"
  Loads "COHNCA+.scpa" and starts search for paired peaks in mode SYM_FIRST. See "get central peaks", above.
• "HN_CO/CA" - "assign as CAp and CA"
  assigns the larger one of the two paired peaks as CAp and the smaller one as CA. This command affects assignments in the list of pairs.
• "HN_CO/CA" - "write pseudo peaklist"
  Creates from the list of pairs a list of peaks in indirect dimension (CA), and adapts the ppm values in N and HN dimension to the pseudo-spectrum.

More detailed information is found under interface: HN_CO/CA

If there is more than one central peak per strip, several strips are created in the pseudo-spectrum. However, all peaks are shown in the first of these strips.

Referencing of the pseudo-spectra can be incorrect by up to +/- 1/4 pixel. Consider that lineshape comparison may be misleading for this reason.

Correlate spectra and dimensions of a spectrum

Let us assume that we have all HA-CA crosspeaks assigned. We want to find the other CH moieties of the sidechain. We start with a peak H1/C1 in a 2D overview spectrum "HC". In strip I of the 3D HC(C)H-COSY spectrum we find the diagonale peak H1/C1/H1 and one or two crosspeaks H1/C1/H2. To get C2 we have to find a matching crosspeak H2/C2/H1. This crosspeak must be visible on strip II. When we have found it, we display strip III to check whether the peaks are correctly centered and whether strip III shares other crosspeaks with strip I. From the crosspeak in strip II and III we can go back to the overview spectrum. The position of the strips in the spectrum is indicated below

Now the steps to do interactively. In the 3D HC(C)H-COSY spectrum we have w1=H1, w2=C1, w3=H2. The spectrum is registered in the project as "HCCH", the 2D overview spectrum as "HC".

• "display spec" - "any spectrum"- HC
• "display spec" - "any spectrum"- HCCH - 1 2 3
  1 2 3 are the new dimensions in the left blue fields (this should be the default). Set the third field of the new dimension "1" (end) to 20. Press "ok". Use the window manager to resize the spectrum so that it forms a vertical strip. The same procedure with the next two spectral displays.
• "display spec" - "any spectrum"- HCCH - 2 3 1
• "display spec" - "any spectrum"- HCCH - 1 2 3
• "display spec" - "any spectrum"- HC
• arrange the windows on your screen as shown in the screenshot HCCH.
• Be sure that the cursor is in one of the spectra and press CTRL-SHIFT-g. Set the first four lines to H1 C1 H2 C2. OK. Press "g". The "chemical shift" window shows four lines H1 ..C2.
• Put the cursor to the first HCCH strip. Press CTRL-g. Set the fields to 0 2 1. OK. Now you have correlated the x-crosshair with H1 (0), the y-crosshair with H2 (2) and the plane with C1 (1).
• Put the cursor to the second HCCH strip. Press CTRL-g. No. Set the fields to 2 3 0. OK.
• Put the cursor to the third HCCH strip. Press CTRL-g. No. Set the fields to 2 0 3. OK.
• Put the cursor to the first HC display. Press CTRL-g. No. Set the fields to 0 1 -. OK.
• Put the cursor to the second HC display. Press CTRL-g. No. Set the fields to 2 3 -. OK.
• Put the cursor to all five spectral displays and press "4". Nothing happens, but after the next change of the windows contour plots will be drawn. (Otherwise the computer will decide from the number of points whether it draws an intensity or contour plot)
• Put the cursor to the first HC display. Press F1. "display peaklist" - HC.
• Same with the second HC display.

• Press the left mouse button on a peak in the first HC spectrum. The crosshairs will be drawn on this peak.
• Put the cursor to the first HCCH strip. Press "o". The strip will show the diagonale peak H1/C1/H1 and (in most cases) one or more crosspeaks.
• Press the left mouse button on one of the crosspeaks
• Put the cursor to the second HCCH strip. Press "o". Strip 2 along the 13C dimension (w2) will be set to the transposed position of the crosspeak in strip 1. There should be at least one peak on the strip.
• Press the left mouse button on the peak. Put the cursor to the third HCCH strip. Press "o". If there are several peaks, repeat the procedure with the other peaks and decide from the match between the transposed peaks in strip 1 and 3, and from the match between additional crosspeaks in the case of CH2 moieties, which crosspeak is correct.
• In the second HC display the crosshairs now mark the peak H2/C2. If you do not see the crosshairs, put the cursor to the display and press "o". Press the middle mouse button on the peak and press "a". You can now assign the peak.

Some more hints:

• You cannot compare the position of crosspeaks in strip 1 and 3 with the crosshairs directly, because the crosshairs are transposed. You cannot click on the two crosspeaks and compare the numbers on the H1 and H2 crosshair fields of the chemical shift window, because the crosshairs are correlated. You have to click on one of the crosspeaks and compare the number on the crosshair field with the number of the pointer field when you move the pointer to the other crosspeak without pressing the left mouse button.
  As an alternative, you can align the two strips so that a visual comparison is possible.
• Before you zoom on a peak, press CTRL-s. So you can restore the full strip with CTRL-z.
• To continue from H2/C2 to H3/C3, you need a fourth strip. In contrast to strip 2 it has to have the 13C dimension correlated with C1(C3).
  "display spec" - "any spectrum"- HCCH - 2 3 1. CTRL-g. No. 2 1 0. OK.
  Now you can go from strip 3 to 4 back to 1.