XIPP – Multi-Dimensional NMR Analysis Software

Abstract

Here we present the XIPP (eXtensible Interactive Peak Picker) NMR software for analyzing multidimensional NMR data of proteins, DNA, RNA and protein-nucleic acid complexes. XIPP organizes experiments into pre-defined studies and replaces our original PIPP software suite which is no longer supported. Default study types exist for backbone assignment, sidechain assignment, NOE assignment and several relaxation series experiments, used in solution NMR studies. XIPP is written in Java and Jython. The default study types are defined in Jython which can be modified and extended to create new types of studies.

Introduction

Two major advances significantly improved the reliability of structural analysis of proteins and other biological macromolecules by solution NMR. First, the development of two-dimensional homo-nuclear experiments spread proton chemical shifts along two dimensions providing of through-bond (scalar) and through-space (nuclear Overhauser effect, NOE) ¹H-¹H connectivities that allowed proteins up to about 100 residues to be studied (Wüthrich, 1986). These homonuclear 2D experiments were generally plotted on paper and analyzed using light tables. The two-dimensional NMR analysis programs that where created at that time such as ANSIG (Kraulis, 1989) and EASY (Eccles et al., 1991) provided useful bookkeeping of peaks, but generally were not as effective as large plots on light tables for spectral assignment and NOE analysis. The second major development involved the use of ¹⁵N and ¹³C isotopically enriched proteins in concert with 3D and 4D NMR experiments that are now used to analyze proteins as large as 100 kDa (Clore and Gronenborn, 1991; Bax and Grzesiek, 1993; Clore and Gronenborn, 1998). Typically, each 3D spectrum has 64 to 128 planes and a 4D spectrum has in excess of 4096 planes making 3D/4D data virtually impossible to analyze using paper plots. Since the 2D NMR analysis programs that where available at the advent of multi-dimensional NMR were not designed to handle such experiments, new software was required.

The PIPP software suite including CAPP (Garrett et al., 1991), STAPP and ps_contour was one of the first three- and four-dimensional NMR analysis packages available at the advent of hetero-nuclear NMR structure determination (Clore and Gronenborn, 1991). The PIPP software suite was written in C using the XView graphics library to analyze a single multi-dimensional experiment at a time to easily create assigned peak-pick files. PIPP had many useful features that included 3D symmetry, automated and manual peak-picking, quick zooming and selecting a 2D plane in a 3D or 4D spectrum by residue number. Several multi-dimensional NMR analysis programs have been developed over the years that each have their own ardent supporters: ANSIG (Kraulis et al., 1994), XEASY (Bartels et al., 1995), NMRDraw (Delaglio et al., 1995), NMRView (Johnson and Blevins, 1994; Johnson, 2004), NMRFAM-SPARKY (Lee et al., 2015), CARA (Keller, 2004), and CCPN (Vranken et al., 2005; Skinner et al., 2016).

Here we present the XIPP package for analysis of multidimensional NMR data. XIPP is a complete rewrite of the now outdated PIPP software suite (Garrett et al., 1991) and shares many of the features originally developed in PIPP, including the same peak-pick and assignment file format. XIPP was created to overcome two major limitations of PIPP. First, PIPP used 8-bit graphics with the XView graphics library that would require significant effort to port to current computers as most graphics cards currently make use of at least 32 bit graphics and the XView graphics library is no longer actively supported. Second, PIPP was limited to analyzing a single experiment at a time which prevents direct comparison between similar experiments. XIPP organizes NMR experiments into studies which capitalize on properties for each experiment to overlay related experiments and to assign cross-peaks based on experiment type. At the time of publication there are 15 study types defined in XIPP as shown in Table 1.

Table 1.

Types of studies currently available in XIPP.^a

Study	Description
Generic
‘Single Experiment’	Analysis of any single 2D or 3D experiment.
Assignment Studies
‘Backbone Assign’	Analysis of experiments to determine backbone chemical shifts.
‘Sidechain Assign’	Analysis of experiments to determine sidechain chemical shifts.
‘Noesy Assign’	Analysis of 3D and 4D NOESY experiments.
Series/Relaxation Studies
‘Fast Exchange’	Titration series in fast exchange.
‘Fractionation’	Analysis of series of CO(CA)HA experiments.
‘Experiment Series’	Analysis of relaxation rate, CPMG dispersion, CEST and DEST data.
‘Series of Series’	Analysis of 2 or more experiment series.
‘Two-Point Rate’ and ‘Multi-Point Rate’	Analysis of R1 R2 or R1ρ.
‘Two-Point Delta-Rate’ and ‘Multi-Point Delta-Rate’	Analysis of ΔR2 data.
‘Two-Point PRE’ and ‘Multi-Point PRE’	Analysis of PRE data.
‘Two-Point ARTSY’	Analysis of ARTSY data for residual dipolar couplings

^aThese studies are defined as Jython classes that can be modified and extended by knowledgeable users.

The organization of the remainder of the paper is as follows: (1) coding framework: Java, Jython and XML; (2) editing properties for a study; (3) displaying canvas and table windows for a study; (4) assigning triple resonance backbone through-bond correlation spectra; (5) assigning multidimensional NOE spectra; (6) titration experiments in the fast-exchange regime; (7) analyzing relaxation series experiments, and (8) concluding remarks.

1. Coding framework: Java, Jython and XML

XIPP is written in the object-oriented languages Java (Flanagan, 2005) and Jython (Pedroni and Rappin, 2002) with the full source code for each version included in all downloads. Java classes (files with the extension .java) are the source code defining all objects that are shown when XIPP is running. Jython classes (files with the extension .py) are the source code that is used to create and assemble Java objects into XIPP using default properties that are also defined in Jython. Jython is a variation of Python (Beazley, 2009) that easily allows Java objects to be created within the Jython interpreter. Since Jython is the Python language implemented in Java, Jython has the same syntax and file name extension (.py) as Python and can run almost any Python script. Although Jython is a scripted language, the text files that define a study (files with the extension .xipp) are in XML (Harold and Means, 2004) (eXtensible Markup Language) not Jython. The XIPP XML file contains all the unique properties that define one study. Default values for properties and common Java objects are defined in Jython classes (.py). XIPP automatically creates the Jython script ‘startXipp.py’ in the current directory and executes it to show a study which brings up the Canvas and Tables Windows. The startXipp.py Jython script defines the initial Java objects to create and assemble using the properties defined in the XIPP XML file. The startXipp.py script is a required legacy from the initial version of XIPP prior to developing the XML property file (.xipp).

The assignment of peak-picks in XIPP is accomplished using an experiment specific ExpAssigner. (This Font is used throughout the paper to identify Jython and Java classes.) The ExpAssigner is defined in Jython for each type of NMR experiment and dictates the peak-pick assignment protocol through one or more AssignerRule Jython classes. Each AssignerRule defines a protocol for assigning all axes in a peak. There are three types of AssignerRule classes used for amide proton detected experiments: known, extended and new. The known AssignerRule requires that there are known assignments within error in the ShiftTable for all axes of the peak-pick. The extended AssignerRule requires that the peak-pick axes for the backbone amide atoms (H_N, ¹⁵N) are within the error in the ShiftTable and extends the assignment to the third axis (i.e. Cα, Cβ, Cα:−1 or Cβ:−1) by creating a new assignment in the ShiftTable. The new AssignerRule creates new assignments in the ShiftTable for all axes in the peak-pick. The ExpAssigner calls the AssignerRule objects in the order known, extended and new until the first AssignerRule classes reports one or more assignments so that if the known AssignerRule finds assignments then the extended and new protocols are not called. The names of the Jython classes clearly indicate their purpose. The CBCA(CO)NH ExpAssigner has the following AssignerRule classes: CBCACONH_Known, CBCACONH_Extended and CBCACONH_New.

The AssignerRule protocols determine possible peak-pick assignments through a series of Java Action classes. All actions in an AssignerRule protocol are executed in the order defined and modify the same table of possible assignments. Table 2 lists the Java Action classes that are available for use in AssignerRule protocols divided into generators, filters and utility actions. The generator actions modify the table of possible assignments by putting new atom assignments into the table, while the filter actions remove invalid existing assignments from the table. The utility actions perform needed work such as NullAutoAssign that initializes the table of possible assignments at the beginning of every protocol, and AcceptSingleAssign that sets the peak-pick assignment when a single assignment is found in the table at the end of the protocol. Most columns in the table of possible assignments correspond to an observed axis from the peak-pick and has the same name as in the experimental properties that define the order of axis. Additional information, such as distance between protons in the table is calculated from PDB files for NOE studies, and assignment of the unobserved ¹³C atoms in the HCCH-COSY experiment for symmetry can define columns when needed by a protocol. Each row in the table of possible assignments defines a unique atom assignment for the peak-pick. The ExpAssigner and AssignerRule Jython classes are defined for each experiment type in the Jython files (directory ~/Xipp/v1/lib/nmr): assignGenericExps.py, assign2DHHExps.py, assignAmideExps.py, assignHCCHExps.py, assignNoesyExps.py. These are text files that can be copied and edited to modify how XIPP assigns peaks.

Table 2.

List of AssignerRule Java action classes used by experiment specific ExpAssigner to assign cross-peaks.

AssignerRule Java Action class	Description
Generators
AtomsFromBond	Generates atoms that are bonded to assigned Atom.
AtomsFromCoordinateDistance	Generates atoms that are within maxDistance to assigned Atom.
AtomsFromShift	Generates atoms whose assigned shift is within error of peak-pick.
AtomsInMoiety	Generates atoms with existing atoms that are in same Moiety as assigned Atom.
NewAtomlnMoiety	Creates new Atom in same Moiety as assigned Atom.
NewAtomMoiety	Creates new Atom in new Moiety in column atomName.
Filters
AllowMissingShiftFilter	Filters atoms by requiring that assigned Shift of Atom within error of peak-pick. Allows Atom to be missing from ShiftTable
BondFilter	Filters atoms by requiring that they be bonded to assigned atoms.
CoordinateDistanceFilter	Requires filtered atoms to be within maxDistance to assigned atoms.
ExpectedRangeFilter	Filters atoms by requiring peak-pick shift to be within the expected range of shifts for the Atom.
RemoveDuplicateAssign	Filters duplicate assignments where the only difference is HBl|HB2 or HB2|HBl.
ResidueFilter	Filters atoms by requiring that they match residueOffset to assigned atoms.
ResidueRangeFilter	Filters atoms by requiring that residue ID be within pre-defined range, i.e. match part of the sequence.
ShiftFilter	Filters atoms by requiring that assigned shift of Atom is within error of peak-pick for axis. Requires Atom to be in Shift Table or it will be filtered out.
SignFilter	Filters assignment rows by requiring that sign of the peak-pick intensity matches the expected sign.
SingleOffsetFilter	This name is misleading. Filters residue offsets for atoms by requiring that if an extrema peak is found in the linked experiment (e.g. CBCA(CO)NH) then the residue offset is set to −1 or if extrema not found residue offset is set to 0.
SymmetryFilter	Filters assignment by requiring that an extrema peak exist at 3D symmetry location.
Utility
AcceptSingleAssign	Sets peak-pick assign to single assignment if one and only one assignment is found.
AssignedSymmetryLocator	Finds 3D symmetry from assignments.
ExpectedRangeSymmetryLocator	Finds 3D symmetry from expected range of atom types.
ExtremaLocator	Finds extrema based on specific position.
NullAutoAssign	Initial Action for all AssignerRule protocols that clears table of possible assigns.
PrintAssignments	Diagnostic tool that prints all assignments used to debug problems.
PrintAtomsInMoiety	Diagnostic tool that prints all Atom objects in a Moiety for debugging.

2. Editing Properties for a Study

The XippPanel shown in Figure 1 is used to create and edit study properties and to display a study. The study properties include the location of files such as the processed NMRPipe files (Delaglio et al., 1995), peak-pick file(s) and assignment files(s) as well as the protein, DNA or RNA sequence(s). The entries under ‘Studies (by File)’ indicate all of the studies that are defined in the current directory which, in Figure 1, shows all of the examples that are available for download with the XIPP software. The XippPanel is usually the first window shown when XIPP is started and all of the properties in all studies in the current directory are read in and available, allowing a property such as sequence to be entered in one study and easily used in other studies. The study ‘noesy (HPr)’ (defined by file noesy.xipp) and the study ‘noesyNew (HPr)’ (defined by file noesyNew.xipp) are shown in red because there is a problem with their properties. The 4D ¹⁵N,¹³C-NOE (Kay et al., 1990) and 4D ¹³C,¹³C-NOE (Clore et al., 1991) were not downloaded in this example, but the properties defined in noesy.xipp and noesyNew.xipp are configured to show the two 4D data-sets. When the text on a button or an entry in a list is shown in red, this indicates that there is a problem or inconsistency with that item and the study may not show. However, the studies noesy and noesyNew will display without the 4D data since other data-sets have been properly configured and downloaded.

Figure 1.

The XippPanel is the initial dialog displayed when XIPP starts. The entries under ‘Studies (by File)’ are all of the example studies downloaded from the XIPP web-site. The studies ‘noesy (HPr)’ and ‘noesyNew (HPr)’ are shown in red to indicate that there is a problem or inconsistency with the properties defined in the study.

Table 3 identifies the standard double and triple resonance experiments available in the ‘Backbone Assign’ study that are used to obtain backbone assignments of ¹⁵N and ¹³C isotopically-labeled proteins. The experiments are organized into linked groups that share common atoms (due to connectivity) along all axes so that the experiments in the same linked group can be fully superimposed when the study is displayed. The adjustable properties for each experiment include: NMRPipe file, experiment type, linked project, axis order, error range, peak-pick file, contour level and extrema level. Except for the NMRPipe file, most properties assume an acceptable default value. Missing or inconsistently set properties have their text shown in red. Properties only need to be set on experiments that have been collected. However, at least one experiment must be properly defined for a study to be shown. Although every study type has a unique set of experiments the ‘Backbone Assign’, ‘Sidechain Assign’ and ‘NOESY Assign’ studies use the same Java class, LinkedGroupListPanel, for setting their experiment properties.

Table 3.

List of standard experiments in a ‘Backbone Assign’ study.

Connectivity	Experiment
HN,N	1H-15NHSQC
CA|CB,HN,N
	CBCA(CO)NH	HNCACB
	HNCA	HNCB
	HN(CO)CA	HN(CO)CB
HA|HB,HN,N
	HBHA(CO)NH	HBHANH
	HNHA	HNHB
C,HN,N
	HNCO	HN(CA)CO
C*,HN,N
	CDIPSI(CO)NH
H*,HN,N
	HDIPSI(CO)NH	HHN-NOESY
N*,HN,N
	(H)N(COCA)NH	HNN-NOESY

The protein or oligonucleotide sequence and assignment must be defined in a study in order to use the ExpAssigner to assign peaks. The sequence type may be: Protein, DNA, RNA, DNA-Protein Complex or RNA-Protein Complex. Only a single sequence can be given so complexes must follow the PIPP convention of listing a single sequence with spacer residues between different segments. The assignment type may be: ‘Assignment File (PIPP V4)’ or ‘Averaged Assigned Peaks’. The only assignment file format available at publication is the format used by PIPP. The ‘Averaged Assigned Peaks’ is not a single assignment file, it is an in-memory assignment table that is dynamically created for each atom as an average from all assigned peak-picks from the experiments that are currently shown. The in-memory average is created from the peak-pick files when XIPP starts and is updated every time a peak-pick assignment is changed. The ‘Average Assigned Peaks’ is the assignment table type that must be used with the ‘Backbone Assign’ study to create assignments from scratch.

3. Displaying Canvas and Table Windows for a Study

The canvas and table windows in Figure 2 are displayed when a study selected in the XippPanel is shown by clicking the ‘Show’ button. Contours for all experiments in the study are shown in the canvas window with separate views for each linked group that has properly defined experiments in the study. Typically, a study is displayed within 6 seconds after clicking ‘Show’, except when creating the extrema list (described in Sections 4 and 5 for specific experiments) which takes an additional 4 seconds per spectrum (depending on threshold) to read in all planes and find all local extrema. The latter are written to a file so that subsequent clicking of the ‘Show’ command will not re-calculate the extrema list. The memory required for XIPP is modest as the full NMR data is not kept in memory and only regions needed for specific tasks are read such as a full 2D plane for contouring or a cube around a peak being picked. The combined resident memory for the ‘Backbone Assign’, ‘Sidechain Assign’ and ‘NOESY Assign’ studies is under 500 MB. In Figure 3A the drop-down menu ‘View Chooser’ shown at point (i) is used to select different linked groups or views defined in the study. For 3D and 4D experiments there are three tools that can be used to select a slice as shown in Figure 3B: point (ii) entering a chemical shift in PPM or slice number in ‘Frequency Slice Chooser’, point (iii) entering residue or spin-system number in ‘Residue Chooser’, and point (iv) when available select an atom from the ‘Atom Chooser’. Displaying a new slice through any of these methods is virtually instantaneous and depends primarily on the number of contours shown. The canvas commands in Table 4 are the keystrokes and mouse actions that are most commonly used while analyzing data. For example, the left mouse button is used to manually add peak-picks and the space-bar is used to toggle the display of the peak-pick ID, label, or assignment to more easily see the contoured NMR data underneath. The table window (Figure 2B) displays tabulated data defined by Jython classes such as: SimplePeakTable, AssignPeakTable, AssignedShiftTable, BackboneAssignTable; and relaxation profile plots defined by classes SymbolTableByResID and SymbolTableByExpValue. The SimplePeakTable is the default table shown when a study is first shown, and the ‘n’ command entered in the canvas window toggles between showing the SimplePeakTable and the other tables types that are presented in a tabbed pane as shown in Figure 2B.

Figure 2.

The canvas and table windows are displayed side by side when a study such as bbNew is shown. These windows show what is observed at the beginning of the analysis with no peaks picked in the canvas window and no assignments in the table window. (A) The canvas window showing a 2D ¹H-¹⁵N HSQC spectrum of ¹⁵N labeled HPr in the presence of unlabeled EIN (Garrett et al., 1999). (B) The table window with two tabs ShiftTable-Hpr Ave@HPr and BAMTable-Hpr_Ave@HPr. There are no assignments because the bbNew study is intended for use with the backbone assign tutorial document available online which describes the generation of backbone assignments from scratch.

Figure 3.

Top of the canvas window displayed for two studies to highlight navigation within and between experiments. (A) Top of the canvas window for study bbNew with ‘View Chooser’ at point (i) open showing selection to CACB_FULL(N) that displays CBCA(CO)NH and HNCACB spectra with ¹⁵N planes. The other views that can be selected are HAHB_Full for HBHA(CO)NH and HNHA spectra, HSQC_Full for ¹H-¹⁵N HSQC experiments, and CACB_Full (C) for CBCA(CO)NH and HNCACB spectra with ¹³C planes. (B) Top of the canvas window for study noesy showing three ways to select a plane: (ii) enter PPM or slice number, (iii) enter residue number or spin-system ID, and (iv), when available, select atom from drop-down list of assigned atoms in selected residue.

Table 4.

List of common commands available on the Canvas Window^a

Command	Description
e	Exits all studies and exits XippPanel after saving data.
n	Toggle Table between showing SimplePeakTable and other table types such as AssignPeakTable used to assign recent peak-picks.
Click Left-Mouse	Create or select one PeakPick at mouse position and show assignments in AssignPeakTable.
Click Right-Mouse	Delete an existing PeakPick at mouse position.
Drag Left-Mouse	Vector add PeakPick. Create Fast-Exchange series of PeakPick objects.
Drag Right-Mouse	Vector delete PeakPick.
Space-Bar	Toggles display of peak labels and traces to quickly see the spectra.
f	Full display. Change display X,Y to show full view.
Click Middle Mouse	Initiate zoom box centered at current mouse position. While zoom box is displayed left and right mouse buttons increase and decrease zoom box size and the middle button sets display to zoom box size and clears zoom box. Double click the middle mouse button to quickly zoom at current position.
o (letter O)	Orientation: Swap X, Y orientation in display.
Down-Arrow	Scroll to next slice for 3D data. Increases slice number by 1.
Up-Arrow	Scroll to previous slice for 3D data. Decreases slice number by 1.
j	Jump to specific slice or PPM value for 3D data.
Alt-Down-Arrow	Scroll to previous Residue ID. Decreases residue ID by 1.
Alt-Up-Arrow	Scroll to next Residue ID. Increases residue ID by 1.
Alt-j	Jump to specific Residue ID or spin-system ID (SSID).
h	Display trace going horizontally at current mouse position.
v	Display trace going vertically at current mouse position.
z	Perpendicular trace along Z axis. Display a Z trace at current mouse position horizontally. Only available with 3D and 4D data.
a	Perpendicular trace along A axis. Display an A trace at current mouse position horizontally. Only available with 4D data.

^aMost of the commands are a single keystroke or mouse action. However, some require holding down a modifier key such as the Crtl or Alt key while the key is being clicked.

4. Assigning Triple Resonance Backbone Through-Bond Correlation Spectra

The ‘Backbone Assign’ study is used to generate residue specific protein backbone assignments such as H_N, ¹⁵N, Cα, Cβ, C, Hα and Hβ shifts from scratch. Typically, 2D ¹H-¹⁵N HSQC and 3D HNCO, 3D CBCA(CO)NH and 3D HNCACB experiments are analyzed to identify chemical shifts for backbone atoms. To make backbone assignments from scratch, the assignment table type must be set to ‘Average Assigned Peaks’ and the ‘Use Backbone Assign Map’ must be enabled. The Java class BackboneAssignMap records the residue number for each spin-system ID (SS-ID) as it gets assigned which is saved into an XML file with the extension .bam. Overall there are four actions involved in the process of determining residue specific assignments: (1) create a list of peak-picks for each experiment, (2) assign observed chemical shifts for each axis in a peak-pick into arbitrary spin-systems defined by backbone amide H and ¹⁵ N N chemical shifts, (3) connect sequential spin-systems based on ¹³Cα, and ¹³Cβ intra and inter-residue connectivities, and (4) map sequential spin-systems to the known sequence. In practice, multiple actions are carried out at the same time, and the process is iterative, requiring modifications to the peak-pick lists and assignments of peaks after spin-systems have been mapped to the sequence.

Peak-pick lists can be created manually by pointing the mouse at a peak and clicking the left mouse button or automatically via the external C program CAPP (Garrett et al., 1991). In both cases the chemical shift is interpolated around a nearby local extrema by fitting the top three points to a parabola independently for each axis. The interpolated backbone amide (H_N and ¹⁵N) chemical shifts are used to define spin-systems from peaks that share the same backbone amide shifts. Manually created peak-picks are automatically assigned using an ExpAssigner configured for the experiment. The ExpAssigner classes for the 2D ¹H⁻⁵N HSQC and 3D HNCO experiments are the only classes that automatically create new spin-system IDs because the new AssignerRule protocols for these experiments ends with the AcceptSingleAssign Action that will automatically accept the assignment for a peak-pick, if and only if, the table of possible assignments has a single assignment. The new AssignerRule protocols for all other backbone experiments do not end with AcceptSingleAssign. The ExpAssigner for other experiments requires that the spin-system already exists in order for the peak to be automatically assigned. The 2D ¹H-¹⁵N-HSQC and/or 3D HNCO should always be analyzed first so that spin-systems are created. After the spin-systems are created it is best to analyze experiments with the smallest number of peaks first; for example, the 3D CBCA(CO)NH spectrum should be analyzed prior to the 3D HNCACB spectrum.

Automated peak-picking is initiated in XIPP from the CAPP Dialog (Figure 4) to create a peak-pick list that is read into XIPP. When the flag ‘Assign Peaks Using Xipp’ is enabled as shown in Figure 4, CAPP-created peaks are assigned as they are read into XIPP using the same ExpAssigner that is used with manual peak-picking. The default settings for CAPP (not shown) are usually acceptable for most triple resonance experiments. An exception is that highly zero-filled data will require widening the values for the ‘Ellipse Fitting’ properties ‘Min Radius (Hz)’ and ‘Max Radius (Hz)’ which are too small in highly zero-filled data. Although CAPP has been shown to be 82% efficient in peak-picking under good conditions (Garrett et al., 1991), it is highly recommended that the CAPP created peak-pick list always be manually inspected and edited in XIPP for accuracy and completeness. Extraneous noise peaks created by CAPP can be deleted by clicking the right mouse button over the peak which will also remove any assignments based on that peak.

Figure 4.

Top of CAPP auto peak-pick dialog for the CBCA(CO)NH experiment. The flag ‘Assign Peaks using Xipp’ must be manually toggled on in order to assign the CAPP created peaks as they are read into XIPP after CAPP finishes.

The table window showing the AssignedShiftTable (Figure 5) lists all of the residues and spin-systems that have assigned atoms sorted first by residue ID and then by spin-system ID. Since the assignment table type is ‘Average Assigned Peaks’, the value for the shift is an average from all observations with a rmsd and count of observations. The display of the full list of peak observations for an assignment shown in Figure 5A can be toggled on/off by clicking the left mouse button on the AtomID (button labeled 12495). Clicking the right mouse button on the AtomID button (12822) brings up the pop-up menu shown in Figure 5B which can be used to quickly assign glycine ¹³Cα atoms as XIPP has difficulty specifically assigning these.

Figure 5.

Assignment table for spin-system ID #12494 after auto peak-picking with CAPP 2D ¹H-¹⁵N HSQC, 3D CBCA(CO)NH and 3D HNCACB spectra of ¹⁵N-labeled HPr in the presence of unlabeled EIN (Garrett et al., 1999). (A) The ¹⁵N assignment atom sub-table is manually expanded to list all of the peak-picks used to assign the ¹⁵N atom and show the deviation from the running average. The + or – on the button label after the spin-system ID or atom ID indicates whether the sub-table is open + or closed −. By default, all spin-system ID sub-tables are open, and all atom ID sub-tables are closed. (B) The pop-up menu from atom ID 12822 which assigns CA|CB:−1 to 46.8 PPM. Selecting CA:−1 from the pop-up menu creates a new atom ID for CA:−1 and assigns it to 46.8 PPM by changing the two peak-pick assignments defined in atom ID 12822 to the new CA:−1 atom.

The automated backbone assignment program MARS (Jung and Zweckstetter, 2004; Narayanan et al., 2010), developed by Jung and Zweckstetter, can be configured and started from XIPP using the MARS Dialog (Figure 6) which will make residue specific assignments for well-defined spin-systems (called pseudo-residues in MARS). The default values (not shown) for the MARS Dialog produce very good results as long as the peak-pick lists have been curated for accuracy (e.g. resolve degeneracy, remove picked noise peaks and add missing real peaks). MARS creates several files and is designed to be run iteratively to obtain the best results, but XIPP only uses the results from the file assignment_AA.out to assign spin-systems to specific residues that updates the BackboneAssignMap and BackboneAssignTable. Although it is safe to run MARS multiple times from XIPP, it will always start from scratch (no spin-systems assigned) since XIPP ignores the flag “Create Fix Assign File from Previous Backbone Assign Map” so that manual assignments will be lost on successive runs of MARS. The full set of properties available from MARS are not accessible from XIPP. To get different results from running MARS multiple times the peak-pick list and or atom assignments in spin-system must change. The results of running MARS independently of XIPP (not starting MARS from XIPP’s MARS Dialog) cannot be used to update assignments in XIPP.

Figure 6.

Top of the MARS dialog used to configure and start the MARS automated assignment program from within XIPP. The assignment results of MARS are read back into XIPP after MARS finishes.

The table window showing part of the BackboneAssignTable in Figure 7 is automatically updated after reading in the MARS results and is also updated after every manual change to the assignment table. The BackboneAssignTable is sorted first by residue ID and then by unassigned spin-system ID with the columns labeled Res-ID and SS-ID. A specific SSID can only appear once in the BackboneAssignTable so that when a spin-system is assigned it will only appear next to its assigned Res-ID. The color of the Res-ID and SS-ID text indicate the quality of the spin-system assignment based on the number of sequential matches for unambiguously assigned atoms. Green indicates good assignment, pale orange intermediate assignment, red poor assignment, and black unassigned. The BackboneAssignTable identifies possible adjacent spin-systems in pop-up menus by matching Cα(i,i) with Cα(i,i-1) and Cβ(i,i) with Cβ(i,i-1) between spin-systems as well as assigning residues and spin-systems. In addition to matching on Cα and Cβ, XIPP can also use Hα, Hβ and C’. The popup menu for the Res-ID button T16 shown in Figure 7B is used to jump by residue and assign or unassign the residue. The sub-menu shown in Figure 7B from ‘2 Columns Matched’ can be used to assign this residue to spin-system #12686. The color of the text indicates the quality of assignment for the spin-system in its current assignment or black if unassigned. The popup menu for SS-ID #12557 shown in Figure 7C is used to jump by spin-system, find adjacent spin-systems, show possible previous and current residue types, and assign or unassign this spin-system. The ‘Find Next SS-ID’ sub-menu shown in Figure 7C is used to update the canvas and table windows to show the current spin-system and next spin-system to determine whether the putative next spin-system is a good match with the current spin-system. As with the Res-ID sub-menu the color indicates the quality of assignment for the spin-system in its current assignment. Note that #12686 is suggested as the best assignment for T16 from both popup menus: T16 ‘2 Columns Matched’ and #12557 ‘Find Next SS-ID’ which re-inforces the assignment of #12557 to H15.

Figure 7.

The BackboneAssignTable shown here is used to interactively assign a spin-system to a single residue to update the BackboneAssignMap. (A) The BackboneAssignTable displaying G13 to V23 with spin-system assignments. The color of the text for the residue ID and spin-system ID (SS-ID) indicates the quality of the assignment from good (green), intermediate (pale orange) to poor (red). Unassigned residues and spin-systems are shown in black. (B) The ‘Residue menu’ for T16 with ‘2 Columns Matched’ selected shows that the unassigned SS-ID #12686 as the most likely spin-system assignment for T16. (C) The ‘Spin-System menu’ for SS-ID #12557, assigned to H15, shows the unassigned SS-ID #12686 as the most likely next spin-system based on all currently assigned backbone assignments for Cα, Cα:−1, Cβ and Cβ:−1.

The ‘Find Prev SS-ID’ and ‘Find Next SS-ID’ menu options are used to update the canvas and table windows to visually determine whether a putative previous or next spin-system matches with the current spin-system. In the example shown in Figure 7C, the current SS-ID, #12557, is assigned to H15 and the selected putative next SS-ID is #12686. Figure 8 identifies the three changes that occur after selecting #12686 as the putative next spin-system: (1) the assigned peak-picks for H15 (#12557) are added to the AssignPeakTable as if manually peak-picked, (2) the canvas window is jumped to residue H15 since #12557 is assigned to H15, and (3) the canvas view ‘Seq-CBCA(CO)NH’ is set to #12686 which uses chemical shifts from #12686 to select the 2D plane for the view ‘Seq-CBCA(CO)NH’ ¹⁵N (112.97 ppm) and display three PpmCursor objects shown in red using #12686 assigned atoms for HN (7.84 ppm), Cα:−1 (54.79 ppm), and Cβ:−1 (29.77 ppm). Figure 8A shows the addition of the peaks for Cα and Cβ from H15 (#12557) to the AssignPeakTable. Figure 8B shows the canvas window with only two experiment views enabled: (1) the ‘HNCACB’ view at H15 drawn with purple and pale orange contours, and (2) the ‘Seq-CBCA(CO)NH’ view at #12686 drawn with green contours. The pale white vertical PpmCursor at 7.03 ppm identifies the H15 amide HN position and is part of the ‘HNCACB’ view. The two-red horizontal PpmCursor objects from #12686 in the ‘Seq-CBCA(CO)NH’ view at 54.79 ppm and 29.77 ppm align perfectly with the contours for the intra-residue Cα and Cβ peaks in the ‘HNCACB’ view for H15 which visually confirms that #12686 follows #12557 in the sequence. After confirming that #12686 has Cα and Cβ intra-residue shifts in the correct region for a Threonine, T16 is assigned to #12686 by selecting #12686 from the sub-menu as shown in Figure 7B.

Figure 8.

Updates observed on the table and canvas windows following selection of spin-system ID (SS-ID) #12686 as the putative next assignment from SS-ID #12557 as shown in Figure 7C. (A) The AssignPeakTable automatically adds peaks from ‘H15 (#12557)’ Cα and Cβ to show possible assignments. (B) The canvas window ‘Seq-CBCA(CO)NH’ view is updated to show slice 112.97 PPM (#12686 ¹⁵N) and 3 PpmCursor objects are added and shown in red at: 7.84 PPM (#12686.HN), 29.77 PPM (#12686.CB:−1), 54.79 PPM (#12686.CA:−1). Note the ‘Seq-CBCA(CO)NH’ view must be manually displayed by clicking the button labeled ‘Seq-CBCA(CO)NH’.

The ‘Sidechain Assign’ study defines the experiments, including for example ¹⁵N-separated DIPSI(CO)NH and HDIPSI(CO)NH, and ¹³C-separated HCCH-COSY and HCCH-TOCSY, used to readily assign sidechain atoms by extending the assignments from the backbone atoms. The ExpectedRangeFilter, SignFilter and ExpectedRangeSymmetryLocator (defined in Table 2) are used to generate assignments from peaks with shifts that are consistent with the atom type being assigned.

5. Assigning NOE Spectra

The ‘NOESY Assign’ study is used to assign NOE peaks in order to generate distance restraints for structure calculations using software such as Xplor-NIH (Schwieters et al., 2006). The 3D ¹⁵N-separated and ¹³C-separated NOE (including variations that evolve on ¹⁵N or ¹³C instead of ¹H_in one of the indirect dimensions) provide the bulk of the NOE distance restraints for isotopically labeled proteins. Each assigned NOE peak defines a distance restraint between a pair of protons. Although peaks are assigned in the same way as in the ‘Backbone Assign’ study by clicking on the peak, there can be a large number of possible assignments for a NOE peak arising from chemical shift degeneracy. As such, it is not advisable to use automatic peak-picking with CAPP to assign 3D NOE spectra. The last action in most AssignerRuleprotocols is to automatically assign the peak, if and only if, a single assignment is found. This criterion fails for many peaks in a NOE experiment. Manually selecting a specific assignment from the table of possible assignments in the AssignPeakTable assigns the peak interactively in XIPP.

The AssignerRule protocols for the 3D ¹³C-separated NOE experiment includes the actions SignFilter, CoordinateDistanceFilter and SymmetryFilter which eliminate some incorrect assignments generated by relying on chemical shift alone. The 3D ¹⁵N-separated NOE AssignerRule protocols include CoordinateDistanceFilter and SymmetryFilter but does not include a SignFilter. The SignFilter requires that the sign of the peak match the expected sign based on the number of times the chemical shift of the ¹³C atom has been folded into the observed spectrum. The SignFilter is automatically enabled when the experiment property ‘Base Peak Sign’ that indicates the sign of an unfolded chemical shift is set to Positive or Negative. The SignFilter is disabled when the ‘Base Peak Sign’ is set to Unknown. The CoordinateDistanceFilter requires that the pair of protons in the assignment be less than or equal to the experiment property ‘Max Distance’. Methyl proton coordinates are averaged to a pseudo-atom that is used in the CoordinateDistanceFilter. The CoordinateDistanceFilter is only enabled when a structure atomic coordinate file (in PDB format) is defined for a NOE study.

The SymmetryFilter leverages the inherent 3D symmetry of the 3D ¹³C-separated NOE, HCCH-COSY and HCCH-TOCSY experiments by requiring that an extrema peak exist at the correct symmetry location for a possible assignment to be kept. Enabling the ‘Use Extrema’ property enables the SymmetryFilter and creates a list of all local extrema peaks when the study is started for the first time. The extrema peaks are created from all local maxima and minima data points above the minimum contour threshold using the same 3-point parabola interpolation used for peak-picking. The SymmetryFilter can be toggled on/off while peak-picking in XIPP via popup menu options from the button labeled ‘HHC-Noe’ on the canvas window and the ‘K+ button’ on the AssignPeakTable in the table window for a recently picked peak. With the SymmetryFilter disabled, Figure 9A shows the AssignPeakTable with two possible assignments for peak ID 112: “A65.CA,HA; I33.HA” or “A65.CA.HA; S46.HA”. When the SymmetryFilter is enabled only the assignment “A65.CA,HA; I33.HA” remains since there is an extrema peak at “I33.CA,HA; A65.HA” but not at “S46.CA,HA; A65.HA”. The SymmetryFilter works by only keeping assignments which have an extrema peak at the 3D symmetry location. The SymmetryFilter does not require that the symmetry peak be peak-picked since the SymmetryFilter uses the list of all interpolated local extrema. The SymmetryFilter will fail when the symmetry location is not in the extrema list, for example as might be the case for a weak peak under the contour threshold or for the shoulder of a stronger peak. Figure 9B shows two slices superimposed from the same 3D ¹³C-separated NOE spectrum: slice 4 at the chemical shift of A65 Cα in magenta contours shows the peak that was picked (ID 112) at (i) whose display is toggled by clicking the button labeled ‘HHC-Noe’ and slice 68 at the chemical shift for I33 Cα in green contours that shows the symmetry at peak (ii) whose display is toggled by clicking the button labeled ‘Sym-HHC-Noe’. The slice shown in view ‘Sym-HHC-Noe’ is set by selecting slice 68 from the AssignPeakTable as shown in Figure 9A and can be changed to an arbitrary slice via a popup menu from the button ‘Sym-HHC-NOE’. The proton error ranges for locating the 3D symmetry peak are indicated by the small red box at position (ii) in Figure 9B which also serves to differentiate between the peak that was picked at (i) and the 3D symmetry peak at (ii). The SymmetryFilter for the 3D ¹⁵N-separated NOE experiment works the same way as in the 3D ¹³C-separated NOE experiment except only for NOEs between amide protons. The SymmetryFilter for the 3D ¹⁵N-separated NOE experiment must be manually toggled off in order to assign aliphatic peaks.

Figure 9.

The table and canvas windows showing 3D symmetry in a 3D ¹³C-separated NOE spectrum for A65.Cα, Hα of ¹⁵N/¹³C-labeled HPr in the presence of unlabeled EIN (Garrett et al., 1999). (A) The AssignPeakTable in the table window showing possible assignments and symmetry peaks after creating peak-pick ID 112 shown in (B) at position (i) with the SymmetryFilter not enabled. (B) The canvas window showing contours from two separate slices: magenta contours from A65.CA which are toggled on/off via the button labeled ‘HHC-Noe’ and green contours from the selected symmetry plane at slice 68 which are toggled on/off via the button labeled ‘Sym-HHC-Noe’. The symmetry slice shown in the canvas window is initially selected by choosing a symmetry peak from symmetry table in AssignPeakTable such as slice 68 selected in (A) and shown in (B).

6. Titration Experiment in the Fast Exchange Regime

The ‘Fast Exchange’ study is used to assign peaks in a titration experiment series such as a set of ¹H-¹⁵N HSQC spectra recorded on samples containing at least two components interacting in the fast exchange regime on the chemical shift time scale. The concentration of the labeled (¹⁵N) component is fixed while the second unlabeled component has increasing concentrations in different samples. Provided that the interaction is in the fast-exchange regime, the chemical shifts from the labeled species should vary linearly between its value with no ligand at position (i) and the value fully bound at position (ii) as shown in Figure 10. When setting up the ‘Fast Exchange’ study the experiment property fractional offset must be set for each experiment in the series. The fractional offset is the expected fractional offset from the first to the last experiment in the series and must be between 0.0 and 1.0 inclusive with the first experiment set at 0.0 and the last at 1.0. Vector peak-picking the series is accomplished by depressing the left mouse button at one end of the fast exchange set of peaks and releasing the button after dragging the mouse to the opposite end of the peaks. This defines the magnitude of the chemical shift changes during the course of the titration for the observed atoms, H_N and ¹⁵N. Vector peak-picking uses the fractional offset for each experiment in the series and the magnitude of the chemical shift changes between the end points of the series of peaks to calculate a starting position to peak-pick each experiment in the series. The starting positions are optimized to finda nearby local extrema and interpolated just as if each experiment in the series was individually clicked with the left mouse button to manually peak-pick at each calculated starting position. The peak-picks that are created by vector peak-picking will have the same peak ID. Assignments or labels from any experiment in the series can be copied from one experiment to all experiments by first copying an assigned peak into the ‘move peak buffer’ before doing vector peak-picking as described in the Xipp_Commands documentation.

Figure 10.

Canvas window showing a titration experiment comprising six ¹H-¹⁵N HSQC spectra of ¹⁵N-labeled HPr in the presence of varying concentrations of unlabeled EIN (Garrett et al., 1997). The complex is in fast exchange and the peaks shown are from L50. ‘Exp_1’ is the reference sample that contains only ¹⁵N-labeled HPr and its contours are shown in pale white at the lower right corner of the spectrum at position (i). The concentration ratio of EIN to HPr in ‘Exp_2’ through ‘Exp_6’ is 0.25, 0.5, 0.75, 1.0 and 1.2. Exp_5 and Exp_6 overlay perfectly at position (ii).

7. Analyzing Relaxation Series Experiments

The nine studies comprising the relaxation series are used to generate profiles for relaxation rates (R₁, R₂, R_1ρ), lifetime line broadening or differences in R₂ values (ΔR₂) between samples, PRE, relaxation dispersion, CEST and DEST (Anthis and Clore, 2015) experiments for detailed kinetic modeling by in-house programs written in MATLAB. The profiles generated are keyed by residue-ID or peak-ID to tabulate intensities, intensity ratios or rates in a results files that is automatically created while peak-picking. The table window displays the profiles as a plot for immediate confirmation of the quality of the profile (e.g. of intensities as a function of time in a R₁ experiment). The default experiment type for all series is of the 2D ¹H-¹⁵N HSQC variety whose ExpAssigner differs from the ExpAssigner for the ‘Backbone Assign’ study in that it cannot create new spin-systems. A single click on a peak in the canvas window will peak-pick the same peak in all experiments of the series, assign each peak, calculate derived data such as relaxation rates and update the plot(s).

Relaxation rate experiments are analyzed using either a ‘Two-Point Rate’ study or a ‘Multi-Point Rate’ study depending on the number of experiments collected. The table window displays the plot of rate versus residue-ID for a ‘Two-Point Rate’ and ‘Multi-Point Rate’. The ‘Multi-Point Rate’ includes a plot of intensity versus relaxation delay as shown in Figure 11 which displays ¹⁵N-R₂ data for the ¹⁵N-labeled A39V/N53P/V55L mutant of Fyn SH3 (Libich et al., 2015). The decay rate for a ‘Two-Point Rate’ is calculated analytically while the ‘Multi-Point Rate’ is optimized by fitting the intensities to a linearized form of the rate constant R: ln(I) = ln(I₀) + Rt, where I is intensity at time t, I₀ is the amplitude at t = 0, R rate constant. Clicking a residue button in the bottom panel of Figure 11 will residue jump the canvas window to that residue. The vertical line labeled G34 in the top panel is synchronized to the most recent residue selected on the canvas window.

Figure 11.

Table window for the ‘Multi-Point Rate’ study on ¹⁵N-labeled Fyn SH3^VPL (Libich et al., 2015). The top panel is the profile of the calculated rate keyed by residue ID. The vertical line labeled G34 matches the most recent residue jump. The bottom panel shows the intensity of peaks for E33 and G34 versus the relaxation delay from the experiment series.

PRE and ΔR₂ experiments are analyzed using a ‘Two-Point PRE’, ‘Two-Point Delta Rate’, ‘Multi-Point PRE’ or ‘Multi-Point Delta Rate’. As far as XIPP is concerned the difference between a ‘PRE’ study and a ‘Delta Rate’ study is primarily semantics since both types of studies involve the difference between a pair of decay rate constants. The canvas and table windows for a ‘Multi-Point Delta Rate’ are shown in Figure 12. The canvas window in Figure 12A has three views: overview (shown), Ref and Test. The overview shows the first experiment from the Ref and Test multi-point rate series which each have six 2D ¹H-¹⁵N HSQC type experiments. The Ref view is the same as the ‘Multi-Point Rate’ shown in Figure 11, which is the reference sample of ¹⁵N-labeled Fyn SH3^VPL. The Test view is the sample containing ¹⁵N-labeled Fyn SH3^VPL interacting with unlabeled GroEL, a molecule ~900 kDa in molecular weight (Libich et al., 2015). Peak-picking in the overview will peak-pick the same position in the Ref and Test experiments creating the same peak-ID in all 12 experiments. The rate for the reference and test samples are calculated as in the ‘Multi-Point Rate’ study and then the ‘delta-rate’ is calculated as the difference. The table window plots shown in Figure 12B displays profiles for Ref, Test and ‘delta-rate’ as well as selected peak intensities.

Figure 12.

The canvas and table window for the ‘Multi-Point Delta-Rate’ study on ¹⁵N-labeled Fyn SH3^VPL in the absence (reference sample) and presence (test sample) of unlabeled GroEL (Libich et al., 2015). (A) The canvas window expanded around G34 with the ‘View Chooser’ pop-up menu showing three views: overview, Ref and Test. The overview view (shown) displays the first experiment from the reference and the test experiment only. The Ref and Test views (not shown) display the multi-point rate for the reference and test samples. (B) The table window shows two panels: the top panel plots three rate profiles: Ref, Test and deltaRate while the bottom panel plots the peak intensities for E33 and G34 as a function of relaxation delay for Ref and Test rate series. Although the E33 Ref peak intensities overlap with the G34 Test peak intensities, the display of an individual set of peak intensities can be toggled on and off by clicking the appropriate button under Ref or Test to focus on either the E33 or G34 intensity profiles.

Relaxation dispersion, CEST and DEST experiments are analyzed using the ‘Experiment Series’ study. The canvas and table windows for a relaxation dispersion on ¹⁵N-labeled Fyn SH3^VPL (Tugarinov et al., 2015) is shown in Figure 13. Figure 13A shows 25 superimposed 2D ¹H-¹⁵N HSQC type experiments residue jumped to T47. Figure 13B shows the dispersion profile for T47 which has a large R_ex and G45 which displays no R_ex. The R_ex is the difference between 0 and 1 KHz CPMG field. Clicking a symbol under rate in Figure 13B toggles the display of the profile for the corresponding residue.

Figure 13.

The canvas and table window for a ¹⁵N CPMG relaxation dispersion experiment on ¹⁵N-labeled Fyn SH3^VPL (Tugarinov et al., 2015). (A) The canvas window expanded around T47 with 25 CPMG 2D experiments overlayed. Each numbered button near the top represents a separate 2D ¹H-¹⁵N correlation experiment at a different CPMG field strength. (B) The table window in which R_2,eff is plotted as plotting rate as a function of CPMG field strength for T47 (large dispersion) and G45 (minimal dispersion).

8. Conclusion

This brief overview of XIPP demonstrates several useful features of the software but obviously cannot fully describe all features due to length considerations. The software, documentation and example datasets can be downloaded from https://spin.niddk.nih.gov/dgarrett/Xipp/xipp.html which includes full source code. The documentation, which contains additional details on using XIPP, includes the PDF files: createSetStudies, Xipp_Commands, backboneAssignStudy, noesyAssignStudy and seriesAssignStudies. XIPP has been designed to optimize the analysis of specific types of NMR experiments together using pre-defined studies and as such may be less useful in analyzing other NMR data such as homonuclear 2D datasets.

One of the goals for XIPP has been to make it simple to modify and/or extend its capabilities, for example by creating new study types. The studies defined in Table 1, as well as the ExpAssigner and AssignerRule protocols described in Sections 1, 4 and 5, were designed to be extended so that anyone can create new studies and experiment types by editing the relevant Jython text files. Other elements of XIPP are straight-forward to modify providing one is comfortable programming in Java and Jython and understands how XIPP is organized. A future version of XIPP is planned that will replace Jython with XML to simplify extending many aspects of XIPP and unify property editing through the XippPanel with a shown study.