Sparky displays processed NMR spectra. You find, assign, and integrate peaks using a graphical interface. Spectra for input to Sparky can be produced with the processing program NMRPipe (from the NIH), or Felix (from BioSym), or VNMR (from Varian), or XWinNMR or UXNMR (from Bruker). After picking, assigning and integrating peaks you can produce peak lists showing chemical shifts, volumes, linewidths, .... Atoms have groups or residues associated with them to aid assignment of proteins, dna and rna. You can work with any number of 2, 3 or 4 dimensional spectra simultaneously.
This is version 3.66 of the manual, last revised March 3, 1999. You can get a Postscript version or the latest html pages, images, and Postscript in tar or zip format from the Sparky web site (http://www.cgl.ucsf.edu/home/sparky). To search for specific words you may prefer the single file html manual. The manual is part of all Sparky distributions. It can be found in /usr/local/sparky under Unix or Linux and in c:\Program Files\sparky under Windows.
Sparky helps you assign and integrate peaks in NMR spectra. The input is spectrum data in Felix matrix format or UCSF format. The output is ascii lists of assigned peaks, chemical shifts, volumes, linewidths, .... Finding peaks and making assignments is done manually through a graphical user interface. Sparky does not do processing or distance geometry, molecular dynamics, or make toast.
Assignment w1 w2 Volume lw1 (hz) lw2 (hz) G16H3'-H8 4.905 8.010 7.15e+06 ga 28.6 20.0 G16H4'-H8 4.439 8.013 5.42e+06 ga 35.3 16.9 T17H6-G16H8 7.205 8.004 1.68e+06 T17H7-G16H8 1.459 8.008 2.09e+07 ga 27.5 24.1 T17H2"-H1' 2.509 5.840 4.68e+07 ga 41.2 17.6 ...
The command to run Sparky is "sparky". The usual installation location is /usr/local/sparky and there is a link to the main program in /usr/local/bin. If either of these directories is in your search path you can start Sparky from any directory by typing "sparky".
Convert data processed with NMRPipe to UCSF format with the program pipe2ucsf that comes with Sparky. Data processed with Felix can be directly read by Sparky but the transmitter frequencies, spectral widths, reference shifts, ... in the Felix matrix must be correct. Set these with the Felix rmx command. Convert 2-D data processed with Varian's VNMR software using vnmr2ucsf that comes with Sparky.
Once you get frequency domain spectral data in Felix of UCSF format you can open it using "open" under the Sparky file menu. A new window will appear showing a contour plot.
The first thing you'll want to do is adjust the contour levels. Select "contour levels" from the tools menu. This will bring up a dialog that lets you set the lowest displayed level, number of levels, space between levels, and color of levels.
Press the "Apply" button to make your changes take effect. Dialogs in Sparky have an "Ok" button and an "Apply" button. Ok means make the changes and make the dialog disappear. Apply means make the changes and leave the dialog up. Since you pressed apply the contour dialog is still showing and you can make another change if you aren't satisfied with the new contour levels.
To show different regions of the spectrum move the scrollbars, resize windows, and use "zoom in", "zoom out", and "zoom previous" from the view menu. Note that the menu entries for zooming have 2-key accelerators listed next to them. The accelerator for zoom in is "zi". Typing zi in the spectrum window makes it zoom in. Another way to zoom in is to select the zoom pointer mode. There's a window of vertical buttons "select", "center", .... This window determines the pointer mode. Select the zoom pointer mode. Then drag a box in a spectrum window. The view zooms to show that region. By "drag a box" I mean press the left mouse button at one corner of the desired region, hold it down and move the pointer, and release the button.
You can show more than one view of a spectrum. Select "duplicate" under the view menu or type the accelerator "vd" in the window you want to duplicate. Another view will be created. You can adjust its contour levels and the region shown to be different from the original view. Note that the contour dialog has a menu of spectrum views so you can select which view you want to adjust. Each view has a name shown at the top of its window. The name is derived from the name of the spectrum with a number appended.
You can show as many views of as many spectra as you want. To open a view of a new spectrum use Open under the File menu. The views of any previously opened spectra remain displayed. To close a window double click on the button in the upper left corner of the window frame.
Now you've zoomed in to an appropriate magnification and set the contour levels to eliminate most of the noise. Choose the "find/add peak" pointer mode. If you click the left mouse button over a peak a marker will appear. You've placed a peak on the spectrum and it will appear in all views of this spectrum. You can also drag a box around a region, ie. press the left button and move the mouse and then release the button. A rectangular box is drawn and Sparky will place peak markers on all the peaks in the region. How does it do this? It uses a minimum height and a minimum linewidth. You set these using the peak dialog (accelerator "kt"). The linewidth is taken as the half height width.
If you want to move a peak marker switch to the "select" pointer mode and drag and drop the peaks. If you want to delete a peak switch to select mode, click on a single peak or drag a box around a region to select peaks. Selected peaks are outlined with a square. You can delete the selected peaks by pressing the delete key. If you delete some peaks by mistake you can use the "edit undo" command (accelerator eu) to restore them.
Select a single peak and bring up the assignment dialog (accelerator at). Type in a group name and atom name for each axis and press apply. Sparky is designed for assigning polymers -- proteins and nucleic acids. The group is meant to indicate the residue or base type and number (eg. P71, tyr36, a9, GUA15, ...). The atom names a specific atom of the group (eg. HN, CA, H2', H6, ...). Since Sparky does not interpret the group or atom names you can use whatever is useful for subsequent processing of peak lists. At the beginning of the assignment process you won't know much and can use group names like g1, g2, g3, ... and later rename them.
When you make an assignment a label is displayed near the peak. With the pointer in select mode you can drag the label to a new location.
Assignments can be displayed along the edges of a view. To show these resonance panels along the edges of a view use the "show resonances" command under the view menu (accelerator vR). The group and atom names will be shown along both axes. To see the alignment of peaks with these resonance names it help to display crosshairs, a horizontal and vertical line that follow the pointer. Bring up the view settings dialog (accelerator vt), and check crosshair display and press OK.
You've picked some peaks. Now try integrating one. Select the "integrate" pointer mode, then drag a box around a peak you want to integrate. The default integration technique is to use a Gaussian fit. If it worked, the peak will be recentered to the best fit position and will have a circle drawn around it. You can examine the fit by displaying one dimensional cross-sections along the edges of the view. Bring these slice panels up using "show slices" under the view menu (accelerator vS). The profiles of the spectrum data are shown in black and the peak fitting profiles in blue. The horizontal panel shows the horizontal cross-section at the pointer position.
To see the numerical volumes and linewidths bring up a peak list (accelerator lt). Press the "options" button in the peak list dialog and select volume and linewidth display and press OK. The list shows all peaks in the spectrum and can be written to a file by pressing the "save" button.
Peaks can be integrated using different methods. Gaussian or Lorentzian fitting can be done. Overlapped peaks can be simultaneously fit where all selected peaks within the lowest contour line are taken as a group. Groups can also include peaks not withing a common contour line but within a specified distance of each other. You can also integrate peaks by boxing or ellipsing. You drag a rectangle or ellipse around a peak and the heights at all interior points are summed up. The integration technique is chosen using the integration dialog (accelerator it).
Sparky maintains lists of resonances. By a resonance, I mean an atom name and a frequency. The frequency of a resonance is calculated from the positions of all the assigned peaks involving the atom. All peaks are weighted equally in the average. These resonances are listed in the assignment dialog to help you make assignments and can be shown along the edges of contour plots. Sometimes it is useful to maintain more than one set of resonances. If your study involves two similar molecules or spectra taken under different conditions (pH, temperature) that shift the resonance lines you probably don't want just one set of average resonance frequencies. To handle this Sparky associates a "molecule" name (eg. cyt-b5) and "condition" name (eg. ph7 25C) with each spectrum. These names are chosen by you and typed in using the spectrum dialog (accelerator st). Separate resonance frequencies are kept for each distinct molecule and condition.
To save the data you produce using Sparky use "save" under the "file" menu. This saves assignments, label positions, view window configurations, ..., jvfor a single spectrum. The file containing your processed NMR data (eg. noe150.ucsf) is never modified by Sparky. All Sparky data goes in a separate file in the ~/Sparky/Save directory (eg. named noe150.ses). Each spectrum has its own Sparky session file. When you are working with more than one spectrum, saving the data for each spectrum can be tedious. To save the data for all spectra use "project save" under the "file" menu. This creates a file in ~/Sparky/Projects which contains a list of the spectrum files you are working on. When you start Sparky at a later time you can open the project to load all your spectra. You can also load Sparky data for an individual spectrum by opening a file in ~/Sparky/Save in the same way you opened your processed NMR data. The open command recognizes both processed NMR data and Sparky data file formats.
You can shift the ppm scale for each spectrum to align spectra. Use the spectrum dialog (accelerator st). The ppm positions of all peaks are updated.
Contour levels for a view are set with the contour dialog (ct). For the positive levels you set the lowest level, the number of levels, the scale factor from one level to the next, and the color. The level heights increase geometrically. The scale factor is multiplied times the lowest level to get the next highest level. Negative levels also have a lowest level, number of levels, scale factor and color. The number of levels can be zero.
You can display a scale showing contour levels at the edge of a contour plot using the command vC. The levels can be adjusted by dragging the lowest or highest level up or down with the mouse. This keeps the existing levels (their position and spacing) fixed while adding or removing levels at the low or high end. By dragging up or down starting in the middle of the group of levels you can add or remove extra levels while keeping the lowest and highest level fixed. This changes the positions and spacing of all the intermediate levels.
In the "center" pointer mode a view is recentered to any point you click on.
The view center command vc centers the view on the selected peak. The most useful case is when the selected peak is from another spectrum. If the peak spectrum and the view spectrum are different then it is possible that only some of the view axes will be centered. For example, if the peak is from a 2D HSQC spectrum (15N and 1H axes) and the view is an HNCA spectrum (1H, 15N, 13C axes) then only the proton and nitrogen axes of the view are adjusted. The carbon axis is left in the current position. The exact rule is for each view axis center use the unique peak axis with matching nucleus type. If there is more than one peak axis with matching nucleus then center the wN view axis with the wN peak axis if the nucleus types match. In other cases don't center the view axis. The true peak frequency (including any peak alias) is used. If the resulting center position is off of the view spectrum then multiples of the spectral width are added or subtracted to bring it onto the spectrum.
When you are working with many views the screen gets crowded. To hide views use "view hide" (vh). To bring them back select them by name from the View menu. You can also use the View menu to raise views that are buried behind other windows to the surface. Another way to show hidden views is to use the project view list (pv). You can also iconify views by clicking on the "iconify" button on the window frame next to the "maximize" button in the upper right corner.
Specify the molecule and condition for a spectrum using the spectrum dialog (st). A given molecule and condition has a set of resonances associated with it. The resonance positions are calculated by averaging the positions of assigned peaks in all spectra for that molecule and condition. The molecule and condition are only used to name multiple sets of resonances. They can be changed at any time and all resonance lines are automatically recalculated.
The molecule and condition can be any text. They can include spaces and they may be left blank. The condition is meant to include things like temperature and ph (eg "25C ph7"). It is desirable to keep the names short since they are sometimes displayed in the titles of windows and in menus.
To show the full spectrum use "zoom full" (zf). To zoom back to the previous region you were displaying use "zoom previous" (zp). To zoom in or out by a factor of 2 use zi and zo. To name specific regions so that you can zoom to them by name use the region dialog (rt). You can type numerical ppm ranges to this dialog and associate a two letter accelerator with them. You then use the "region goto" (rg) command followed by your chosen 2 letter region abbreviation to zoom to that region in any spectrum.
The region dialog (rt) allows you to name regions with given chemical shift boundaries so that you can quickly zoom to those regions. To name a region enter the numerical region limits in ppm. You can instead adjust a view so it is showing the desired region and press the Current button to have the boundaries entered for you. Type in a name and a two letter accelerator. The accelerator names do not conflict with Sparky commands so you can choose any two letters. Press the Add button to add the named region to the list of regions. Now you can use the region goto command rg followed by the two letter region accelerator to zoom a view to this region.
You can also apply the current pointer mode to a region. For example, to pick peaks over an entire spectrum choose the find/add peaks pointer mode (F8). Bring up the region dialog (rt). It will show the upfield and downfield limits of the region you are viewing. Press the World button. This sets the limits to include the whole spectrum. Now press Apply Mode to find peaks.
The orthogonal views (ov) command shows three orthogonal planes of a 3-D spectrum. If a peak is selected before typing the command, the three orthogonal planes intersect at the peak position. Otherwise they intersect at the central point of the current view. The three views have their w1, w2 and w3 axes synchronized. This means the center points of the 3 views show the same data point even when you scroll one view or center on a new peak.
You can overlay the contours of one spectrum on another spectrum. You use the overlay dialog (accelerator ol) to set this up. You choose two Sparky views, one to to be shown overlaid on the other. By repeating this process you can overlay as many spectra as you want on one view. You can control the contour levels and colors of each overlaid view separately using the contour dialog (accelerator ct). Printed output does not yet include the overlaid contours.
You can print contour plots to a Postscript printer. Accelerator pt. Color output is supported.
The selected view is the window that you last clicked on or moved the pointer into. Whether you need to click on a window or just move the pointer over it to select it is determined by your window manager, not Sparky. Most window managers allow you to choose either style. The selected view has the word "selected" in its title. when you execute a command from the pulldown menus it operates on the selected view.
Axes of 2 or more views can be synchronized so that scrolling one view causes the others to scroll. Accelerator yt. Synchronization keeps the center positions (in ppm) of the corresponding axes the same. To make synchronized views match their displayed ranges use "synchronize ranges" (yr).
The accelerators ya, yd, and yt all bring up the synchronization dialog. It lists the axes for every view. You select two or more axes to synchronize and press the synchronize button. Synchronized axes have a letter a, b, c... appearing next to them. Axes labelled with the same letter are synchronized. To remove synchronizations select one or more axes you no longer want to synchronize and press the unsynchronize button. Synchronization keeps the center positions of the synchronized axes matching. Note that you can synchronize two axes from the same spectrum. This forces the view to show the diagonal and is probably not what you want. To make synchronized views display the same range along synchronized axes use synchronize ranges (yr). This will zoom other views to show equal axes ranges. They are matched to the view in which you executed the synchronize reset command (ie. typed yr).
To zoom a view to the corresponding region across the diagonal of a homonuclear spectrum use "transpose axes" (xx). If you try xx on a heteronuclear spectrum the displayed vertical and horizontal axes are swapped keeping the center of the view fixed.
To cyclically permute the axes of a view of a 3-d spectrum use "axis roll" (xr). The center point of the view is kept fixed. On a 2-d spectrum this command swaps the axes.
The "project view list" (pv) shows a list of all your views. The project view list shows the sizes, nuclei, number of peaks, and number of assignments for your spectra. A minus sign is shown next to hidden views and a plus sign next to visible views. Double click on list entries to show a hidden view or to hide a shown view.
Use the "view settings" dialog (vt) to change what is displayed in a spectrum view window. You can control the display of axis scales (vs), axis units (xp, xh, xd), nucleus types (xa), aspect ratio, assignment label format, ornament display (os, ls, ps, xs, gs, is), resonances along edges (vR), 1-D cross-sections along edges (vS), peak info status bar (vp), crosshair display (hh, ht, ho), scrollbars (vb), and subtracting fit peaks (sf).
The scales along the edges of views can display ppm units, index units (ie. indices from the NMR data matrix), or Hz using accelerators xp, xd, xh. You can display the nucleus types (H, 13C, 15N) on the scales using "axis atoms" (xa).
The aspect ratio controls how a 1 ppm by 1 ppm cell will appear on the screen. An aspect ration of 3 would make the 1 ppm square appear 3 times wider than it is tall. Aspect ratios less than one make the cell appear taller than it is wide.
The assignment format specifies how to display assignment labels on contoured spectra. The default format is "%a1-%a2" for a 2-D spectrum. The "%a1" means display the full atom name for the w1 assignment. The full atom name includes the group. Then the "-" is just put into the label. Then "%a2" means display the atom name for the w2 assignment. The "%a2" will not display the group if it is the same as the group displayed in the preceding "%a1" part. To force the groups to be displayed use "%A1-%A2". In general, "%a" means display the atom name and leave off the group name if the preceding % format displayed the group, whereas "%A" means always show the full atom name. To show just the group names use "%G1-%G2". To show just the group name for the w2 axis use "%G2".
The switches in the view settings dialog (vt) or the accelerators os, ls, ps, xs, gs, is, turn on and off display of ornaments, labels, peaks, peak groups, grids, and lines. The ornament display switch (os) turns off the display of all ornaments when it is off. When it is on the specific ornaments selected with the other switches are shown.
Use "show resonances" (vR) to display resonances along the edges of spectrum views. The resonance closest to the pointer position is highlighted in blue. If the pointer is over a peak, the assigned resonances are highlighted in red. The resonances often get very crowded making the display along the edges not useful. You can reduce the number of resonances displayed by setting assignment guessing constraints. Press the Guessing button in the assignment dialog (at) to set assignment constraints. For example you can set an (i,i) constraint meaning consider only intra-residue assignments. Then switch on "Thin resonance panels using assignment guessing?" in the preferences dialog (pf). Now a resonance from residue 17 will only be displayed along the x-axis if there is some resonance from residue 17 in the range displayed on the y-axis.
Accelerator vS turns on and off the display of 1-D data cross-sections. The 1-D profiles are displayed along the edges of the spectrum view window. The panel along the bottom edge shows the horizontal data slice passing through the current pointer position. With crosshair display turned on the horizontal crosshair line shows the position of this 1-D section. The panel at the right edge of the view shows the vertical 1-D slice passing through the pointer position. If peaks have been integrated by fitting Gaussians or Lorentzians, the fit profile is shown in the slice panels in blue. A third trace (in green) can show the spectrum data minus the fit peak curve (sf). This is useful for judging the quality of peaks with baseline fitting.
You can adjust the range displayed in the 1-D data profiles shown at the edge of contour plots (accelerator vS). You move the mouse to either the horizontal or vertical slice panel and drag to adjust the range displayed. Holding the shift key while dragging shifts the center line. Alternatively you can have the range automatically adjust to fit the slice data. Set this in the view settings dialog (vt).
A problem with adjusting the slice panels is that when you move the pointer to the slice panel it updates the slices. So you no longer see the relevant slice you want to use to adjust the scales. Here is a way adjust while showing the slice you are interested in. Suppose you want to look at an X axis slice. Move the pointer horizontally to the Y axis slice panel and adjust the scales. Since both X and Y slice panels use the same range you will see the effect on the X slice. Try it and you'll understand what I mean.
The "show peak info" command (vp) puts a status bar at the bottom of the current view which displays peak assignment, position, height and linewidth when the pointer is over a peak. If the peak has been integrated by fitting then the fit height and linewidth are shown. Otherwise an estimated linewidth is computed as the full width at half the peak height. If the peak is not positioned at the local maximum this can be misleading. When the pointer is not over a peak marker but is over a contoured region Sparky will find the local maximum and show its position, height and full width at half the maximum height.
Views can display a crosshair (vertical and horizontal lines) that follows the pointer. They can also display a crosshair transposed across the diagonal in homonuclear spectra. They can also display a crosshair when the pointer is in another view at the corresponding point in this view. This last capability helps look at corresponding peaks in different spectra. To turn on crosshairs of one type or another use the view settings dialog (vt).
Crosshair tracking from other views shows the crosshair in one view at the corresponding point in another view. What does the "the corresponding point" mean? It means the same ppm values on the w1, w2, w3, ... axes. But if the two spectra don't have matching nucleus types (1H, 13C, 15N) Sparky will make the axis correspondence that makes nucleus types match provided there is a unique correspondence. If there isn't a unique correspondence Sparky chooses one of the possible correspondences based on rules that are beyond explanation.
Turn on the subtract fit peaks (vf) switch to display contoured data with fit peaks subtracted off. This can be used in conjunction with 1-D slice display to see how well the spectrum data is fit and to see whether there are smaller peaks buried under larger fit peaks.
You assign peaks using the assignment dialog (at). Select a peak in a view. Bring up the assignment dialog (at) and type in group and atom names for each axis and press Apply. The peak is labeled with the assignment.
The assignment dialog contains a list of resonances for the molecule and condition of the selected peak. If you click on an axis label (w1, w2, ...) in the assignment dialog the resonance list will scroll to the resonance closest in frequency to the peak position along that axis. If you double click on a line in the resonance list it will fill in that group and atom name for the selected axis.
The Resonance Peaks button brings up a list of peaks from all spectra with an assignment involving the resonance selected in the resonance list.
The assignment delete command (aD) deletes the assignments from all selected peaks.
Press the Guessing button in the assignment dialog (at) to set up assignment constraints. You can consider intra-residue (i,i) guesses or inter-residue (i-1,i) guesses. You can request guesses using only a specific atom name or set of names separated by '|'. You specify the range of chemical shift values away from the peak position to look at. Press the Apply or Ok button after choosing the constraints. Now whenever you show a peak from the same spectrum in the assignment dialog Sparky will look at your current set of resonances and find the closest assignments satisfying the constraints. It puts these in a menu under the "guesses" button in the assignment dialog. Selecting a guess from this menu fills in the assignment. The guessing constraints are also used by the "assignment guessing" pointer mode (sh-F2). When you select peaks in this pointer mode they are assigned if they have a unique assignment guess. This mode will not reassign a peak. Only new assignments are made.
To display a table of chemical shifts where the rows are the different groups (ie. residues) and the columns are the different atoms use the assignment table command tb. The chemical shifts shown in the table are averages obtained from all peaks in all spectra having the same molecule and condition names. To see the number of assignments contributing to each average chemical shift click on the "assignment counts" switch and press the "update" button. You can also have the table entries include the standard deviation of the peak positions contributing to each chemical shift. To display the list of the peaks contributing to a resonance click on its entry in the table.
You can copy peaks with their assignments between spectra. You select the peaks, use "ornament copy" (oc), select the destination view, and use ornament paste (op).
To copy just assignments (assuming peaks already exist in the destination spectrum) there are two methods. You can use the same two step copy and paste method with the "assignment copy" (ac) and "assignment paste" (ap) commands, or you can use the assignment copy pointer mode. Using the pointer mode you just drag a rectangle around the peaks you want assignments applied to. The source spectrum is specified in the assignment copy dialog (co). If you select a peak and there is no close peak in the source spectrum then you get a message saying there was no nearby peak in the source spectrum. How close must a source peak be? Here it gets weird. You set the tolerances with the assignment copy dialog. Each spectrum has its own tolerances. And for the assignment copy operation I just described the tolerance for the source spectrum is used. The tolerance for the destination spectrum, ie the one containing the peak you want to put an assignment on, is not used and changing tolerances for that spectrum will have no effect. Why does it work this way you ask?? When you select a peak in assignment copy mode Sparky looks in the source spectrum and tries to find a peak with nearly the same position. To find a nearby peak in the source spectrum it uses source spectrum tolerances.
The other method of doing assignment copy using commands ac and ap works like this. Use the selection pointer mode. Select some peaks with assignments and type ac. Those peaks are remembered. Go to a spectrum with unassigned or partially assigned peaks and type ap to paste assignments to this spectrum. This takes each peak remembered from the last ac command and tries to find a corresponding peak to paste the assignment onto. That is it takes a source peak and looks for a peak near the corresponding location in the destination spectrum. Since it is looking for a nearby peak in the destination spectrum it uses the destination spectrum tolerances.
So why do the tolerances used differ for the two assignment copy methods? In the pointer method you select destination peaks to put assignments on. In the ac / ap command method you select source peaks to copy assignments from. That asymmetry is the basic reason why different tolerances are used.
The resonance list command rl shows a list of resonances for a specified condition. Each line shows a group name, atom name, average chemical shift from all assigned peaks, standard deviation, and the number of assignments made from all spectra. The list can be saved to a file. The list is not automatically updated when new assignments are made or peaks are moved. Press the update button to update the list. After selecting a new molecule / condition from the menu you need to press the update button to show the resonances.
Use the rename resonances (rr) dialog. If you want to change a group name fill in the old and new group names. Leave the atom names blank. To change an atom name for all groups fill in the old and new atom names and leave the group names blank. To change a specific resonance enter old and new atom and group names. Only resonances for the given molecule and condition are changed. If the condition is left blank then resonances for all conditions of the specified molecule are changed. If the condition and molecule is left blank all resonances for all molecules are renamed. In summary, leaving a field blank means apply the rename for all values of that field. You can delete resonances not used in any peak assignment by renaming them to nothing.
You can copy resonances from one molecule / condition to another. Use the "predefined resonances" command (pd). Copied resonances can be used to aid assignment of a new spectrum. They can be shown along the edges of views (vR) and appear in the list of resonances in the assignment dialog. And they are used when Sparky guesses assignments. Once a resonance is used in a peak assignment its frequency is computed from the average positions of the assigned peaks. To delete resonances that are not used in any peak assignment use "delete unused resonances" (dr). To delete only a few unused resonances, use resonance rename (rr) and rename them to nothing.
You can show your assignments as colored lines on a structure using Midas. There is a Midas dialog in Sparky (accelerator mi). You select a spectrum, PDB file, and line color. Sparky starts Midas and displays your assignments as lines between atoms. Some assignments will not be displayed because the assignment atom name doesn't match a pdb file atom name. When you select an assigned peak in Sparky, the corresponding line will be highlighted in Midas. Sparky peak lists can display the distance between atoms in an assignment and the peak lists can be sorted by this distance. By selecting an entry in the peak list, you select the peak and the Midas display will highlight the assignment. You can display assignments in Midas for different spectra in different colors. The lines representing assignments will be given a new Midas "model number". The lines can be displayed or hidden with the Midas commands "objdisplay model-number" and "~objdisplay model-number". When you show the same assignment from more than one spectrum the lines will be on top of each other and only one will be visible even if they are in different colors.
You can mark folded peaks with the correct frequency. This allows peak lists to display correct chemical shifts. It is also needed to compute correct average chemical shifts from all assigned peaks. To say that a selected peak really belongs off spectrum shifted one sweepwidth down field along the w1 axis use a1, or up field use A1. For axis w2 use accelerators a2, A2.
Spectra acquired in TPPI mode can create aliased peaks that are reflected about the up field or down field edge of the spectrum. The u1 command gives the selected peak an alias by reflecting the peak w1 position about the up field spectrum edge. Using the u1 command a second time removes the alias from the selected peak. The u2, u3 and u4 commands mark selected peaks as aliased in the w2, w3 and w4 dimensions. The d1, d2, ... commands perform the reflection about the down field edge of the spectrum.
To center a peak at the local maximum use "peak center" (pc). This uses quadratic interpolation to position the peak to a resolution finer than one data point. If you want to type in the position select a peak and use the ornament properties dialog (ot).
The most accurate linewidths are obtained by integrating with Gaussian or Lorentzian fitting. This can be inconvenient because fitting sometimes fails. The "estimate linewidth" (pe) command gives full width at half the peak height for all selected peaks. This command first centers the peaks at the local maxima. You can manually set linewidths using the ornament properties dialog (ot). The linewidths can be seen in peak lists. Instead of looking through a peak list you can have the linewidth displayed in a status bar at the bottom of the view window when the pointer is over a peak. Use show peak info (vp) to turn this status bar on or off.
You can define a set of selected peaks as a peak group (pg). Peak groups have a volume and an average position weighted by the peaklet volumes (if integrated). They are intended to represent multiplet peaks.
You can do two types of integration. The preferred method is to fit peaks to Gaussian or Lorentzian functions and get the volume from the fit height and linewidths. In cases where this doesn't work you can sum up the data heights at each point in a box or ellipse surrounding the peak. You choose the box or ellipse by dragging out the region with the mouse while in the "integrate" pointer mode. For the fitting method you can also use the "integrate" pointer mode and drag a region around the peaks to integrate or you can select the peaks and use the "peak integrate" command (pi). You set the method of integration using the integration dialog (it). In rare cases you might want to set the peak volume by hand. For instance, if you have a doublet peak and one component is overlapped you could integrate the unoverlapped part and manually double the volume. You type in the volume value by selecting the peak and using the ornament properties dialog (ot).
When you integrate by Gaussian or Lorentzian fitting you need to specify the data to use for the fit. The default is to use data above the lowest displayed contour level. There is a switch in the integration settings dialog (it) to use data points within a rectangle drawn with the mouse. This is only possible for 2-D spectra. You can also select data both within a rectangle and above the lowest contour.
If the lowest contour contains more than one selected peak and the "grouping method" in the integration dialog is set to "common contour" then all the selected peaks within the contour will be fit simultaneously. That is the positions, heights and linewidths for all peaks are adjusted concurrently to achieve the best fit to the data. If you don't want peak positions or linewidths to change, switch off "Allow peak motion?" and/or "Adjust linewidths?" in the integration dialog (it). Even if peaks do not lie within the same contour they can be simultaneously fit if they are within a specfied distance of one another. You turn on "Group close peaks?" in the integration dialog and specify a maximum distance (in Hz) for each axis. Two peaks are grouped if they are within the specified distances along all axes.
If you are fitting a peak that is close to another peak that has already been fit you might want to turn on "Subtract fit peaks?". This subtracts the fits of other peaks from the data before fitting the new peak.
The "Fit baseline?" option adjusts baseline offset and slope parameters when doing the fit. For this to work well you need to use data around the base of the peak. It is convenient to set "Use data within rectangle?" on and "Use data above lowest contour?" off when fitting baselines.
If a peak has been successfully integrated, the peak marker has a circle drawn around it. The fit linewidths and volumes and residual errors can be inspected in a peak list. This information is also output to the main Sparky window when the integration is performed. To see the fit and data in 1-D cross-sections turn on slice panels. The slices do not show the baseline fit (because each fit can have a different baseline). Only the Lorentzian or Gaussian part is shown. To judge whether the baseline fit is good you can have the 1-D slices show the difference between the spectrum data and the Lorentzian or Gaussian shape (sf). What is left should be a smooth baseline. You can also have the contour plot show the spectrum data with peak fits subtracted (vf).
Each spectrum has its own set of integration settings. You can select the spectrum at the top of the integration settings dialog. There is currently no way to change the settings for all spectra at once. Remember that when you change a setting you must press the Apply button or the Ok button for the change to take effect.
The fit procedure uses an iterative procedure to minimize the sum of the squares of the errors between the fit curve and spectrum data. The iterative procedure can move peaks far away or give them unreasonable linewidths. To prevent this you can specify the maximum distance any peak should be moved along each axis. And you can specify upper and lower bounds for linewidths. You can also handle this by turning off "Allow peak motion?" and "Adjust linewidths?". You can copy linewidths and positions from other peaks with the same assignment that have already been integrated using the copy linewidths (cl) extension.
If you try to simultaneously fit the linewidths, positions and heights of a group of more than 5 peaks (25 degrees of freedom) be prepared to wait a while. You might hit the cancel button that appears while the fit is being calculated, raise the lowest contour level (ct) so that the group separates into smaller groups, and retry the integration. Or you can integrate by the box or ellipse method.
If the lowest contour enclosing a peak encompasses a giant region, for example, if it includes all the diagonal peaks, then the integration will fail with a message about the contour being too big. You can raise the contour level to make the region small. Or you can turn on "Use data within rectangle?". If a peak is below the lowest displayed contour (ie. has no contour surrounding it) then it will not be integrated if the fit uses only data above the lowest contour because in this case there is no data to fit to. Lower the contour levels or turn on "Use data within rectangle?".
The unintegrate command pU erases the volume and linewidth of a peak. You might use this on peaks whose volume seems unreliable because of overlap. By unintegrating you can eliminate questionable volumes from peak lists.
You can place labels on peaks that are not assignment labels. These labels can contain any text you want. Select a peak and use the peak label command (pl). Or select the "add label" pointer mode and click on peaks to label them. A dialog will come up for you to type in the label.
To automatically have labels in the current view moved so they do not overlap one another or peak markers use the unoverlap labels command lu. Each visible label is moved by small amounts in the direction (up, down, left or right) which minimizes its overlap with other labels and peak markers. This procedure is iterated to unoverlap all labels. If you are not satisfied with the results you can immediately move the labels back with the undo command eu. Note that in 3 or 4 dimensional spectra arranging the labels to be non-overlapping in one plane usually makes them overlap when viewed in other planes (because additional labels become visible). This command does not know to avoid overlapping the arrows connecting assignment labels to peaks.
The right offset labels command lr moves all visible peak labels to the right of their peak markers. The gap between the left edge of the label and the center of the peak marker is twice the peak marker size. Use the undo command eu immediately after to move the labels back to their original positions if you don't like the results.
Use the peak list command (lt) to bring up a list of all peaks in a spectrum. If there is already a peak list for the spectrum its window will be raised on top of all other windows. To force a second peak list window to be created for a spectrum use the new peak list command nl. Peak lists can display assignments, chemical shifts, volumes, linewidths, signal to noise ratios, data height, deviation from average resonance frequencies, .... Press the Options button to change the set of fields displayed. Use the Save button to write the list to a file. You will probably need to produce peak lists in a precise format for input to other programs that calculate molecular structures. You can either massage the peak list file using your favorite tool (Perl, awk, Tcl, vi) or you can write a Sparky extension in the Python language to directly output the desired format.
Lines in a peak list are highlighted if the peak is selected. Clicking on a peak list line will select that peak. Double clicking on a peak list line will cause a view to center on that peak. And selecting a peak in a view will cause peak lists to scroll to that peak.
You can display a peak list containing peaks from all spectra that are assigned with a given resonance. There are several ways to get this list. You can press the Resonance Peaks button in the assignment dialog (at). You can use the command r2 which bring up the list with for the w2 resonance of the currently selected peak. The commands r1 and r3 do the same for axes w1 and w3. If you click on a chemical shift in an assignment table (tb) the list for that resonance is shown.
There is a peak list option called "Pair crossdiagonal peaks?" If you turn this on, peaks in 2-D homonuclear spectra that are assigned on both sides of the diagonal are placed on adjacent lines in the peak list. This facilitates comparing volumes or other properties.
Sparky peak lists can be output to a file in MARDIGRAS or DYANA format. You select "Mardigras format" or "Dyana format" from the peak list options dialog. Turn off the display of all other fields unless you want these in the output file. The DYANA format puts the peak "note" in the last column which is intended to indicate "weak", "medium", or "strong". There will be blank lines in the list for unassigned peaks. These are place holders. Each peak in a spectrum always occupies a line in the peak list even if no data is displayed. Blank lines are filtered out when you write a peak list to a file.
Use the find/add peak pointer mode (F8) to pick peaks. Clicking on a point in a spectrum view will place a peak marker there. Dragging a box will place peak markers at all peaks satisfying a minimum height and minimum linewidth requirement. You can pick peaks over the whole spectrum using the region dialog (rt). The height and linewidth thresholds are set with the peak picking dialog (kt). Separate height thresholds are set for positive and negative peaks. If the height threshold is below the lowest contour level then the contour level is used as the threshold. The linewidth for a prospective peak is computed as the half height width.
You can draw noesy walks using lines. Select the "add line" pointer mode. Now click on a position to start a line and another position to end the line. Lines are forced to be vertical or horizontal. Grids are lines that extend from edge to edge of a spectrum and are intended to be used for looking at alignments. Select the pointer mode "add grid horz", "add grid vert", or "add grid both" and then click on a point to place a grid. Lines and grids appear in all views of the spectrum on which they are placed.
"Ornaments" are peaks, labels, lines, grids, peakgroups, ie. spectrum annotations. You can change their color and size using the ornament dialog (ot). You can lock peaks (pk) so that they are not moved during integration. You can attach notes (nt) to peaks to record unusual features. The notes can be displayed and searched for in peak lists.
If Sparky doesn't do what you want you can write your own extension in Python. You can also make use of extensions that other people have written. If you want to do something similar to what an existing extension does you can customize it.
New developments in Sparky are often done in Python. Core features are implemented in C++. Python is simpler than C++ and is interpretted so an extension can be added or modified without building new Sparky executable. Some of the extensions below are inconveniently slow, their reliability is lower than the core C++ features, and they are more likely to be changed in future releases than are core features. In spite of these drawbacks many do tasks that cannot be readily done using only core features.
An important limitation of all current Python extensions is that they are not updated when you add or delete spectra from your project. This means if you use an extension (say restricted peak picking) which displays a spectrum menu, and subsequently load a new spectrum, it will not appear in the menu. To work around this problem you can destroy the window with the spectrum menu (using the close button on the window frame, not the close button at the bottom of the window), and then display the window again with the appropriate Sparky command. This causes a new window and menu to be created with the full list of spectra.
Errors that occur in a Python extension generally do not cause Sparky to crash. Instead the Python shell window pops up and displays a stack trace. The stack trace shows exactly what functions in which files of Python code were executing when the error occurred. The last line indicates the type of error. For instance, if you mistype a PDB file name to an extension it may fail with an I/O error indicating the file could not be found. Many of the Python extensions do not adequately check their input and catch such problems. In these cases looking at the last line of the stack trace may indicate what caused the problem.
Extension | File | Description |
---|---|---|
AutoAssign (aa) | autoassign.py | Run protein backbone automatic assignment program AutoAssign |
Assignment distances (ad) | distance.py | List assignments with far atoms, peaks with multiple close atom assignments, close atom pairs with no assignment, ... |
Atom name translation (ax) | atomnames.py | Show translations used to convert non-standard atom names to standard names. |
Center view setup (cv) | centerview.py | Center spectrum view on mouse position or peak in another view. |
Chemical shift plot (cs) | chemshift.py | Plot chemical shifts for atoms |
Chimera molecule view (km) | chimeraview.py | Display molecule and restraint violations with Chimera |
Copy peak linewidths (cl) | copylinewidth.py | Copy peak linewidths and positions |
CORMA simulated spectrum (cx) | cormaspectrum.py | Create a simulated NOESY spectrum using CORMA predicted peak intensities |
Linewidth plot (lp) | linewidthplot.py | Plot linewidths for peaks for each resonance |
Midas atom picking (ma) | midaspick.py | Pick atoms using Midas 3D display and show peaks |
Midas constraints (mc) | midasconstraint.py | Display Mardigras constraint violations using molecular display program Midas |
Mirror peaks (md, mp) | mirror.py | Find mirror peaks in HSQC-noesy spectra |
Molecule sequence (sq) | sequence.py | Enter molecule sequence for use by other extensions |
Peak list (LT) | peaklist.py | List peak assignments, volumes, linewidths, PDB model distances, Mardigras distance bounds, Corma predicted intensities, ... |
Peak table (pb) | peaktable.py | List peaks with columns for several spectra |
Python shell (py) | pythonshell.py | Shell for typing Python commands and display errors |
Read peak list (rp) | readpeaks.py | Read a peak list from a file and create peaks on a spectrum |
Relaxation peak heights (rh) | relax.py | Produce a table of peak heights for a set spectra for use in calculating relaxation time constants. |
Reposition sequence (rs) | reposition.py | Reposition assigned protein fragment using chemical shift statistics |
Restricted peak picking (kr) | restrictedpick.py | Pick peaks using peaks from another spectrum as a guide |
Shift resonances (mv) | movepeaks.py | Move one assigned peak and have all other peaks on resonance lines moved by the same amount. |
Spectrum labelled axis (la) | axes.py | Specify spectrum proton axis labelled by a heavy atom |
Spectrum type (sy) | spectrumtype.py | Specify the type of the selected spectrum |
Spin graphs (sg) | spingraph.py | Show a diagram of atoms connected by lines, one line for each assigned peak |
Spin graph assigner (ga) | assigngraph.py | Explore possible assignments using spin graph display |
Strip plot (sp) | strips.py | Show strips of 3-d spectra in a single window |
Volume errors (ve) | volumeerror.py | Set volume error estimates based on several criteria |
Setup and run automatic assignment program AutoAssign (aa).
This extension is not usable unless you have obtained the AutoAssign "ascii client" program. This is not part of the standard AutoAssign distribution. It allows Sparky to run AutoAssign without invoking the AutoAssign graphical user interface.
AutoAssign is a program that does protein backbone assignment. It was developped by Gaetano Montelione's group at Rutgers. It is not part of the Sparky distribution. You can get it from http://www-nmr.cabm.rutgers.edu/software. It takes lists of picked peaks from a 2D N15 HSQC spectrum and the following 7 triple resonance spectra: HNCO, HNCACB, CBCA(CO)NH, HNCA, CA(CO)NH, HNHA, HA(CO)NH. The following paper describes the program. "Automated Analysis of Protein NMR Assignments Using Methods from Artificial Intelligence", J. Mol. Biol. (1997) 269, 592-610. The paper tested the program on six proteins ranging in size from 58 to 121 amino acids. In all cases almost all assignable resonances (more than 90%) were correctly assigned.
This Sparky extension exports the peak lists needed by AutoAssign, runs the program (taking seconds to minutes), imports the calculated resonance assignments, infers peak assignments, and displays the peak assignments using the spin graph assignment tool. Eight files containing peak lists and a spectrum table file are written and passed to AutoAssign. You specify the table file path. The peak list files are created in the same directory. The peak list file names use the Sparky molecule name and the spectrum name and a .pks suffix. All picked peaks in the 8 spectra are exported to AutoAssign. The restricted peak picking extension is useful for creating intial peak lists for the triple resonance spectra. The previous peak assignments for the 8 spectra are deleted and the new calculated assignments are made to the Sparky peaks. You can inspect the assignments using the spin graph display, add or remove peaks to fix problems and rerun AutoAssign. Or you can use the calculated assignments as a starting point for manual assignment.
You must have the AutoAssign ascii client in your execution search path before you run Sparky. It should be executable as ascii_autoclient. Also the AutoServer program must be in your search path.
The 8 spectra needed by AutoAssign must be opened in Sparky. This extension tries to identify the 8 spectra by comparing their Sparky names to a list of spectrum types n15hsqc, hnco, hnca, hncoca, caconh, hncacb, cbcaconh, hncocacb, hnha, haconh, hncoha, .... This may incorrectly identify the type of some of the spectra. You can override the guessed spectrum types using the spectrum type dialog. If you try to run AutoAssign and not all the spectra are identified an error message is displayed. If there is more than one spectrum of a type needed by AutoAssign this will also be reported as an error. For example, if you have two hnco spectra open in Sparky AutoAssign will not be run. Currently there is no way to specify which should be used. The way to proceed is to close one of the spectra.
AutoAssign is able to handle spectra folded in the N15 dimension but this is not currently supported by this Sparky extension.
Use atom distances to check noesy assignments (ad).
You can list assignments with protons farther apart than a specified distance, peaks with more than one assignment where the resonance lines are close and atoms are close, all pairs of close atoms having no assigned peak, unassigned peaks for which reasonable assignments exist, .... This works for 2-D noesy and 3-D hsqc-noesy spectra.
Atom coordinates are read from a PDB file. If a Sparky atom name does not match a PDB file atom name then assignment distances involving that resonance are not available. This extension is currently not able to translate atom names. To get distances for all assignments you can make a PDB file that uses your Sparky atom names.
Show atom name translations used in converting Sparky atom names (ax), PDB file atom names, Mardigras file atom names, ..., to standard atom names.
Some Sparky extensions need to compare atom names from different sources. For example, the Python peak list extension (PL) can show proton-proton distances for assigned peaks calculated from a PDB model. If the atom names used in the PDB file do not exactly match the atom names used in Sparky assignments then translations need to be done to match the names. The spin graph extension tries to display residues using standard templates. For this to work the Sparky atom names must be matched to the standard atom names for which the templates are defined. The mirror peak extension needs to determine the name of the heavy atom attached to Sparky assigned protons. It finds the heavy atom name by looking up the proton atom name in a table based on standard atom names.
Sparky attempts to accomodate minor atom name variations, for example, GLY <-> G and and HN <-> H and HB2 <-> 2HB and H2" <-> H2'2, It does this by defining a set of standard names and translations between non-standard and standard names. When a new source of atom names is read (eg. PDB file, Mardigras constraint file, Corma predicted intensities file, ...) Sparky guesses what translations to apply. Translations define a one to one mapping between the non-standard and standard names. They are used to compare atom names and also when lookup in standard atom tables is needed (eg. to determine attached heavy atom, or determine atom layout for display of a residue).
The atom name translation dialog (ax) shows what translations are being used for each set of atom names (PDB files, Sparky names, ...). Initially Sparky guesses the translations to use. The dialog lets you select a different set of translations and lets you see what atom names are not recognized and not translated to standard names.
The translations are defined in the file atomnames.py. You can copy that file to your ~/Sparky/Python directory and add additional translations following the instructions and examples in that file.
There are many limitations of the atom translation facility. Here are a few.
With the center view dialog (cv) you choose a spectrum window to be centered by subsequent uses of the center on mouse (cm) and center on peak (cp) commands. The center on mouse command will center the prespecified view at the current mouse position. The center on peak command centers the prespecified view on the selected peak. If "center when peak selected" is turned on, then selecting a peak causes the specified view to center without typing any command. When the peak or mouse position comes from a spectrum other than the one to be centered then a correspondence is made between the spectrum axes. Each axis of the view to be centered is matched with the axis of the source spectrum having the same nucleus type. If more than one axis in the source spectrum has matching nucleus and one of the matches has the same axis number (w1, w2, ...) then that axis is used. In other cases no correspondence is made with the axis of the centered spectrum and so that axis does not get centered.
There is a simpler view center command vc that centers the spectrum window it is typed in instead of centering a pre-specified window as the above described commands. The vc command centers at the position of the selected peak. All of the view centering commands can be used between spectra of different dimensions (eg. select a 3D HNCA peak and center 2D N15-HSQC spectrum).
Plot resonance lines by group/atom type (cs).
Plot resonance frequencies as tick marks along a horizontal scale. Each group/atom type is plotted on a separate line. Only resonances in the specified ppm range are shown. A subset of atoms to show can be specified as a comma separated list of atoms or groups and atoms (eg. H2', C H5, K CD, N).
Display molecule and restraint violations using Chimera (km).
Chimera is a molecular display program developped by the Computer Graphics Lab at UC San Francisco. It is the successor to their Midas and MidasPlus molecular display programs. An alpha release is out as of May 1999. This extension uses Chimera to display a model and restraint violations. The restraints are read from a file in Mardigras format. Mardigras is a program to compute NMR distance restraints from NOESY peak intensities using complete relaxation methods. It was developped by Tom James' NMR group and UC San Francisco. With the alpha release of Chimera it is necessary to have Chimera start Sparky for this extension to work. This is because it is not yet possible to start Chimera as a Python extension using the normal Python mechanisms. So it is necessary for Chimera to start Sparky as a Python extension. This is done with the following command:
% chimera /usr/local/sparky/python/start_in_chimera.py
You select a PDB file and a Mardigras restraint file. You can show satisfied and / or violated restraints as colored lines connecting pairs of atoms. Red restraint violation lines indicate the pair of atoms are separated by more than 1.2 times the restraint distance upper bound. Magenta lines indicate a violation of in the range of 1.0 to 1.2 times the upper bound. Cyan lines indicate an atom separation of .8 to 1.0 times the lower bound distance. Blue lines indicate atoms closer than .8 times the lower bound distance. Satisfied restraints are shown as green lines. The interface does not allow you to change these colors. The atoms for which you have resonance assignments are colored by a color of your choice. Select restraint lines in Chimera (hold control and press the left mouse button) and the currently selected spectrum will be centered to show the corresponding peak. A status line in the Sparky extension dialog reports what restraint was selected and gives an explanation if the spectrum could not be centered (for example, because chemical shifts are not known). When you select a peak the corresponding restraint line is highlighted if one exists. If one does not exist a blue line is created and highlighted provided the two atoms associated with the peak assignment can be identified. Atom identification uses the atom name translation facility. Assignment names that refer to more than one atom (eg methyl group ALA MB) are not matched to any molecule atom. Restraints involving such NMR pseudo-atoms are not shown.
Copy peak linewidths and positions to aid peak fitting (cl).
The positions and linewidths of selected assigned peaks are set to the average position and linewidth along each axis from other peaks in the spectrum having the same assignment on that axis. This is intended to be used to help fit overlapped regions. You assign peaks in an overlapped region and set their positions and linewidths from other (better resolved) peaks with like assignments. Then you fit the overlapped region by adjusting only peak heights. In practice, not all of the overlapped peaks will be assigned and there will be assignments for which there is no other peak in the spectrum with a known linewidth. The copy linewidth command sets the linewidth to zero along the axes for which no linewidth is known. Zero linewidths are always adjusted in the fitting procedure, even when the "Adjust linewidths?" option turned off.
Create a simulated NOESY spectrum using CORMA predicted peak intensities (cx).
This command creates a simulated 2D homonuclear NOESY spectrum from predicted peak intensities. The peak positions and linewidths are derived from a specified assigned NOESY spectrum (ie. experimental data). The simulated peak intensities are read from a file in CORMA format. Here is a sample of this file format:
ATOM1 ATOM2 DISTANCE RATE Icalc Iobs error H1' 4 2H2' 4 2.357 -4.97628 0.11698 0.06497 0.05201 **** H1' 4 H8 41 3.989 -0.21205 0.03088 0.03152 -0.00064
The header line is necessary and there can be lines preceding the header which are ignored. The column locations are significant (this is Fortran style output). The simulated spectrum extension expects the first atom name in columns 1-4, first residue number in columns 5-7, second atom name in columns 9-12, second residue number in columns 13-15, and the predicted intensity in columns 36-45. All other columns are ignored.
A peak is made in the simulated spectrum for each entry in the CORMA file provided a position and linewidth can be determined from the specified experimental NOESY spectrum. The position is found by looking for assigned resonances for the two atoms. The atom name translation facility is used to match the atom names in the CORMA file with the Sparky assignment names. The linewidths are derived from assigned peaks in the experimental NOESY spectrum. An average linewidth is calculated for each resonance separately for each spectrum axis using all assigned peaks in the experimental spectrum for which linewidths are known. If no peak linewidth is available from the experimental data for a resonance along one of the axes, then the default linewidth specified in the dialog is used. If the default is zero no simulated peak will be created in this case. The peak intensity (ie volume) from the CORMA file is divided by the product of the linewidths and multiplied by a scale factor 1e6 to produce a peak height. This normalization is of course arbitrary so the resulting peak heights cannot be directly compared to experimental peak heights. The peaks in the simulated spectrum are Gaussian and truncated beyond 5 standard deviations. There is no noise added. The simulated spectrum file is a normal UCSF format spectrum file which can be opened in Sparky. This extension writes the file but does not open it in Sparky. Comparison can be done by overlaying the simulated spectrum on the experimental spectrum.
The above described extension uses a program peaks2ucsf that comes with Sparky to create the simulated spectrum file. You can use this program directly to create other simulated data sets. The parameter file that describes the desired spectrum and peaks is illustrated below. (This is the documentation displayed when you run peaks2ucsf with no arguments.)
Syntax: peaks2ucsf output-file < parameter-file Creates a UCSF format spectrum file from a list of Gaussian peaks. The parameter file has the following format. 2 # dimension 1024 2048 # matrix size 8.37 9.21 # ppm at index 0,0 H H # nuclei (H, N or C) 500.123 500.123 # nucleus frequencies (MHz) 4000.732 5200.183 # spectral widths (Hz) 4.37 2.15 1.95e6 13.2 15.1 # Gaussian center (ppm), height, linewidth (Hz) . . .
Plot peak linewidths for each resonance (lp).
This extension is similar to the chemical shift plot but displays peak linewidths for each resonance. Each row in the plot corresponds to one resonance. The horizontal axis is linewidth and tick marks are placed to show the linewidth of each peak assigned with that resonance. The linewidth for just one of the spectrum axes is displayed. You specify which axis in the dialog. This helps you examine whether peak linewidths for a resonance are all the same as expected. It can identify integration errors by showing abnormally large or small linewidths. It can also be used to view linewidth variation for different resonances giving an indication of atom dynamics.
You can click on the individual tick marks and the corresponding peak will be centered in a spectrum window. You can limit the plot to certain atoms. You enter these in the dialog as a comma separated list of simple atom names (eg HA, HB), or residue symbol and atom name separated by a single space character (eg G HA, V HB).
Recenter spectra to show peak for a pair of atoms chosen in a 3D model (ma).
Once you have started Midas using the Midas constraint dialog (mc) you can select pairs of protons on the 3D model and have the selected spectrum recenter to the location where a crosspeak for the atom pair should appear. You turn on the "Show peaks?" switch in the atom picking dialog (ma). After selecting a pair of assigned protons the currently selected spectrum is automatically recentered to the relevant spectrum region. This works for 2D noesy and 3D noesy-hsqc spectra. The atom picking dialog also has switches to automatically label each picked atom in Midas, to show distances between picked pairs of atoms, and to show all assigned atoms (in yellow).
Display Mardigras constraint violations using molecular display program Midas (mc).
A PDB model and Mardigras constraints are displayed using Midas. This is similar to the Midas delegate NOEShow with fewer features. Violated distance constraints are show as colored lines connecting atoms. Distances less than .8 times the lower bound are shown in blue, .8 - 1.0 times the lower bound are shown in cyan, greater than 1.2 times the upper bound are shown in red, 1.0 - 1.2 times the upper bound are shown in magenta, and satisfied constraints are shown green.
Use mirror peaks to help make assignments of 3-D labelled noesy spectra.
For a pair of close protons H1, H2 you expect two hsqc-noesy peaks. One corresponds to the two protons and the C13 or N15 attached to the first proton, and the other is for the two protons and the C13/N15 attached to the second proton. To check a proposed assignment for a peak you can look to see if the "mirror peak" (the other peak associated with the pair of protons) exists. This code helps you look for mirror peaks. For each possible assignment it lists the signal/noise at the mirror peak location and allows you to jump to that place in the spectrum.
To find mirror peaks, this code must be able to lookup the attached heavy atom for any proton. In order to do this your Sparky atom names must be recognized. They must either be the standard names used by Sparky extensions or you must define translations between the atom names you use in Sparky and the standard atom names.
Enter molecule sequence for use by other extensions (sq)
The sequence is specified as a string of one letter amino acid or nucleic acid codes. White space characters (space, tab, newline) are ignored and lower or upper case can be used. You specify the number of the first residue. It is not possible to put breaks in the numbering sequence. Instead of typing in or pasting in the sequence you can specify a file which contains the sequence string. The file must contain only the sequence string.
List peak assignments, volumes, linewidths, PDB model distances, Mardigras distance bounds, Corma predicted intensities, ...
This extension is similar to built-in Sparky peak lists but will show fields not supported by the built-in peak lists. PDB model distances for multiple models can be shown for each assigned peak. Fields for Mardigras distance bounds and Corma predicted peak intensities can also be shown. The Corma intensities are shown as an absolute intensity and as a fraction of the peak volume. The intensities are normalized to make the average fractional value equal 1. Data will not be displayed when PDB, Mardigras, or Corma file residue and atom names do not exactly match Sparky residue and atom names.
The peak list initially shows no fields. Press the Setup button to select fields. Unlike built-in peak lists, these lists are not updated when properties of the peaks (volume, position, ...) are changed. To update the list you must press the Update button.
List peaks from several spectra on one line
You select one or more spectra and a table is shown where the rows are assignments and the columns are different spectra. An entry indicates whether the assignment has been made in that spectrum. The entry can be 'yes', 'no', '.', or the peak volume if the peak has been integrated. A '.' entry means one of the resonances has not been determined for the that spectrum condition. Clicking on any entry will select the peak in the corresponding spectrum. Double clicking on an entry recenters the spectrum to show the peak position (or where the peak should be if no assigned peak exists).
The 'Noesy Format?' switch changes the format of the table. The assignment is displayed as a pair of protons in Mardigras format. Peaks above and below the diagonal and peaks from 3-D noesy spectra are combined on a single row.
The Python shell window lets you type commands to the Python interpretter and displays their output. Refer to the Python documentation to see what kinds of commands you could type here. Invoking a Sparky extension from the Extensions menu or with a two letter accelerator causes the associated Python command to be sent to the Python shell. If an error occurs in an extension the shell window is displayed and a long and ugly and very useful stack trace tells exactly where the error occurred. You turn off the automatic shell window display using the switch in the preference dialog. This is accessed by clicking the preferences button at the bottom of the shell window.
Make peaks on a spectrum from a peak list file (rp).
Peaks are read from a peak list file and placed on the selected spectrum. The file should contain a line for each peak. The line should have an assignment followed by chemical shifts for each axis. For example
C2H5-G1H1 5.395 6.030
The assignment can contain ? components. It can omit a group name for a component -- the shorthand G1H1'-H2' where the second group is omitted is equivalent to G1H1'-G1H2'. The residue name is separated from the atom name by looking for a residue number followed by one of the letters H, C, N, Q, or M. Extra columns are used to set the peak note. Peaks for 3-D or 4-D spectra can be read.
This rh command lets you create a table of peak intensities for a several spectra. It was intended to collect data for fitting exponentials to calculate relaxation time constants. When you first invoke rh a dialog appears. You choose the spectra you want intensities for. Then you select a peak or peaks and when you type rh a line is added to the list of peaks. The line lists the peak assignment and intensities for each spectrum. The spectrum intensities are listed in the order in which you initially selected the spectra. If a peak marker with the same assignment as the selected peak does not exist in any of the chosen spectra then it is created. When a new peak marker is created it will automatically be centered if the "Center new peaks?" check button is on. Instead of peak heights you can choose to put volumes in the peak list by turning on the "Show volumes?" check button. This requires that the peaks are already integrated. Peak integration is not done automatically. The list can be saved or appended to a file with the Save and Append buttons for subsequent fitting with other software. The list is cleared with the Clear button.
Reposition assigned protein fragment using chemical shift statistics (rs).
This extension helps determine the correct sequential position of a stretch of assigned protein backbone resonances. You specify a numeric range of residues. Every possible repositioning of the resonances for these residues up and down the sequence is considered. For each position the deviation of the resonance chemical shifts from the expected shifts based on residue and atom type is determined. A score describing how well the assignments fit at this sequence position is calculated based on a database of expected shifts. The positions and scores are displayed in a list ordered from best to worst score. This list is produced by pressing the Positions button. You can select a line in the list and press the Move button to update all peak assignments involving the moved resonances.
The chemical shift statistics come from BioMagResBank and reflect an average of assigned resonances for all proteins in their database. (Resonances where unusual chemical shift referencing was used, or that are outside 8 standard deviations, or that are aberrant in other ways were excluded. The actual data used is in the Sparky Python file shiftstats.py and contains more details.) Each database residue/atom shift has a standard deviation. The score listed by the repositioning extension is obtained by averaging for all moved resonances the magnitude of the difference between experimental and expected shift divided by the standard deviation for that expected shift. So a score of 1.0 means that at the new sequence position the experimental shifts on average are 1 standard deviation from the expected values. The list also has a column called Mismatches. A mismatch is where a resonance does not make sense in the new sequence position. An example is moving a CB to a glycine residue (which has no CB atom). If you move assignments to a location where there are mismatches the resonances are moved and resonances not normally defined for a residue will be made. Another column in the scored positions list is called Collisions. A collision is where a moved resonance lands on an already assigned resonance. It is inadvisable to move assignments onto already assigned resonances (ie when there are collisions). It only makes sense to do so if the chemical shift of the destination is the same as that of the resonance being moved.
In addition to scoring all possible sequence positions for a segment of residues, you can list individual chemical shifts and their deviations from database values. This is done by pressing the Shifts button at the bottom of the dialog. The shifts for all resonances in the specified range of residues are listed as well as the expected shift and deviation from the expected shift in standard deviation units. Also the number of peaks assigned with each resonance is shown. Expected chemical shifts are not shown for atoms with non-standard names.
The restricted peak pick command kr automatically picks peaks using existing peak markers from another spectrum as a guide. For example you can pick peaks in a 3D HNCA spectrum (correlating amide proton and nitrogen and alpha carbon) using already picked peaks from a 2D N15-HSQC (correlating amide proton and nitrogen). Only peaks in the 3D spectrum which have nearly the same 1H and 15N shifts as a peak in the 2D spectrum would be found. The advantage of restricting the search is that lower picking thresholds can be used. More real peaks and fewer noise peaks will be found. And the search is much faster. Other useful cases include picking 3D N15-NOESY peaks restricted with 2D N15-HSQC peaks, or picking 3D HCCH-TOCSY peaks using 2D C13-HSQC peaks. Another useful case is picking 3D HNCACB peaks using already picked 3D HNCA peaks. The HNCACB spectrum is just like the HNCA only it sees beta carbons in addition to alpha carbons. Because it has lower sensitivity you can first pick HNCA peaks and then pick HNCACB peaks that are near HNCA peaks using low thresholds.
The kr command shows a dialog where you specify the spectrum to be peak picked and the reference spectrum. Only the selected peaks in the reference spectrum will be used. You specify which axes of the pick spectrum will be restricted to have shifts near reference peaks. And you specify the allowable deviation in ppm for each reference axis. Pressing the Pick Peaks buttons will then search for peaks using the selected peaks in the reference spectrum. The minimum pick heights and linewidths used are exactly the same as the ones used in manual peak picking. They can be set with the peak pick thresholds command (kt). There is also a Select Peaks button which just selects existing peaks in the pick spectrum using the selected reference peaks to narrow the search.
Technical note / known bug: A corridor around each reference peak position is searched in the pick spectrum. Because this corridor is in index units (rather than ppm units) peaks may be found that are outside the specified ppm range by up to half a spectrum index unit or peaks inside the ppm range can be missed that are half an index unit inside the specified ppm range.
Move one assigned peak and have all other peaks along its resonance lines moved by the same amount (mv).
This is used to assign a new spectrum taken under new experimental conditions when a previous spectrum has already been assigned. You can select all peaks from the old spectrum (pa) and copy and paste them to the new spectrum (accelerators oc and op). Then start this tool and move a peak for each resonance line to its shifted location.
For each resonance in the assignment of the hand moved peak all other peaks in the spectrum assigned with that resonance are located. For each peak with this resonance the corresponding peak in the old spectrum is found and the new peak is shifted relative to the old peak to match the size of the shift for the hand moved peak. The reason the shifts are referenced to the old spectrum is as follows. Suppose you move some peaks without using this tool. Then you turn this automatic peak mover on. Now if you move a peak, other peak markers that you already moved by hand would be moved away from their correct locations. This is not what you want. By referencing the shift to positions of the peaks in the old spectrum this problem is avoided.
Specify spectrum proton axis labelled by a heavy atom (la)
This dialog allows you to specify the proton axis labelled (ie. directly attached to) a heavy atom axis of 3D spectra. It applies to spectra such as HSQC-NOESY or HNHA where there are two proton axes and one heavy atom axis. You identify which of the two protons is attached to the the heavy atom. This is needed by some extensions (eg. the AutoAssign extension) to correctly interpret the spectra. When such an extension needs this information it will ask so cases where you need to use this dialog are rare.
Specify the type of the selected spectrum (sy)
Some extensions need to know the type of a spectrum (eg. hnco, hcch-tocsy, ...). From the spectrum type and molecule primary structure what peaks are expected can be inferred. This is used by the spin graph assigner and AutoAssign extensions. The type of a spectrum is guessed by matching its name against a list of known types n15hsqc, hnco, hnca, hncoca, caconh, hncacb, cbcaconh, hncocacb, hnha, haconh, hncoha, .... If the spectrum name contains one of these type names then it is used as the type of the spectrum. If more than one type name is contained in the spectrum name then the longest match is used. If the guess is incorrect you can fix it with this command.
Show a diagram of atoms connected by lines, a line for each assigned peak (sg).
A spin graph is a diagram with vertices and lines connecting vertices. The vertices represent atoms and the lines represent NMR interactions. This extension shows spin graphs for assigned peaks. A peak in a 2-D spectrum is shown as a line between the two atoms. A peak in a 3-D spectrum is shown as two lines connecting the w1 and w2 axis atoms and the w2 and w3 axis atoms. Peaks in more than one spectrum are shown as different color lines. The graph is layed out based on templates for DNA, RNA, and proteins. In order to use the templates your Sparky atom names must be recognized. You can define translations between the atom names you use and the standard atom names used by Sparky extensions. You can print a diagram with the Save Postscript entry under the Commands menu. Only the region visible on the screen is printed.
Under the Spectra menu there are checkbutton entries for each loaded spectrum. Pushing in a button causes all peaks in that spectrum to be displayed. The color of the button matches the color of the lines in the graph. Deselecting a button undisplays the peaks for that spectrum.
The What... entry under the Layout menu brings up a dialog of controlling what type of atoms and peaks are displayed. This dialog will only appear when you have selected at least one spectrum to display. When you select a spectrum the residue labels for each residue is shown but not individual atoms. The Show Residue Atoms and Hide Residue Atoms buttons in the What to Display dialog show and hide all atoms. To limit the displayed atoms to certain types you can enter a space separated list of atom names. Also you can display only specified ranges of residues by entering ranges of residue numbers. The text labels identifying atoms and residues can be turned on or off. If an atom is not being displayed but the residue it belongs to has its label displayed then peak lines can be drawn to the residue label. This is controlled with the Lines to Residue Labels switch. If it is off then peaks assigned to undisplayed atoms are not shown. If you are displaying residue labels and lines between the residues, a single line can correspond to many peaks. You can display a numeric count of how many peaks is represented by that line by turning on the Peak Counts option. If you are displaying multiple spectra, the count includes lines from all spectra. There are switches to display or undisplay intra-residue, sequential or long range peaks. And there is an option to shade the intra-residue, sequential and long range lines in 3 distinct shadings emphasizing the intra-residue lines. After you have changed any of these options you need to press the Ok or Apply buttons for them to take effect. The Hide/Show Residue Atoms buttons have an immediate effect.
Label sizes, line thickness and spacing, and dot radii can all be set. This is done with the Sizes... entry under the Layout menu. This shows a dialog where numbers in units of screen pixels can be entered for all sizes. Label sizes represent height of characters. The line spacing parameter controls the offset between parallel lines of different colors. If the offset is 0 then the lines will be on top of each other and the top one will obscure any others. The line spacing should be greater than or equal to the line thickness to avoid parallel lines overlapping one another. There are checkbuttons to specify whether text labels should be automatically scaled as you zoom in and out.
The initial layout of the residues zig zags down the screen with increasing residue numbers to form a roughly square pattern. The first row goes left to right, the second right to left, ..., and so on. Choosing Row Layout under the Layout menu puts all residues in a single row from lowest residue number to highest. The scale is set so that the residue that takes up the most vertical space is fully visible using the current window height.
You can rearrange the layout of spin graph atom labels, atom dots, and residues with the left mouse button. Dragging a residue label moves all atoms in that residue. A box is drawn around these atoms while the left button is held down. If you want to move the residue label but not the atoms drag with the middle mouse button held down. If you click on a residue label but do not move it, its atoms are displayed or undisplayed. If you press the left button over a blank spot and drag a rectangle will be drawn. The spin graph will be zoomed to display the delimited region when you release the button. The vertical slider on the right edge of the spin graph window allows you to zoom in and out.
To reposition a sequence of residues drag a residue label using the right mouse button. When the button is depressed a yellow line will be drawn connecting the residues in sequential order. You drag the chain around like a piece of string and the drop it. You can chop your sequence up into smaller pieces for purposes of this string dragging operation. To do this press and release the right button on a residue label. The label will be highlighted in yellow. Now you can drag the string of higher numbered residues or the string of lower numbered residues. The highlighted residue label represents a break point and is included with the string of lower numbered residues. You can right click to make a number of these break points and drag the individual strings around. To eliminate a break point right click on the yellow residue label again.
You can save new layouts. When you load a layout from a file you should already be displaying a graph. Loading the new layout just repositions the atoms, it does not create the graph. This allows you to use the same layout for different spectra.
The atoms of a residue are initially positioned according to templates defined in the spinlayout.py file that is part of the Sparky distribution. You can use the Template... command under the Layout menu to interactively adjust the layout templates and create your own template file. Instructions are given in the Template... dialog.
You can click on a line with the left mouse button to select the corresponding peak. Using the middle mouse button selects the peak and centers a spectrum window and raises it to the top to show you the peak. If the spin graph shows peaks of several spectra in different colors then you can click on the individual parallel colored lines to select or show peaks from the different spectra. In cases where a line represents more than one peak, for example, a 2D noesy peak and its transpose peak, then one of them is arbitrarily chosen. If there is no line between two atoms and you wish to see the region of a spectrum where the corresponding peak would be click with the left button on each atom. The currently selected view window will be recentered so that the hypothetical peak would be in the middle. The selected atoms should be clicked in the w1, w2 axis order of the the current spectrum window. If you click them in the wrong order you will be shown the wrong region. If it lies outside the bounds of the spectrum it will be aliased onto the spectrum giving seemingly random positions. The same procedure works to show a region of a 3D spectrum. You left click on the 3 atoms in the w1, w2, w3 axis order. The top line of the spin graph windows indicates what atoms have been chosen.
Explore possible assignments using spin graph display (ga)
This extension helps you make protein backbone resonance assignments using spin graphs. A spin graph is a diagram showing atoms as dots and assigned peaks as lines between the atoms. You can click on an atom and a list of possible chemical shifts is shown. Under each candidate chemical shift is a group of peaks from different spectra which support the proposed assignment. The suggested chemical shifts for the selected atom are ordered to put the most probable assignment at the top. The ordering is based on the total number of peaks consistent with the proposed assignment. Each resonance assignment line also shows the number of standard deviations of this chemical shift from the average shift for this atom and residue type using statistics from BioMagResBank. The peak assignment lines show the peak position or the deviation (in ppm) from the resonance shift for each spectrum axis. You can select a resonance assignment line from the list and press the Assign button to make all the associated peak assignments. You can click on atoms which already have an assignment and press the Unassign button to remove all associated peak assignments and then examine alternatives. As you assign and unassign resonances the spin graph lines are updated to display the assigned peaks. This extension uses peaks that you have already picked in the spectra. It does not find new peaks that have not been picked.
The Setup button on the assignment graph dialog brings up a window for choosing the spectra to use and chemical shift tolerances. Only the following spectra for use in protein backbone assignment are supported: n15hsqc, hnco, hnca, hncoca, hncacb, cbcaconh, hnha, haconh. Information about what peaks are expected in each of these spectra is encoded in the experiments.py Python code that comes with Sparky. In the future (sometime after 5/99) I will add spectra for making protein side chain assignments and for assigning DNA and RNA. The type of each of your spectra is guessed from the spectrum name which is derived from the file name. If your spectrum name does not contain one of the above listed spectrum types then you will be asked to specify the spectrum type. If it does contain one of the above type names but this is not the correct type for the spectrum you will have to change it using the spectrum type command sy. After you press Ok on the setup dialog a spin graph window will appear showing the existing assignments.
Here are details of the algorithm that produces the proposed resonance assignments and lists of supporting peak assignments. When you click on an atom in the spin graph display all expected peaks (from the spectra chosen in the setup dialog) involving that atom are considered. For example if the atom selected is a protein backbone CA and an HNCA spectrum is being used then an intra-residue peak connecting the CA to the amide H and N of the same residue is expected and an inter-residue peak connecting the next residue's amide H and N to this CA is expected. For each expected peak a check is made to see if any of the resonances have been assigned. If any is assigned then all picked peaks in the spectrum consistent with those resonances (using the tolerances set in the setup dialog) are considered. Each such peak gives a possible chemical shift value for the CA you are trying to assign. At this point we have a list of peaks connecting already assigned resonances to the CA resonance you want to assign. Each peak suggests a chemical shift for the CA. For each of these possible CA shifts, the peaks that agree with the shift to within the setup dialog tolerances are collected. These are the possible resonance assignments and sets of supporting peak assignments that are displayed.
Since resonance assignments are only proposed using peaks that connect to already assigned resonances you must have at least one already assigned resonance to get started. To start I suggest choosing an HSQC peak and assigning it with the standard assignment dialog (at) to an arbitrary place along the sequence. It is best to put it not too close to prolines or glycines so that you will be able to extend your assignments without running into these difficult residues. After you have extended to assign a few residues you can reposition the assignments using chemical shift statistics with the sequence repositioning tool (rs).
To make all peak assignments for a proposed resonance assignment you select the resonance assignment line (the top line of the group) and press the Assign button. Some peaks in the group may already be assigned. These preexisting assignments are shown in the last column. These peaks will not be reassigned when you select a resonance assignment line and press the Assign button. You can reassign the individual peaks by clicking on individual peak lines and pressing the Assign button. Or you can first unassign them by selecting the peak line and pressing the Unassign button. When you click on a spin graph atom that is already assigned you are shown just one group of peaks consistent with the current assignment. If you wish to see a list of alternative resonance assignments you need to unassign the resonance and then click on the atom again. (I should change this so that you see the alternatives in this case. The case of clicking on an already assigned resonance is handled differently because I want to show assignments that have been made that are outside of tolerances. This would be better handled by just putting the current assignment group at the top and include all existing assignments in it.)
When you assign and unassign peaks or groups of peaks with the Assign and Unassign button the spin graph lines are updated but the text window is not. (I don't update the text window because then all the alternative assignments disappear. This related to the last comment of the previous paragraph.) If you assign or unassign peaks by other means such as the standard assignment dialog (at) or using the unassign peak command aD, then neither the spin graph display or text is updated. Pressing the Update button on the assignment graph dialog will update the spin graph to reflect the current assignments. When you pick new peaks or delete peaks you also need to press the Update button so that the new peak lists are used for proposing assignments.
The strip plot window (command sp) is used for displaying narrow 2D portions of 3D spectra. It can display many strips of one or more spectra. and can search for strips having peaks with shifts matching selected peaks. There are many possible uses. For example, the HNCACB strip for each residue of a protein can be displayed with the amide proton on the x-axis, the alpha and beta carbons shifts on the y-axis, and the amide nitrogen on the z-axis (ie determining which plane is viewed). This spectrum correlates amide proton and nitrogen with intra and preceding residue CA and CB atoms. Every pair of strips from adjacent residues should show CA and CB peaks with matching y positions. So a walk down a protein backbone is displayed. Since only 20 or so strips will fit on the screen, there is a horizontal scrollbar to shift through strips. You can find strips with peaks having y positions matching selected peaks. So you can produce a walk down a protein backbone by starting with one HNCACB strip. Select the intra CA and CB peaks and invoke a command to find strips with peaks with matching y positions. This will find the amide strip for the next residue (recall each strip shows intra and preceding CA and CB). Then you can select the CA and CB for the new strip and find the next residue. In practice this will probably not work because peaks will be missing due to the low sensitivity of the HNCACB experiment. To accomodate this you can display strips for both HNCACB and CBCACONH. The latter spectrum shows only peaks from amide H and N to preceding residue CA and CB and may have better signal to noise. You can request that the strip plot window display strips for both spectra and you can search for matching strips in the CBCACONH spectrum. Besides backbone assignment using triple resonance spectra strip plots are also useful for side chain assignments. For instance starting with once strip of an HCCH-TOCSY (correlating attached proton and carbon to all other protons connected by chains of carbons) with the xy axes being the two proton axes you can select all peaks in the strip and find all other strips that match a large subset of those peaks. This can produce a collection of all strips for a sidechain spin system. Strip plots are also useful for making assignments in N15 and C13 editted NOESY spectra. To read more about how to take advantage of strip plots see: Journal of Biomolecular NMR, 5 (1995), 1-10 where Christian Bartels, Tai-he Xia, Martin Bileter, Peter Guntert, Kurt Wutrich describe their strip plot program XEASY. The Sparky strip plot extension was based on that paper.
To display strips show the strip plot window with the sp command and choose "Select strip spectra... (ss)" under the Show menu. This displays a dialog listing the currently loaded 3D spectra. You click the checkbuttons next to the spectra you want to display strips for. You need to select which spectrum axes will be the x (horizontal), y (vertical) and z (plane) axes for each spectrum you will display strips for. Now you can select a peak and use the add selected peak strips command sk to show strips corresponding to the peak position for all of the chosen spectra. The strips are displayed in the same order that the spectra were chosen. Additionally each strip label has a border whose color matches the color of the checkbutton for that spectrum. A spectrum strip is only displayed if the x and z axes can be matched with corresponding axes of the spectrum the peak comes from. The peak must have a single axis with matching nucleus. (Note: This should be generalized to use the matching rules used by view centering that fallback on matching corresponding axis numbers.) The sk command adds strips at the end of the current set of strips. To delete individual strips type the Delete Strip command sd in the strip to be deleted. The sD command deletes all strips.
To display strips for all assigned peaks use the All Assigned Strips command sn. All x-axis and z-axis assignments are found for all chosen spectra and strips are displayed at these positions, ordered by residue number. The Goto Assigned Peak Strip command sj (under the Find menu) can then be used to scroll to the first strip whose assignment matches that of the selected peak.
To find all strips in a spectrum with peaks matching the y positions of currently selected peaks use the add strips matching peaks command sm. The search is done in the spectrum you typed the sm command in. Typically you pick one or two peaks in one strip and then wish to find strips in a different spectrum. To change the input focus to the spectrum in which you want to find matching strips without deselecting your peaks you can hold the shift key while clicking in the desired spectrum window. The peaks of the spectrum are clustered into strips using ppm ranges for each nucleus type. These ranges are specified in the Select Strip Spectra (ss) dialog. Then each strip has its peak y positions compared to the y positions of the selected peaks. A strip peak matches the y position of one of the selected peaks if it is within the range for that nucleus type. You can show only strips that have peaks matching every selected peak, or you can allow some number of selected peaks to have no match. The allowable number of mismatched peaks is also set in the Select Strip Spectra dialog. The displayed matching strips are ordered by how good the match is measured as the sum of the absolute y position errors. An unmatched position counts as an error equal to the ppm range in this score. Many matching strips can be found. They are appended to the current set of strips. To delete all the matching strips found by the most recent sm command use the Delete Matched Strips command sM.
Each strip is a view window that can be manipulated like all other spectrum view windows. For instance the contour scale can be displayed (vC) and contour levels adjusted. To apply changes made to one strip to all other strips of the same spectrum use the copy view strip options command sv in the strip whose settings you want to propagate.
Integrated peaks have a volume and volume error associated with them. The seldom used volume error is intended to estimate errors in integration arising from poor fitting, offset baselines, other spectrum processing artifacts, overlap with other peaks, .... It can be output as a column in peak lists for use by programs which compute distance bounds from NOESY peak intensities. The volume error is not set automatically when peak integration is performed. Peak fitting produces a "fit residual" which can be displayed as a separate column in peak lists. The ve command allows you to set volume errors for all integrated peaks based on a few criteria. There are default percent error values for fitting and for box/ellipse methods, there is a penalty for being near the spectrum diagonal, and there are penalties for being overlapped with smaller, bigger, and comparable volume peaks. All error values are expressed as a percent of total volume.
Here is how to modify a Sparky extension to do something new. Copy the Python code for the extension (standard extensions are in /usr/local/sparky/python) to a directory named Python under your home Sparky directory. Sparky looks first in this personal Python directory when you ask it to load Python code. If you want to use both the original and customized versions rename the file. Now look through the Python code and modify it as desired. Python is a very clean language so even if you don't know it you can probably figure out many of its features just by looking at some code. There are several books on Python and there is online documentation. Python is a general purpose language. The way Sparky data is represented in Python and how you can use the Sparky user interface are described in sparky.py.
To use a modified Sparky extension (in file mycode.py) bring up the Python shell window in Sparky (py) and type the command:
import mycode
You can have your extension loaded every time you start Sparky by adding the above import command to a file called sparky_init.py in your Python directory. You will probably want to add a menu entry and accelerator to invoke the extension. You can do this by adding a line to the end of the Python code like:
sparky.add_command('sg', 'Spin graph (sg)', 'spingraph.show_spin_graph()')
This adds an accelerator and extension menu item that execute the specified Python command.
If your modifications to the Python code generate an error, Python will print an error message including a trace indicating where the problem is. Sparky should never crash because of incorrect Python code. The error message will appear in the Python shell window (py). You can modify the code and then reload it with the command:
reload(mycode)
You have to use this reload command instead of import because import does not reread the file.
You can look at the extensions /usr/local/sparky/python for examples of Sparky extensions. A good way to learn Python is take an existing extension that does something similar to what you want and modify it. Here is an example of a Sparky extension.
def write_peak_list(peak_list, path) : file = open(path, 'w') for peak in peak_list: if peak.assignment != None and peak.volume != None: line = "%15s %9.0f\n" % (peak.assignment, peak.volume) file.write(line) file.close()
The function write_peak_list() is defined. It takes two arguments, the first is a list of peaks and the second is the name of a file to write a peak list to. The first line opens the file for writing. The second line starts a loop where the variable "peak" will be set to each peak in "peak_list" in succession. The "if" statement checks that the peak has an assignment and a volume. If it does the variable "line" is set to a string containing the assignment and the volume. The next line writes the string to the file. When the loop is finished the file is closed.
The words highlighted in red are defined by the Python language. The words "volume" and "assignment" are defined by Sparky. The other words are variables names I chose. The format of the string uses the C language format specifiers. The assignment name is placed in a field 15 characters long, then there is a space, and the volume with zero digits after the decimal place in a field 9 characters long followed by a newline character.
To use this function in Sparky you do the following. First put the code in a file called "writepeaks.py" in the directory "~/Sparky/Python". Then bring up the Python interpretter in Sparky with the command py and type:
>>> from writepeaks import * >>> peaks = selected_view().spectrum().peak_list() >>> write_peak_list(peaks, "mypeaks")
The ">>>" is the Python prompt. The first line loads your function. The second line calls 3 Sparky defined functions to get the currently selected view, find the spectrum it is associated with, and produce a list of all that spectrum's peaks. The third line writes the peaks to a file called "mypeaks".
That's alot of typing to produce a list of peaks. You could much more simply produce this list by bringing up a peak list (lt) and saving it to a file with the Save button. But if you needed to precisely control the format of the list so that it could be used as input to another program it might be worth writing the above Python function with exactly the right format specifier. If you were going to use this more than once it you could make it callable with a keyboard accelerator like all other Sparky commands. I'd write a slightly different function for this purpose.
def write_spectrum_peaks() : spectrum = selected_view().spectrum() peak_list = spectrum.peak_list() path = "~/Sparky/Lists/" + spectrum.name + ".peaks" file = open(path, 'w') for peak in peak_list: if peak.assignment != None and peak.volume != None: line = "%15s %9.0f\n" % (peak.assignment, peak.volume) file.write(line) file.close()
This version of the function takes the peaks from the spectrum of the current view and writes them to a file whose name is the spectrum name with a ".peaks" suffix. To have this function called when I type "wp" in a view window I would put the following lines in the file "~/Sparky/Python/sparky_init.py".
from sparky import add_command from writepeaks import write_spectrum_peaks add_command("wp", "Write spectrum peaks (wp)", "write_spectrum_peaks()")
The first two lines make the
add_command()
and
write_spectrum_peaks()
functions available. The three arguments to the
add_command()
function are the new keyboard accelerator "wp",
the text to use for a menu entry, and the Python code to execute when the
command is typed. Sparky executes the sparky_init.py file when it is
started. So now whenever you start Sparky this command will be available,
and will have a menu entry in the "Extensions" menu. To test this without
exitting and restarting Sparky you would type to the Python interpretter:
>>> from sparky_init import *
There are more examples of Python extensions to Sparky in the file example.py that comes with the Sparky distribution (look in directory /usr/local/sparky/python). Copying example code and modifying it to suit your needs is an easy way to learn the Python language. You can also learn how Sparky data (peaks, spectra, ...) is represented in Python from example. A more direct way is to look at the file sparky.py distributed with Sparky. This file defines peaks, spectra, ..., and all the functions for getting data from Sparky and manipulating the Sparky user interface.
For more on Python look at the excellent tutorial, or for a crash course, the quick reference. For more details see the language manual, and library manual. To get the latest version of the Python language, about all kinds of optional packages, etc ..., go to Python's home http://www.python.org
Below I describe an interface to an automatic protein backbone assignment program called AutoAssign. A step by step description for assigning BPTI is given. This was presented as a poster at the "Computational Aspects of Biomolecular NMR" conference in Pisa in June 1999.
Software to automate resonance assignment of proteins has not been widely adopted. Such programs can significantly reduce the time required for assignment, a tedious and time consuming step in NMR studies of protein structure and dynamics. A difficult aspect of automated methods is assimilating the results. It is necessary to check the assignment for errors and omissions. A second impediment is that current programs deduce assignments from lists of peak positions. They have difficulty achieving results as complete as hand assignment because they do not have direct access to the spectra. To address these limitations I have united a graphical manual assignment program, Sparky, and an automated protein backbone assignment code called AutoAssign. The key new feature of this system is a diagram called a spin graph. A spin graph represents atoms as dots and assigned peaks as lines connecting the dots. It provides an intuitive and detailed display of generated assignments. The tight integration of Sparky and AutoAssign allows a cycle of revising peak lists and computing assignments to be done in tens of seconds. The spectroscopist adds and deletes peaks based on flaws in the previously computed assignments and direct examination of contoured spectra. Tests of the Sparky / AutoAssign software on 58 residue Basic Pancreatic Trypsin Inhibitor (BPTI) protein suggest that this combination of tools may offer substantial time savings for protein backbone assignment. This approach is expected to result in assignments that are as complete as those obtained with traditional methods. Application to more realisitic protein systems is necessary to better assess the usefulness of this software.
The following is a walk through of the backbone assignment process for the 58 residue protein BPTI using the Sparky and AutoAssign programs.
I start with 8 processed spectra, a 2D N15 HSQC, and 7 triple resonance spectra: HNCO, HNCA, CA(CO)NH, HNCACB, CBCA(CO)NH, HNHA, HA(CO)NH. This is the preferred set of spectra for running AutoAssign. It is possible to work with fewer spectra, omitting the HNCO and the two HA spectra. The spectra can be processed with Bruker software, Varian's VNMR, NMRPipe from the NIH, or Felix.
The first step is to align the spectra. This is done by shifting the spectrum ppm scales so that corresponding peaks in the spectra are aligned. This is necessary when the referencing information used in processing the spectra is not consistent. You use the Sparky spectrum tool (accerlator st) to enter shifts for individual spectrum axes. I do this by first shifting the H and N axes of the triple resonance spectra so that their peak line up with the HSQC peaks. Then I shift the CA axes so that peaks in CA strips line up. Then I adjust the HA axes. To determine the numerical shifts in ppm I find corresponding strong peaks in two spectra, pick them, and take the difference of their chemical shift positions as shown in peak lists (accerator lt). For aligning the H and N axes of the triple resonance spectra with the HSQC it is helpful to project the 3D spectra onto the HN plane. You can create a 2D projected spectrum with the ucsfdata program using a command like:
% ucsfdata -s1 256 -r -o hnca2hn.ucsf hnca.ucsf
This command projects the along the CA axis of the HNCA spectrum, in this case it is axis w1 having 256 data points. Executing ucsfdata without any arguments will give a summary of the options. The alignment of the ppm axes described above does not establish absolute ppm scales. You need a reference peak of known chemical shift to do this. It is desirable to establish absolute referencing because AutoAssign and some Sparky tools use chemical shift statistics to help guess assignments.
Above is shown the N15 HSQC spectrum. I interactively adjust contour levels and pick peaks above a specified threshold and minimum linewidths. For the triple resonance spectra I pick peaks that are sufficiently close in the amide H and N dimensions to picked HSQC peaks. This is done with the restricted peak picking extension (accerator kr). Limitting the picked region of the 3D spectra allows me to use lower thresholds while keeping the number of noise and artifact peaks small. This process produces a total of about 750 peaks in 30 minutes. Most of the time is spent adjusting thresholds and repicking to obtain approximately the expected number of peaks.
Next I run AutoAssign to generate backbone assignments. AutoAssign was created by Gaetano Montelione's group at Rutgers and is described in a paper "Automated Analysis of Protein NMR Assignments Using Methods from Artificial Intelligence", J. Mol. Biol. (1997) 269, 592-610. It has a user interface which displays text lists of assignment information and scatter plots. I don't make use of this interface. Instead, I treat the program as a black box invoked by the dialog shown above. The picked peaks and a set of chemical shift tolerances are the only inputs. The program runs for about 5 seconds and generates backbone resonance assignments. Peak assignments are automatically inferred from the resonance assignments and displayed.
Peak assignments are displayed as a spin graph. This is the novel element of the software I am describing and much of what follows will describe how it is used to arrive at a final set of resonances assignments.
A spin graph shows atoms as dots connected by lines which represent assigned peaks. The above picture shows the amide H, N and CA atoms of glycine residue 28 of BPTI. The line connecting the amide proton and nitrogen represents an assigned HSQC peak.
An assigned peak in a 3D spectra is shown as two lines. The example above shows an HNCA peak connecting the amide proton and nitrogen to the alpha carbon.
The color of the line indicates which spectrum the assigned peak comes from.
Peaks from multiple spectra can be shown in the same diagram.
![]() |
![]() |
The above spin graph shows the BPTI assignments generated by running AutoAssign. The 58 residues of BPTI are layed out in a single row and you can scroll from one end to the other. Only the assignable backbone atoms are shown. The 8 different line colors indicate peak assignments from the 8 spectra.
No assignments are made for some residues. Sometimes this is because a small stretch of residues is bounded by prolines. In other cases the peaks needed for assignment are below the spectrum noise level. About 75% of the backbone resonances are assigned without any modifications to the automatically picked peak lists. A few residues are given incorrect assignments. About half the unassigned resonances cannot be assigned using the available spectra.
The spin graph above shows that no assignments were made for proline 13 and the assignments for cysteine 14 and lysine 15 are incomplete. I investigate this problem by starting with the lysine 15 alpha and beta carbon resonances and directly examining the spectra to verify the lysine 15 assignments.
I first display the peaks connecting the solidly assigned A16 residue to the CA and CB of K15. The first 3 strips show the CBCACONH, HNCACB and HNCA spectra for alanine 16. Next I selected the CA peak shown with the square box around it in the first strip, and request all HNCACB strips with a peak having matching carbon shift. The seven rightmost strips are displayed. The strip with amide H shift 8.001 and N shift 115.5 has a peak matching the CB peak of alanine 16 but it has not been picked.
I pick the unmarked peak identified with the strip plots above and rerun AutoAssign. The new assignments are displayed in about 15 seconds. The one additional peak allows AutoAssign to correctly assign residues P13 through K15.
Three additional locations along the BPTI backbone require direct inspection of the spectra similar to what was illustrated above to improve peak lists. After fixing those problems a few gaps remain in the assignments.
The spin graph above shows a gap between residues K46 and S47.
I click on the spin graph S47 H atom and the above list of plausible assignments is displayed. Three groups of assignments are shown. The top line of each group lists a proposed resononance assignment and the subsequent lines show peak assignments consistent with the resonance assignment. The groups are ordered by the number of supporting peak assignments.
I select the top line of the proposed assignments in the above list and press Assign. I similarly assign S47 HA and K46 C getting the assignments shown in the spin graph above. Why didn't AutoAssign make these assignments? I don't know. The algorithm is sufficiently complex that it is difficult to explain all of its behavior. It is important that the program can be treated as a black box and tools are available to complete assignments by hand.
Combining graphical tools supporting traditional assignment methods that make direct use of spectra with automated assignment software lets the NMR spectroscopist focus on difficult to assign residues. Spin graph display of automatic assignment results is an effective means of locating the difficult to assign residues. The Sparky / AutoAssign combination will need to be tested on more realistic data sets to assess the time savings resulting from this approach. I would like to provide Sparky interfaces to other automatic assignment programs for both protein backbone and side chain assignments.
Sparky is distributed for Windows, Linux, SGI, Sun, and DEC platforms:
http://www.cgl.ucsf.edu/home/sparky
AutoAssign is distributed for SGI and Linux:
http://www-nmr.cabm.rutgers.edu/software
Computer Graphics Laboratory, UC San Francisco Tom Goddard (that's me) - Sparky development Tom Ferrin - director of lab Magnetic Resonance Laboratory, UC San Francisco Members of Tom James' NMR group guide Sparky development Protein NMR Spectroscopy Lab, Rutgers University Ying Xiong - processing BPTI spectra Hunter Moseley - AutoAssign development Gaetano Montelione - director of lab
You can change the font size and style used for buttons, labels, menus, peak lists, ... by adding some lines to your ~/.Xdefaults file. The fonts you specify override the defaults specifed in the Sparky option database /usr/local/sparky/lib/Sparky. You can look in that file for other options you may want to override. The lines to specify fonts that you add to your .Xdefaults files should look like:
sparky.normalFont: -family lucida -size 12 sparky.fixedWidthFont: -family lucidatypewriter -size 12
You should then execute the command "xrdb -merge ~/.Xdefaults" so that the X server reloads the .Xdefaults file, and then restart Sparky. You will not need to run the xrdb command in the future. Every time you log in the .Xdefaults files is read. The font sizes are specified in points (1/72 of an inch). To see what font families and sizes are available you can use the xlsfonts command (if it is available on your system). The fixedWidthFont line should name a font that has a fixed width per character. It is used in peak lists so that columns line up. To adjust the size of assignment labels on contour plots you use the ornament size dialog in Sparky (oz).
Sparky no longer has:
The spectrum window buttons correspond to keyboard accelerators. Zoom in is zi, zoom out is zo, zoom previous is zp, toggle resonance panels is vR, toggle slice panels is vS.
The files in the DB directory are no longer used by Sparky. This means that resonance frequencies are calculated by averaging the positions of assigned peaks in spectra in your project. Peaks in spectra which are not part of your project no longer effect resonance frequencies.
The accelerators for ornament copy and paste have changed from ec and ep to oc and op.
There are no longer separate integration methods for isolated and overlapped peaks. You choose a single integration method from the integration dialog (accelerator it).
The assignment dialog is different from pre-1995 Sparky.
View synchronization is now done with a synchronization dialog. The accelerators ya, yd, and yt all bring up this dialog. You can now synchronize individual axes instead of all corresponding axes between two or more spectra.
If you process your data with NMRPipe you'll need to convert it to UCSF format with the program pipe2ucsf that comes with the Sparky distribution. NMRPipe is a processing program written by Frank Delaglio at the NIH. Request this program from him at delaglio@spite.niddk.nih.gov.
Given NMRPipe data noe150.pipe you convert it to UCSF format with:
% pipe2ucsf noe150.pipe noe150.ucsf
This creates the file noe150.ucsf. Only the real component is taken from the NMRPipe file. To see the header of a UCSF format file you can use:
% ucsfdata noe150.ucsf
pipe2ucsf [-axisorder] pipefile ucsffile where axisorder is a string of digits (eg. 312)
The pipe2ucsf program will convert 2D, 3D, or 4D data processed with NMRPipe to UCSF format. 3D or 4D nmrpipe data data should be in a single file. A spectrum divided into separate files containing 2D planes (with pipe2xyz) cannot be converted by pipe2ucsf. The input and output files must be explicit files, unix pipes cannot be used. This is because pipe2ucsf does random access reading and writing of data which is not possible using stdin (standard input) and stdout (standard output).
The axis order in the created UCSF spectrum file (ie. which spectrum axis is called w1, which is called w2, ...) can be controlled by the axisorder option. The w1, w2, ... axis names are displayed by Sparky but have no special significance (ie. there is no correct order). Conventionally the highest axis number is the directly detected dimension. Here is an explanation of how pipe2ucsf arrives at its default axis order. To put Bruker or Varian raw spectrometer data into NMRPipe format before processing you use the programs bruk2pipe and var2pipe that come with NMRPipe. The arguments to these commands define the XYZA axes for the data. For a 2D spectrum pipe2ucsf with no axisorder option will name the X and Y axes w2 and w1, for 3D data the XYZ axes become w3, w2, w1, and for 4D data the XYZA axes become w4, w3, w2, w1. This is true even if processing with NMRPipe transposed the axes in the NMRPipe file. To obtain a different order use a command like:
pipe2ucsf -321 pipefile ucsffile
This will reverse the default ordering for a 3-D spectrum. Using -123 gives the default order, -213 swaps the first two axes, etc... For a 2-D spectrum -21 reverses the default axis order.
To extract information from a UCSF NMR file you can use the program ucsfdata that comes with Sparky.
Usage: ucsfdata [-w1 i j] [-w2 i j] [-w3 i j] [-w4 i j] [-s1 r] [-s2 r] [-s3 r] [-s4 r] [-t v1 v2] [-r] [-m] [-o output-ucsf-file] input-ucsf-file Prints header information for UCSF format NMR data files. Produces new UCSF data files for subregions, or with data below specified thresholds zeroed, or with reduced matrix size. Produces matrix file with no header information. -wN low-index high-index specifies subregion for axis N -t negative-threshold positive-threshold zeros all data points below threshold values -sN cell-size replace cells by single data value of largest magnitude -r reduce dimension by eliminating dimensions with only one plane -m outputs the data matrix (last axis varying fastest) to stdout
With no -m or -o flag header information is printed to standard output. If the -m flag is present the data matrix is written in binary format as IEEE floats with your machine's native byte order. The matrix is written out with highest axis varying fastest. With the -o flag a new ucsf format file is written. The -w1, -w2, ... flags can be used to specify a subregion. The -s1, -s2, ... flags can be used to have cells replaced with the data value of largest magnitude (reducing the size of the matrix). A 3D data matrix can be projected to 2D by specifying the cell size for one axis to be the full matrix size and using the -r option. The -r option causes axes with just one plane to be eliminated. Without the -r the preceding example would produce a 3D matrix where the projected axis has just one plane. The -t flag can be used to zero small data values. The -t option can be used to conserve disk space. The resulting file must be compressed (eg. with gzip) to realize any space savings. Sparky cannot read the compressed file directly so it must be uncompressed before use.
TO: All SPARKY Users RE: NMRPipe, the NIH Multidimensional NMR Processing System DATE: July 21, 1997 FROM: Frank Delaglio delaglio@spite.niddk.nih.gov Dear Colleagues, We welcome your interest in NMRPipe ... the current release is available via a restricted-access anonymous FTP server. Some details on the software and its capabilities are included below. In order to access the software, simply send an e-mail request to the address above; a password and instructions will be sent in return. We very much hope that NMRPipe proves useful to your work ... Best Regards, Frank Delaglio National Institutes of Health Laboratory of Chemical Physics, NIDDK 5 Center Dr MSC 0505 Bethesda MD 20892-0505 USA ---------------------------------------------------------------- FUNCTIONALITY The NMRPipe system provides facilities for conversion and processing of 1D-4D NMR spectra and spectral images, and for interactive processing and display of raw and processed data. Extensive options for inverse processing, Linear Prediction, Maximum Entropy, and user-written functions are provided. Many auxiliary facilities are included, such as multidimensional lineshape fitting, and general functional fitting with Monte Carlo error estimation. The release includes the programs xyz2pipe, nmrPipe, and pipe2xyz, which are used together to create multidimensional processing schemes. It also includes conversion programs specifically for Bruker and Varian Unity data, as well as a generic conversion program that can be used with most other formats. In addition, source code for the conversion routines is included. Recently added is a beta version of our graphical interface for "automated" spectrometer format conversion, which can be executed by the scripts "bruker" or "varian". This interface was developed using the Tk/Tcl command language. The release also includes a graphical interface called nmrDraw, used for quick inspection of the raw data and the processed results. In addition, NMRDraw provides analysis facilities such as 1D-4D peak detection. REFERENCE The software is described by the following paper; feel free to e-mail a request for a reprint: NMRPipe: a multidimensional spectral processing system based on UNIX Pipes F. Delaglio, S. Grzesiek, G. Vuister, G. Zhu, J. Pfeifer, and A. Bax J. Biomol. NMR, 6 (1995) 277-293. SUPPORT NMRPipe has been used successfully at over 200 commercial and academic sites across the world. However, NMRPipe is completely unsupported outside the NIH and is without warranties of any kind. We will respond to questions and bug reports when possible, and we are grateful for your opinions on improving the software. HARDWARE AND OPERATING SYSTEMS Sun and SGI executable versions of the software have been included, and they have worked well at numerous sites. HP, DEC Alpha, IBM RISC, and PC (x86) Solaris versions of NMRPipe have also been included, although these are not as well tested: HARDWARE OPERATING SYSTEM NMRPIPE VERSION ------------------ -------------------- --------------- Sparc Solaris 1 sun Sparc Solaris 2 sol 1) x86 Solaris 2 pc SGI all types IRIX 4 sgi SGI R3000 and below IRIX 5.3 and above sgi5x.m1 SGI R4000 and above IRIX 5.3 and above sgi5x 2) SGI R4000 and above IRIX 6.2 and above sgi6x 2) SGI R8000 and above IRIX64 6.2 and above sgi6x.m4 3) x86 Linux linux HP HP-UX hp IBM RISC AIX ibm DEC Alpha OSF UNIX alpha Notes: 1) Beta release, not yet optimized. 2) We recommend the "sgi5x" version of the software for all SGI platforms R4000 and above (R5000, R8000, R10000), in cases where IRIX 5.3 and higher is used. 3) As of this writing, still under development.
Data processed with Felix that is in Felix matrix format can be used directly by Sparky. You use the Sparky open command under the file menu. The Felix matrix should contain correct transmitter frequencies, spectral widths, reference points, reference shifts and axis labels for each axis. These are set with the Felix rmx command.
rmx dim freq width type refpt refval text
For example,
rmx 1 600.123 5000.0 0 1 10.35 H1
sets axis 1, with transmitter frequency 600.123 MHz, sweep width of 5000.0 Hz, axis type 0 (this is not used by Sparky), index position 1 has a chemical shift of 10.35 ppm, and this is a proton axis. Axis labels C13 or N15 are used for heteronuclear spectra.
If you process your data with Varian's VNMR you'll need to convert it to UCSF format using the program vnmr2ucsf supplied with Sparky. This program will convert 2D or 3D data.
To convert VNMR processed 2D data in directory exp7 to UCSF format use:
% vnmr2ucsf exp7/procpar exp7/datdir/phasefile exp7.ucsf H H
This creates the file exp7.ucsf using parameters from exp7/procpar and data from exp7/datdir/phasefile. To make sure that VNMR produces the phasefile you need to set trace='f1', display the full spectrum, and use the VNMR flush command. If you don't use the above VNMR commands the phasefile may not be written or may contain just zero values. The above example is for a homonuclear experiment. The H H arguments specify the nucleus types for the f1 and f2 axes. You use C and N for carbon and nitrogen dimensions.
Here is an example that converts processed 3D data.
% vnmr2ucsf extr/procpar3d extr/dataf1f3 hnca.ucsf C N H
Parameters are read from the procpar3d file and data comes from files dataf1f3.* which are 2D planes of the 3D spectrum. The 2D planes dataf1f3.n (where n is the plane number) are created by the VNMR getplane command. See the VNMR command reference manual for how to use getplane. The path to the data files on the vnmr2ucsf command line is specified without the plane number suffix. The vnmr2ucsf program appends the numeric suffixes to read all 2D planes. The final 3 arguments are the nucleus types for the f1, f2 and f3 axes.
Parameters fn, fn1, sfrq, dfrq, dfrq2, dfrq3, tn, dn, dn2, dn3, sw, sw1, rfl, rfl1, rfp, rfp1 from the procpar file are used by the conversion program to determine the size of the data set, transmitter frequencies, sweep widths and ppm scales. For 3D the additional parameters fn2, sw2, rfl2, rfp2 are used.
If you process your data with Bruker's XWinNMR or UXNMR software you can convert it to UCSF format using the program bruk2ucsf supplied with Sparky. This program has not been tested much. Bruker processed data can also be read directly by Sparky. Both the Bruker and UCSF file formats store the data matrix in blocks so that the whole file does not need to be brought into memory. The Bruker blocks are typically large (1Mb) while the UCSF blocks are small (32Kb). Because Sparky is designed to use the small blocks, you might run out of memory if you have many Bruker spectra loaded simultaneously. In this case you should convert the Bruker files to UCSF format with bruk2ucsf.
To convert Bruker processed data 1/pdata/1/2rr to UCSF format use:
% bruk2ucsf 1/pdata/1/2rr noesy150.ucsf
This creates the file noesy150.ucsf using parameters from 1/acqus, 1/acqu2s, 1/pdata/procs, and 1/pdata/proc2s. The parameters used from the acqu*s files are NUCLEUS and SFO1. The parameters used from the proc*s files are SI, XDIM, SW_p, OFFSET, and BYTORDP. All the parameters needed by Sparky are put in the UCSF file. These include nucleus names for each axis, data size, block size, transmitter frequencies, sweep widths and ppm scales.
Use File Open (fo) to open UCSF format NMR data, Felix matrix files, or Sparky spectrum files. File Save (fs) writes the spectrum file for the current view. It does not modify Felix or UCSF NMR data files. If you want to modify a Felix matrix use Felix. You can extract a subregion from a UCSF NMR data file with the program ucsfdata. To save all the spectrum files you are currently working on use Project Save As (ja). In addition to updating all the spectra, a list of the spectra are recorded in a project file. Use Project Open (jo) to open all the spectra listed in a project file. Note that a project file just lists the spectra you are working on. So saving a project under a new name does not make a copy of your peak data. If you want to copy your peak data you need to copy the Sparky spectrum files.
Sparky reads UCSF format NMR data or Felix matrix files. It never creates or modifies NMR data files. The data you produce while using Sparky (peak positions, assignments, volumes, etc...) is saved by Sparky in spectrum files and project files. Spectrum files are usually placed in the ~/Sparky/Save/ directory and contain almost all the data relating to an individual spectrum. Peak positions, assignments, volumes, label positions, and what views you are currently looking at are all saved in these files. Project files are usually placed in the directory ~/Sparky/Projects/. A project file contains a list of spectrum files you are working on. It also contains information pertaining to more than one spectrum such as the list of resonances for each molecule and condition, view synchronizations, and view overlays.
When you save a project file or spectrum file Sparky copies the previous contents of the file to a file with the suffix .BAK. If you accidently save bad data you can recover the previous file contents by copying the .BAK file.
You can have Sparky automatically backup your project every so many minutes. You set this using the preferences dialog under the file menu. Sparky then periodically saves copies of your current unsaved work in files with a .backup suffix. These files will be deleted when you quit Sparky. If Sparky crashes the files are not deleted. When you start Sparky again you will be asked if you want to use the automatic backup files, ignore them, or remove them. If you choose to use them Sparky will load the .backup files. If the auto backup data looks OK you can save your work bringing your files up to date. Sparky will not automatically backup files that you do not own. This is to prevent backup conflicts when you and the owner of the files are both looking at the data with separate Sparky sessions.
Here is a sketchy description of the UCSF NMR data format as used by Sparky. Sparky needs to know the dimension, data matrix size, data values, nucleus types, and parameters to convert data indices to ppm and Hz. The ppm and Hz scales are determined by knowing along each axis the transmitter frequency, spectral width, and ppm value for index 0. Given this information you can write a UCSF NMR data file for input to Sparky. The file format is somewhat complicated. The data matrix is broken down into small arrays so that small regions of the data can be read with few disk accesses.
A UCSF NMR data file is a binary file with a 180 byte header, followed by a 128 byte header for each axis of the spectrum, followed by the spectrum data. All integer and float values in the file have big endian byte order independent of the native byte order for the machine that wrote the file. An int has big endian order if the most significant byte appears first in the file (or at the lowest memory address). Sun Sparc and SGI Rx000 processors are big endian and DEC Alpha is little endian. If you write a conversion program to produce UCSF format the code should check the native byte order at run time and reverse floats and ints if necessary before writing them out. All float values are in IEEE format. All header bytes not described below should be set to zero.
The 180 byte header contains:
position | bytes | contents |
---|---|---|
10 | 1 | dimension of spectrum |
11 | 1 | number of data components (= 1) |
13 | 1 | version number (= 2) |
The first byte in the file is position 0. A complex spectrum has two components. Sparky only reads real data and I will only describe below the layout for real data so set the number of components to 1. Use version number 2.
For each axis of the spectrum write a 128 byte header of the following form:
position | bytes | contents |
---|---|---|
0 | 6 | nucleus name (1H, 13C, 15N, ...) null terminated ASCII |
8 | 4 | integer number of data points along this axis |
16 | 4 | integer tile size along this axis |
20 | 4 | float spectrometer frequency for this nucleus (MHz) |
24 | 4 | float spectral width (Hz) |
28 | 4 | float center of data (ppm) |
Next comes the spectrum data floating point values. The full data matrix is divided into tiles. Each tile is written to the file as an array with the highest axis varies fastest. If a tile size does not evenly divide the data matrix size then their will be a partial tiles at the edge. Partial tiles are written out as a full tiles with zero values for the region outside the data matrix. The tiles themselves form an array and are written out in sequence with highest axis varying fastest.
We distribute binary versions for SGI running Irix, Sun Sparc using Solaris, DEC Alpha using Digital Unix, x86 and Pentium PCs running Linux or Windows 95/98/NT, and possibly other platforms. See the Sparky web site http://www.cgl.ucsf.edu/home/sparky to see what versions are available.
A trial license and sample data are available. A license for academic use costs few hundred dollars.
sparky-license@cgl.ucsf.edu | licensing inquiries |
sparky@cgl.ucsf.edu | other questions |
Sparky was developped by Donald Kneller 1989-95 working with Tack Kuntz at the University of California, San Francisco. Development is continuing at the Computer Graphics Laboratory, UCSF, headed by Tom Ferrin, and within the NMR group lead by Tom James at UCSF. My name is Tom Goddard. I do the programming.
Sparky is a graphical program for doing NMR assignment and integration. The latest version is available at: http://www.cgl.ucsf.edu/home/sparky An academic license costs a few hundred dollars. An academic license costs a few hundred dollars. A trial license good for 3 to 6 months is available. See the web page for instructions on getting a license.
Binary distributions of Sparky are available for:
SGI | IRIX 5.3 |
DEC Alpha | OSF 4.0d |
Sun Sparc | Solaris 2.5.1 |
Sun Sparc | SunOS 4.1.3 |
PC x86 | Linux 2.0.30 |
Obtain the sparky distribution sparky-xxx.tar.gz for your hardware and operating system from the Sparky web site and unpack it as follows.
% mv sparky-xxx.tar.gz /usr/local % cd /usr/local % gunzip sparky-xxx.tar.gz % tar xvf sparky-xxx.tar
This puts the following files in /usr/local/sparky.
README - where to get help INSTALL - installation instructions (this file). manual - directory containing manual in HTML. bin/sparky - a script that starts Sparky. bin/sparky.exe - the actual executable. bin/pipe2ucsf - conversion from NMRPipe format to Sparky format. bin/ucsfdata - prints UCSF NMR data header, extracts data matrix. bin/vnmr2ucsf - conversion from Varian VNMR format to Sparky format. lib/Sparky - the Tcl/Tk option database. lib/print-prolog.ps - Postscript used for printing spectrum views. python - code for Python extensions to Sparky
You can put links to the programs in /usr/local/bin as follows, or you can add /usr/local/sparky/bin to your search path.
% ln -s /usr/local/sparky/bin/sparky /usr/local/bin/sparky % ln -s /usr/local/sparky/bin/pipe2ucsf /usr/local/bin/pipe2ucsf % ln -s /usr/local/sparky/bin/ucsfdata /usr/local/bin/ucsfdata % ln -s /usr/local/sparky/bin/vnmr2ucsf /usr/local/bin/vnmr2ucsf
If you want to put sparky in a directory other than /usr/local/sparky you will need to edit the startup script "bin/sparky" to give the correct path. That completes the installation. See the introduction of the manual for operating instructions.
If a binary distribution is not available for your hardware and operating system you need to compile Sparky from the source code. You will need a Sparky license, UNIX, X windows, Tcl/Tk, and a C++ compiler. Sparky can be extended by users with the Python language (http://www.python.org). If you want to use this you must have Python (free from http://www.python.org) and Tcl/Tk (free from http://sunscript.sun.com).
Unpack the Sparky source distribution and edit the Makefile. Set the paths to the source directory and the installation directory. If you have Python and Tcl/Tk set the lib and include paths. Shared object libraries for Tcl/Tk are required. If you don't want to use the GNU C++ compiler g++ change the definition of CC. Add any flags needed by your ompiler to the CFLAGS variable. If you want to install in a directory other than /usr/local/sparky edit the path in the sparky startup script "sparky". Now run make (or without Python make nopython) and if everything compiles run make install (or without Python make install-nopython). You can optionally put links to the programs in /usr/local/bin:
% ln -s /usr/local/sparky/bin/sparky /usr/local/bin/sparky % ln -s /usr/local/sparky/bin/pipe2ucsf /usr/local/bin/pipe2ucsf % ln -s /usr/local/sparky/bin/ucsfdata /usr/local/bin/ucsfdata % ln -s /usr/local/sparky/bin/vnmr2ucsf /usr/local/bin/vnmr2ucsf
Or you could add /usr/local/sparky/bin to your search path.
Copyright 1989-1997 by the Regents of the University of California. All rights reserved.
The UC Regents make no warranties, either express or implied, as to any matter whatsoever, including without limitation, the condition of the program, merchantability, or fitness for any particular purpose. The UC Regents shall not be liable for any direct, consequential, or other damages suffered by the user or any others resulting from the use of the program.
Version | Date | Description |
---|---|---|
3.64 | 1/26/99 | Added strip plot extension |
SGI Irix 6.5 distribution available | ||
3.60 | 10/27/98 | Trial version is now fully functional for a few months |
3.59 | 10/12/98 | Microsoft Windows version of Sparky distributed |
3.57 | 9/8/98 | Help buttons on all core dialogs show documentation with Netscape |
3.51 | 5/21/98 | Many new peak integration features |
3.49 | 5/4/98 | Contour scale to display contour levels and adjust them with the mouse |
3.39 | 1/8/98 | bruk2ucsf for converting Bruker processed data to UCSF format |
Bruker processed data directly readable by Sparky | ||
3.30 | 9/18/97 | Show peak info (linewidth, volume, position) at bottom of views |
vnmr2ucsf for converting Varian processed 2-D data to UCSF format | ||
3.29 | 9/9/97 | assignment label format option in view settings dialog |
3.28 | 8/21/97 | click on assignment table entry to bring up resonance peaks |
3.21 | 6/24/97 | open Felix matrices in Sparky |
3.16 | 6/9/97 | write your own Python code to extend Sparky |
3.14 | 5/12/97 | table of chemical shifts where rows are groups, columns are atoms |
new view synchronization dialog | ||
resonance panels thinned using assignment guesses | ||
3.13 | 5/1/97 | handle 4-D spectra |
integrate 3-D and 4-D peaks by fitting | ||
3.12 | 4/24/97 | Display assignments on a structure with Midas |
3.11 | 4/21/97 | DB directory no longer used |
3.10 | 4/14/97 | Overlay contours of one spectrum on another |
3.6 | 3/18/97 | Show information about spectrum views in a view list |
Dialog to rename atoms and groups | ||
Integration dialog option to lock peak positions | ||
3.3 | 3/4/97 | delete resonances not used in any assignments |
3.1 | 2/20/97 | automatically write backup files every x minutes |
3.0 | 1/10/97 | Sparky web site for the latest distribution and documentation |
file open... | fo | open UCSF NMR data, a Felix matrix, or a Sparky spectrum file |
file save | fs | save a Sparky spectrum annotation file |
file save as... | fa | save spectrum with a new name |
project open... | jo | open several spectra at once |
project save | js | save all spectra |
project save as... | ja | save project with a new name |
preferences... | pf | miscellaneous settings |
quit | qt |
axes in Hertz | xh | display view scale axes in Hz |
axes in ppm | xp | display view scale axes in parts per million |
axes show index | xd | show data index values on view scales |
axis nucleus types | xa | show nucleus type (1H, 13C, 15N) on axes |
axis roll | xr | exchange axes keeping center point of fixed |
axis transpose | xx | zoom to cross-diagonal region of spectrum |
center view on peak | vc | center a view on the selected peak |
orthogonal views | ov | show 3 orthogonal views of a 3-D spectrum |
region goto | rg | zoom to a named region |
region tool... | rt | name regions of a spectrum |
show axis scales | vs | show scales (ppm, hz, or index units) along view axes |
show grids | gs | toggle display of grids |
show labels | ls | toggle display of labels |
show lines | is | toggle display of lines |
show ornaments | os | toggle display of all ornaments |
show peaks | ps | toggle display of peaks |
show peak groups | xs | toggle display of peak groups |
show peak info | vp | show peak position / height / linewidth in status bar |
show resonances | vR | show resonances along edge of spectrum |
show scrollbars | vb | show scrollbars for view windows |
show slices | vS | show 1-D data cross-sections along edge of spectrum |
view duplicate | vd | make another view window |
view hide | vh | undisplay a view |
view redraw | vr | redraw the view (in case it gets messed up) |
view settings... | vt | set crosshairs, aspect ratio, slices, ... |
zoom full | zf | show entire spectrum |
zoom in | zi | zoom in by a factor of 2 |
zoom out | zo | zoom out by a factor of 2 |
zoom previous | zp | zoom to the previously shown region |
add sweepwidth | a1 a2 a3 a4 | adjust peak w1,w2,w3,w4 frequency one sweepwidth downfield |
subtract sweepwidth | A1 A2 A3 A4 | adjust peak w1,w2,w3,w4 frequency one sweepwidth upfield |
reflect upfield | u1 u2 u3 u4 | reflect peak w1,w2,w3,w4 frequency about upfield boundary |
reflect upfield | d1 d2 d3 d4 | reflect peak w1,w2,w3,w4 frequency about downfield boundary |
assignment copy | ac | remember peak assignments for assignment paste |
assignment delete | aD | delete the assignments of selected peaks |
assignment paste | aP | paste assignments onto peaks in this spectrum |
assignment paste & label | ap | copy assignments and show labels |
assignment tool... | at | make assignments |
delete unused resonances | dr | delete resonances not used in any peak assignments |
integration tool... | it | select integration method |
sum over box method | ib | switch to box integration method |
sum over ellipse method | ie | switch to ellipse integration method |
Gaussian fit method | ig | switch to Gaussian fit integration |
Lorentzian fit method | il | switch to Lorentzian fit integration |
integrate selected peaks | pi | |
ornament copy | oc | record ornaments for future paste operation |
ornament paste | op | paste ornaments into this spectrum |
center peaks | pc | center selected peaks at local maxima or minima. |
estimate linewidths | pe | get linewidth of selected peaks as width at half max |
group peaks | pg | create a peak group from selected peaks |
update heights | ph | reread peak heights from NMR data file |
label peak | pl | put a label on a peak |
unoverlap labels | lu | move labels so they don't overlap each other |
right offset labels | lr | move labels so they are to the right of peak markers |
lock peaks | pk | prevent peaks from moving when integrated |
reintegrate peaks | pr | integrate selected peaks using previous settings |
select all peaks | pa | select all peaks in a spectrum |
unintegrate peaks | pU | forget that a peak has been integrated |
unlock peaks | pu | allow selected peaks to move when integrated |
undo | eu | undo last peak move, deletion, or integration |
w1 resonance peaks | r1 | list assigned peaks with selected peak w1 resonance |
w2 resonance peaks | r2 | show assigments with selected peak w2 resonance |
w3 resonance peaks | r3 | show assigments with selected peak w3 resonance |
assignment... | at | make assignments |
assignment copy... | co | thresholds for copying assignments |
assignment table... | tb | table of chemical shifts |
contour levels... | ct | set contour levels and colors |
integration... | it | set integration method |
midas... | mi | display assignments on a structure using Midas |
ornament... | ot | change ornament colors and sizes |
note... | nt | add notes to peaks |
overlay views... | ol | overlay contours of one spectrum on another |
peak list... | lt | show a list of peaks for a spectrum |
peak picking... | kt | set thresholds for find peak pointer mode |
pointer modes... | pm | show buttons to select pointer mode |
predefined resonances... | pd | copy resonances from another spectrum |
preferences... | pf | set global Sparky options |
print view... | pt | print spectrum views to a Postscript printer |
project view list... | pv | list of views, sizes, peak counts, ... |
python... | py | Python shell for running your own programs |
region... | rt | name regions and apply operations to regions |
rename resonances... | rr | rename atoms and groups |
resonance list... | rl | list group/atom chemical shifts, standard deviations |
spectrum... | st | set molecule and condition, and axis shifts |
synchronize views... | yt | make views scroll in parallel |
view... | vt | options controlling what is displayed in a view |
select | F1 | click or drag to select or move peaks, labels, lines, ... |
center | F2 | clicking centers view on point |
add grid both | F3 | place vertical and horizontal grid lines |
add grid horz | F4 | add a line extending across whole spectrum |
add grid vert | F5 | add a line extending across whole spectrum |
add label | F6 | add a text label to a peak |
add line | F7 | add a horizontal or vertical line between end points |
find / add peak | F8 | click to place a peak or drag to find peaks |
integrate | F10 | click or drag to integrate peaks |
zoom | F11 | drag to select a new region to show |
duplicate and zoom | F12 | drag to zoom and duplicate a view |
assignment copy | sh-F1 | copy assignments from an already assigned spectrum |
assignment guess | sh-F2 | make assignment if there is a unique guess |