Xplor‐NIH for molecular structure determination from NMR and other data sources

Abstract

Xplor‐NIH is a popular software package for biomolecular structure determination from nuclear magnetic resonance (NMR) and other data sources. Here, some of Xplor‐NIH's most useful data‐associated energy terms are reviewed, including newer alternative options for using residual dipolar coupling data in structure calculations. Further, we discuss new developments in the implementation of strict symmetry for the calculation of symmetric homo‐oligomers, and in the representation of the system as an ensemble of structures to account for motional effects. Finally, the different available force fields are presented, among other Xplor‐NIH capabilities.

Introduction

Xplor‐NIH1 is a software package for biomolecular structure determination from various experimental data sources combined with known geometric data. Structure determination is achieved by seeking the minimum of a target energy function comprising terms for the experimental restraints, covalent geometry and non‐bonded contacts using a variety of optimization procedures such as molecular dynamics in Cartesian and torsion angle space, Monte Carlo methods and conventional gradient‐based minimization.

Xplor‐NIH was originally derived from XPLOR2 version 3.851 and contains all of the functionality therein. While this legacy component is supported and readily accessed, a completely reworked framework with a Python scripting language front end has been the basis of development for the past 15 or so years.

Xplor‐NIH is written in a combination of languages, with the older XPLOR interface coded in Fortran 77. This component corresponds closely to XPLOR 3.851, with some additions, bug fixes and enhancements. One major change to the Fortran code was the removal of all structure‐based limits, so that the maximum number of atom, bonds, and so forth, is now determined by the amount of the computer's random access memory (RAM), and not by precompiled constants. Most recent computationally intensive code has been developed in the C++ language, with interfaces to the Python and Tcl scripting languages generated automatically with the SWIG package.3 Most of Xplor‐NIH's code is now being developed directly in the Python language, and thus is directly accessible for modification by the end‐user without recompilation, while code paths which require high performance, such as those executed at every timestep of molecular dynamics, are coded in C++. The Python interface to Xplor‐NIH provides an extensible toolbox for developing further functionality. Precompiled packages for most popular Unix and Unix‐like operating systems (such as Linux and Mac OS X), as well as documentation and support are available directly from http://nmr.cit.nih.gov/xplor-nih/. The full source code package is available by email request to requests@nmr.cit.nih.gov. Xplor‐NIH is freely available (in both source and executable formats) for research purposes. For commercial use of Xplor‐NIH, contact C.D.S.

Xplor‐NIH is a collaborative effort, with groups worldwide contributing advice and computer code. Additional contributions are particularly encouraged as these are advantageous to the contributors as well as to other end‐users. New contributions should adhere to Xplor‐NIH coding conventions, and be accompanied by appropriate testing scripts to assure reproducible future operation.

This article provides an overview of the current state of Xplor‐NIH, and references an earlier review4 where features have not changed. The previous general description of Xplor‐NIH was published 11 years ago,4 and this work documents the significant changes and enhancements which have been implemented since then.

Here we assume some familiarity with the Python language as example code is included throughout. For a good introduction to the language see Ref. 5. This article is organized as follows. The following Section presents a brief introduction to the Python interface. This is followed by an introduction to some of the most often used energy terms in structure determination, along with Python example code. The next Section details commonly used force fields. This is followed by an overview of Xplor‐NIH's new strict symmetry facility, and then an update on the use of facilities for ensemble refinement, including population optimization. The following Section covers new standard data formats supported by Xplor‐NIH. The final Section presents other Xplor‐NIH facilities, including external helper programs.

Overview of the Python Interface

In the most common use of Xplor‐NIH, an energy metric is minimized by a combination of simulated annealing using molecular dynamics, and gradient minimization. The energy metric is a sum of terms corresponding to experimental, chemical and knowledge‐based restraints. Experimental restraints include traditional NMR restraints, such as those based on interatomic distances obtained from Nuclear Overhauser Effect (NOE) experiments, and torsion angles, obtained from chemical shifts or scalar coupling data. Chemical restraints consist of those corresponding to covalent geometry and a desire to prevent atomic overlap. Knowledge‐based terms restrain structures based on statistical trends seen in a database of structures, an example of which is an energy term which biases torsion angles to regions of dihedral angle space that are populated by well‐defined regions in high‐quality crystal structures.

Atomic properties such as Cartesian coordinates, atom names, masses, and so forth are contained in a Simulation object. The default Simulation is a xplorSimulation.XplorSimulation object which can be accessed as xplor.simulation. The coordinates in xplor.simulation are mirrored in the XPLOR interface. A separate set of atomic properties can be created by instantiating a new XplorSimulation object, which will be associated with a separate Unix process. For instance, an extra XplorSimulation object can be useful for holding coordinates of a homologous structure for comparison or to be used as a restraint. Other simulations are used with ensemble and strict symmetry calculations as described below. Direct access to atomic properties can be obtained via methods of a simulation object, or using an atomSel.AtomSel object. Commands in the old XPLOR language can be executed by calling the command method of xplor.simulation.

The atom selection language is almost identical to that in the XPLOR interface and is documented in the atomSelLang module. Additions to the selection language include the INDEx keyword which allows one to reference atoms by their internal 0‐offset reference number, the PSEUdo keyword which selects all pseudo atoms, and the RECAll keyword which allows one to reference by name an atom selection previously defined by the atomSelLang.setNamedSelection function.

Atomic coordinates can be read and written using a pdbTool.PDBTool object, but in most scripts, higher level functions perform this function. For instance, coordinates are most often read using protocol.initCoords or protocol.loadPDB, which also understand how to convert atom names from different schemes to those used in Xplor‐NIH. Coordinates are most easily written using the protocol.writePDB function, or by the automatic facilities provided by simulationTools.StructureLoop. Torsion angles can be set to nominal values from a XPLOR‐formatted restraint table using the torsionTools.setTorsionsFromTable function. On the other hand, the monteCarlo.randomizeTorsions function can be used to randomize all torsion angles active in a particular IVM object.

By convention, Xplor‐NIH energy terms exist in Python modules with the suffix PotTools. So, for instance, the terms for distance restraints and residual dipolar couplings (RDCs) are in the modules noePotTools and rdcPotTools, respectively. In these modules, the functions that create the energy terms take the prefix create_, so that the creation functions corresponding to the above terms are create_NOEPot and create_RDCPot, respectively. On the other hand, energy terms defined in the legacy XPLOR interface are instantiated via the XplorPot constructor function from the xplorPot module. XplorPot energies typically used in modern Xplor‐NIH scripts include BOND, ANGL and IMPR, the covalent energy terms for bonds, angles and improper dihedral angles, respectively, and CDIH, the energy term which restrains dihedral angles to experimentally determined values. There are helper functions in the protocol module to help initialize and configure commonly used XPLOR terms, where appropriate.

The internal variable module (IVM)6 is used to manipulate coordinates either by molecular dynamics or gradient minimization. This facility allows generalized internal coordinates ranging from the three degrees of freedom per atom in Cartesian coordinates to torsion angle space, to allowing rigid‐body motions of arbitrarily large subunits. IVM objects can be created by the ivm.IVM constructor and the desired degrees of freedom then specified. The final step in the topology setup of an IVM object should be a call to either of the helper functions protocol.torsionTopology or protocol.cartesianTopology. These functions configure those degrees of freedom not already specified, for either torsion or Cartesian degrees of freedom, respectively. torsionTopology groups in rigid bodies atoms in aromatic and other known planar regions. Its use is demonstrated in Figure 1. In addition, these functions take care of proper configuration of pseudo atoms, used to encode non‐atomic coordinates such as those atoms which describe the RDC alignment tensor, and those which encode ensemble populations (see below). IVM objects are configured for dynamics or minimization by use of the protocol.initDynamics or protocol.initMinimize functions, respectively.

Figure 1.

Topology setup for torsion angle dynamics with a grouped region composed of residues numbered from 100 to 120, inclusive.

As described above, functions used to configure standard settings for dynamics, minimization and XPLOR energy terms can be found in the protocol module. For example, to load a protein structure file (PSF) (which contains atom information and covalent geometry definitions for a particular structure, used for proteins and all other types of molecules), the initStruct function can be used as seen in Figure 2. Figure 2 also shows that PSF information can also be directly generated from a residue sequence using functions in the psfGen module. Alternatively, for proteins and nucleic acids containing standard residues, protocol.loadPDB can be used to generate PSF information directly from a PDB or mmCIF file, and the coordinates then loaded. [loadPDB can also optionally generate subunits related by crystallographic symmetry from a PDB BIOMT record.]

Figure 2.

Loading PSF information from a file, or generating it from sequence. protein.psf would contain a pre‐calculated PSF file, while protein.seq would contain a list of whitespace‐separated 3‐character residue names. PSF information is required for any Xplor‐NIH functionality which references atomic coordinates.

An outline of a complete structure calculation script can be found in Figure 3, which introduces AnnealIVM, used to perform simulated annealing, and StructureLoop, which repeatedly calls a function to compute the requested number of structures (optionally in parallel) and then writes out the coordinates.

Figure 3.

Schematic of a structure calculation script.

The Python interpreter is invoked via the xplor ‐py or pyXplor commands. In Xplor‐NIH's Python interface, functions and class definitions are placed in module namespaces; a reference manual for all Xplor‐NIH modules is available.7 The Python built‐in function help can be used to get immediate help about Python objects. The following conventions are used in Xplor‐NIH's Python interface: module and function names start with lower‐case letters and class names start with upper‐case letters.

While the primary interface for Xplor‐NIH is via Python, the legacy XPLOR interface continues to be maintained, and can be utilized for additional functionality not yet supported by the Python interface, such as refinement against X‐ray crystallographic or fiber data. Xplor‐NIH's Tcl interface is used solely for the PASD8 automatic NOE assignment facility. Xplor‐NIH ships with multiple additional facilities including the numpy9 and matplotlib10 packages.

Options for parallel structure calculation

To ascertain the range of conformations consistent with the experimental restraints and other energy terms, multiple structures are usually computed which differ in the random number seed used for generation of initial random coordinates and velocities. Additionally, it is common that some structures will fail to converge to an acceptable solution, so running multiple calculations increases the chance of success. For a production refinement calculation, it is common to compute 100 or more structures.

On a workstation with multiple cores, one may specify the ‐smp $N_{\text{proc}}$ command line option to run $N_{\text{proc}}$ structure calculations in parallel. Similarly, on Scyld ClusterWare systems, one specifies ‐scyld $N_{\text{proc}}$. Xplor‐NIH also supports clusters running the PBS11 or SLURM12 queuing software using the pbsxplor and slurmXplor commands, respectively. These commands will create a job submission script appropriate for the queuing system, and help assure that Xplor‐NIH is run efficiently on each node of the cluster. For example, with pbsxplor, the number of cluster nodes N is specified with the ‐l nodes= N option, and $N_{\text{proc}}$ is then automatically computed.

Energy Terms

Xplor‐NIH energy terms can be divided into four general classes:

• Terms that reflect how well experimental observables are predicted from the molecular structure. Examples of NMR terms include those that enforce NOE and RDC restraints. Examples of non‐NMR data terms are those from small angle solution scattering (SASS),13 cryo‐electron microscopy (cryo‐EM),14 and X‐ray crystallography.15, 16, 17

• Those terms which enforce covalent geometry and prevent bad atom–atom contacts. Example terms include bond, angle, improper dihedral, and non‐bonded terms.

• Statistical or knowledge‐based energy terms derived from the Protein Data Bank which bias structures towards existing features seen in the database. An example is the torsionDB multi‐dimensional torsion angle database energy term.18, 19 When these terms are designed, special care is taken so that they are readily overridden by experimental restraints in cases of conflict.

• Other energy terms used to aid with structure determination—generally to aid with convergence or to enforce other physical information gleaned about the structure. For example, such terms include XPLOR's NCS and HARM terms, which enforces symmetry, and restrains atomic positions, respectively.

Ideally, only the first class of energy terms would be necessary in structure determination, but the problem is underdetermined, such that experimental restraints alone usually do not contain sufficient structural information.

Standard energy terms

Energy terms for various NMR experiments are listed here. The following energy terms are implemented in the modern Python/C++ interface:

• The previously mentioned NOEPot term is usually used for distance restraints. This term supports the XPLOR ASSIgn $\dots$ OR format to provide pairs of ambiguous assignments, and different averaging options such as sum averaging.20 This term supports the standard piece‐wise quadratic,4 log‐normal,21 and soft forms of the energy function.

• The RDCPot term can be used for RDC restraints, as well as dipolar coupling restraints from solid state NMR. It allows one to choose the flexibility of the alignment tensor, from being fully fixed to allowing all five degrees of freedom. One can treat through‐space RDCs by enabling the distance dependence of this term by setting the useDistance accessor. This form of the energy term thus also supports pseudo‐contact shift restraints.

• Chemical shift anisotropy can be measured in solid state NMR and using weakly aligning media in solution.22 These data can be used as restraints on bond vector orientation using the CSAPot term.

• Restraints on torsion angles from three‐bond J coupling experiments are supported by the JCoupPot term.4

• DiffPot 23 is an energy term restraining the shape of a protein using components of the rotation diffusion tensor extracted from NMR relaxation data.

• Direct use of $T_1/T_2$ ratios from relaxation data is afforded by the RelaxRatioPot term to provide information on overall molecular shape and local bond vector orientations in docking24 and all‐atom structure determination.25

• Refinement against cross‐correlation relaxation (CCR) can be performed using CCRPot.26 This term is only meaningful in the context of an EnsembleSimulation.

• Solvent NOE and PRE data can be qualitatively incorporated into structure calculations using the NBTargetPot term.27

• The OrderPot term can be used to refine against bond angle S ² parameters. This term is only meaningful in the context of an EnsembleSimulation.

• Paramagnetic relaxation enhancement (PRE) can be used to derive long‐range (10–30 Å) distance information via the Solomon–Bloembergen equation. While PREs are sometimes converted to distance restraints, Xplor‐NIH supports structure calculation directly from PRE values with the PREPot term,28 and includes an extension which better describes motional effects due to flexibly‐linked paramagnetic groups. Because of the $1/r^6$ distance dependence of PREs, these are powerful in characterizing minor populations of a species in the case where there are distances in the minor species which are smaller than the corresponding distances in the major species.29

• Experimentally measured ${}^{\mathrm{h}3}{J}_{\text{NC}\prime }$ scalar coupling values30, 31 can be fit to single structures using the h3JNCPot energy term to provide an empirical measure of the quality of hydrogen bond geometries.

Certain possibly useful NMR energy terms in the old XPLOR interface are listed next:

• Torsion angle restraints32 derived from three‐bond J couplings in combination with NOE/ROE data are available in the CDIH XPLOR energy term accessed via the RESTraints DIHEdral XPLOR statement.

• The ${}^1{J}_{{\mathrm{C}}_{\alpha }-{\mathrm{H}}_{\alpha }}$ couplings are related to ϕ and ψ angles by an empirical relationship.33 ${}^1{J}_{{\mathrm{C}}_{\alpha }-{\mathrm{H}}_{\alpha }}$ coupling restraints are available via the ONEBond XPLOR term (J.J. Kuszewski and G.M.C., unpublished).

• ${}^{13}{\mathrm{C}}_{\alpha }$/ ${}^{13}{\mathrm{C}}_{\beta }$ secondary shifts,34 which are empirically related to ϕ/ψ values,35 are available in the CARBon XPLOR term.

• ¹H chemical shifts restraints,36, 37 which include the capability of dealing with nonstereospecifically assigned methylene and methyl groups are available in the PROTon XPLOR term.

• Direct refinement against NOE intensities using complete relaxation matrix calculations38, 39 are available via the RELAxation XPLOR term. This approach is computationally intensive, and for this reason is used infrequently and then only in the very last stages of a refinement protocol.

• Heteronuclear $T_1/T_2$ ratios for molecules that tumble anisotropically40, 41 also provide orientational information. Associated restraints can be applied using the DANI XPLOR term.

• Alternative RDC energy terms are available. The Implicit Saupe tensor Alignment Constraint (ISAC)42 code available via the XPLOR TENS energy term allows for a floating orientational tensor without explicit tensor atoms. The VEAN term43 imposes intramolecular angle restraints derived from RDCs in a smooth energy term which can be useful for early stages of refinement. The VEAN term is also useful to apply restraints from tensor‐based solid state NMR experiments in structure calculations.44

In addition to torsionDB (discussed further below) other knowledge‐based terms derived from the Protein Data Bank (PDB) are also available. Backbone amide hydrogen bonding is encoded via two terms. The HBDA XPLOR term45 employs an empirical relationship between hydrogen‐oxygen distance and the NHO angle. An alternative representation of backbone hydrogen bonding is encoded in the HBDB XPLOR term,46 which is a direct potential of mean force.

The ORIE XPLOR energy term comprises another database term containing information about the relative positioning of groups close in space. The term currently encodes base‐base information for DNA47 and RNA,48 as well as protein sidechain‐sidechain interactions (J.J. Kuszewski and G.M.C., unpublished). For nucleic acids, use of this term leads to a significant increase in accuracy as judged by cross‐validation against dipolar couplings and circumvents limitations associated with conventional NMR representations of non‐bonded contacts. The term's usefulness was underscored by comparison of high‐angle X‐ray scattering data with the calculated structures of a double‐stranded DNA dodecamer.49

The gyration volume50 and radius of gyration51 energy terms are useful to obtain structures with approximately correct atomic density. These restraints can be applied to well‐packed ellipsoidal regions of protein structures using the create_GyrPot and create_RgyrPot functions from the gyrPotTools modules. residueAffPot 23 implements a per‐residue packing potential energy which encodes the arrangement of hydrophobic, polar and charged residues.

New energy terms can be written purely in Python. Thus, new terms can be prototyped rapidly. If execution speed requires, such a term can later be recoded in C++, with no change to the structure calculation scripts.

New RDC terms

Aside from the standard Xplor‐NIH RDC energy term,4 we have implemented two additional terms which are particularly useful for ensemble calculations. For interconversion fast on the RDC timescale, each ensemble member has its own effective alignment tensor, and if one were to use the common practice of letting the alignment tensors float to optimize fit to experiment, there would be far too many parameters for the given data.

SARDC

The SARDC energy term52 computes the alignment tensor from molecular shape, which is appropriate for experiments performed using purely steric alignment media. After initial publication, the SARDC term was updated and corrected.53 Corrections included proper calculation of the gradient with respect to the alignment tensor. Updates included adding support for pairwise averaging such that a single restraint table can simultaneously be used for symmetric homodimers and the monomeric species.

The target function for the SARDC term is proportional to the ${\chi }^2$ metric:

$${\chi }^2=1/{\mathrm{N}}_{\mathrm{RDC}}{\displaystyle \sum _{\mathrm{i}}{({\delta }_{\mathrm{i}}-{\delta }_{\mathrm{i}}^{\text{expt}})}^2}/\Delta {\delta }_{\mathrm{i}}^2,$$ (1)

where δ _i is the calculated RDC value for residue i, ${\delta }_{\mathrm{i}}^{\text{expt}}$ is the observed experimental value, $\Delta {\delta }_{\mathrm{i}}$ is an error, and the sum extends over all N_RDC observed RDCs. Errors arise from experiment and due to coordinate error.

While the alignment tensor is computed from the structure, there remains an overall scale factor which is chosen to optimize the fit to experiment. RDCs from multiple experiments can be combined to use a shared tensor. They can be read as a single set, or placed in separate terms for convenience, but in the later case they must be linked so that they share the overall RDC scale factor.

RDCCorrPot

An alternative approach for treating RDCs in an ensemble calculation is to compute RDCs from structure using a tensor‐less approach.54 Here, the proper overall RDC scale factor is again unknown, so the default target function is $C_{\text{RDC}}$, the correlation of observed to calculated RDCs:

$$C_{\text{RDC}}=\frac{\sum _{\mathrm{i}}({\delta }_{\mathrm{i}}-\overline{\delta })({\delta }_{\mathrm{i}}^{\text{expt}}-{\overline{\delta }}^{\text{expt}})}{\sqrt{\sum _{\mathrm{i}}{({\delta }_{\mathrm{i}}-\overline{\delta })}^2\sum _{\mathrm{i}}{({\delta }_{\mathrm{i}}^{\text{expt}}-{\overline{\delta }}^{\text{expt}})}^2}},$$ (2)

where $\overline{\delta }$ and ${\overline{\delta }}^{\text{expt}}$ are the average of the calculated and observed RDC values, respectively. For this term, the usual form for the energy is

$$E=k_{\text{RDC}}(1-C_{\text{RDC}}),$$ (3)

where k _RDC is a force constant. The rdcCorrPotTools.calibrate function can be used to compute the appropriate scale factor so that RDC values can be compared, and (optionally) a “harmonic” potential energy type then used to restrain individual restraints.

Non‐NMR energy terms

In addition to the full set of facilities for refining against X‐ray crystallographic2 and X‐ray fiber diffraction data55 implemented in the XPLOR interface, we implemented two sets of facilities for which increasing amounts of data are now available.

SASS data

Small angle X‐ray scattering (SAXS) and small‐angle neutron scattering (SANS) can be used to study samples under conditions very similar to those of NMR. As these data are sensitive to overall size and shape information, they are complementary to NMR data. A detailed review of Xplor‐NIH's SASS facilities has been reported13 and the reader is directed there for a description and for Python snippets to use for incorporating SASS data into an existing script. The SASS terms are implemented in solnScatPot.SolnScatPot terms created by create_ functions in the modules solnXRayPotTools and sansPotTools.

Cryo‐EM maps

Xplor‐NIH has a native OpenMP‐parallelized facility to handle cryo‐EM density maps.14 Recent advances in cryo‐EM technology has enabled the technique to achieve nearly atomic resolution. An example snippet for using cryo‐EM data in structure determination can be found in Figure 4.

Figure 4.

Setup of the energy term for refining against an atomic probability density map (e.g., generated from cryo‐electron microscopy).

Force Fields

The force field describes molecular motion in the absence of experimental restraints. Xplor‐NIH can support and is shipped with multiple force fields, the choice of which can be tailored for one's particular need.

The default force field

The default force field includes bonds and angles designed to agree with the Engh and Huber parameter set56 for proteins and those of Parkinson et al.57 for nucleic acids, with improper dihedral angles used to uniquely define tetrahedral centers and to restrain rigid regions, such as aromatic rings. Dihedral angles are restrained using TorsionDBPot,18, 19 a multi‐dimensional knowledge‐based potential of mean force derived from high‐quality structures from the PDB. TorsionDB is an improvement over the earlier RAMA term,58, 59 and completely supersedes it. TorsionDB applies to proteins, RNA and DNA.

The default nonbonded term RepelPot is a simple excluded volume term which is a re‐implementation of the XPLOR VDW REPEl term.60 RepelPot implements only the purely quartic repulsive term, but allows more convenient specification of which atoms are included or excluded, and has been efficiently OpenMP‐parallelized. With older force fields, the atomic radii were modified by a scale factor during simulated annealing. With the adoption of Molprobity radii,19 a single constant scale factor of 0.9 is now applied during simulated annealing. An example of typical RepelPot setup is shown in Figure 5.

Figure 5.

Setup of the RepelPot energy term for atom‐atom repulsion with the correct radius scale factor set automatically. This setup specifies that only interactions between residues 2–40 and 50–90 are computed. This setting can speed up non‐bonded calculations when regions are grouped as rigid bodies.

By default, the RepelPot setup excludes non‐bonded interactions between atoms separated by three or fewer bonds (i.e., 1–4 interactions) because most such interactions are implied by the torsionDB term. However, since the torsionDB term is derived from X‐ray structures, it only involves torsion angles defined by heavy atoms. Thus, torsion angles involved in methyl and O‐H group rotations are not restrained, which may lead to eclipsed conformations unless 1–4 non‐bonded interactions are introduced for these groups (e.g., between the H ${}^{\gamma }$ and C ${}^{\beta }$ in serine residues). A separate RepelPot instance must be configured for this purpose, as shown in Figure 6.

Figure 6.

Instantiating the dihedral portion of the default force field using TorsionDBPot and Terminal14Pot for dihedral angles which contain one or more protons (see text).

EEFx

It has been noted that refinement of NMR structures in fully realistic force fields including electrostatics and the effects of solvent can improve NMR structures.61 Thus, an implementation of the EEF162 implicit solvent force field has been introduced into Xplor‐NIH as the EEFx term.63 While there is a modest slow down in computation time, this force field has been shown to be usable in all stages of structure determination, and can provide improvements over the results from the default RepelPot‐based force field.

The EEFx term also contains an implicit representation of lipid bilayer membranes,64 in which the dielectric constant modulates from that of bulk water at the membrane surface, to that appropriate for the lipid interior. This term has been shown to help determine the overall orientation of a membrane protein, and can help exclude hydrophilic regions from the membrane.

Figure 7 shows how the EEFx energy term is added to an Xplor‐NIH Python script. This term includes van der Waals, electrostatic and solvent contributions. It can be used in concert with either TorsionDBPot or the standard XPLOR DIHE dihedral term using CHARMM22 parameters.65

Figure 7.

An example of how to include the EEFx energy term. The initEEFx function loads the appropriate electrostatic, non‐bonded and solvation parameters, while the eefxpot object is instantiated later in a script with other energy terms.

Alternate force fields

In addition to the EEFx term, Xplor‐NIH ships with support for the explicit water refinement protocol introduced in Ref. 66. Force field parameters may be easily modified by end‐users so as to ensure very small deviations from idealized covalent geometry, while satisfying experimental restraints and achieving good non‐bonded contacts (i.e., no atomic overlaps). Full empirical energy functions (CHARMM19/20/22, OPLS67) are also available. Finally, it is straightforward to adapt parameter and topology files for any empirical energy function (e.g., AMBER,68 etc.) which employs the same analytic form for the electrostatics, hydrogen bonding and van der Waals Lennard–Jones energy terms as CHARMM19/20. Note that obtaining parameters and topology information for other systems, including polysaccharides and small molecules, is relatively simple. Non‐proton information can be generated from arbitrary molecular coordinates using the Dundee PRODRG2 Server,69 XPLO2D,70 program, or ACPYPE.71 Frequently, some amount of manual editing of the generated topology and parameter data is required. If coordinates are known, the LEARn facility in the XPLOR interface can be used to generate the parameters.

Strict Symmetry

While approximate symmetry can be maintained using the terms PosDiffPot (which restrains atomic coordinates in different subunits to have the same relative configurations) and DistSymmPot (which implements distance symmetry20), Xplor‐NIH also has a strict symmetry facility implemented in the symSimulation module, in which only a single copy of protomer¹ coordinates are maintained, and the other subunits are generated by rigid body rotations and translations.72 The advantages of this strict symmetry representation are that the number of coordinates are reduced by a factor of the size of the oligomer, and that only a subset of interactions need be computed, leading to faster sampling and reduced computational cost. See Figure 8 for an example of a symSimulation setup appropriate for a symmetric homodimer. All of the native Python energy terms can be applied to the full oligomer, or to the protomer alone, as is appropriate, while the old XPLOR terms have the limitation of only applying to the protomer. For example, torsion angle restraints only need be applied to the protomer, while intersubunit restraints would need be applied to the full SymSimulation. When setting up energy terms or IVM objects, the current Simulation is used unless otherwise specified. Hence, in strict symmetry calculations it is convenient to switch the current Simulation between the initial XplorSimulation containing protomer coordinates, and the SymSimulation which contains coordinates of the full construct using the function simulation.setCurrentSimulation. Strict symmetry has not yet been implemented in the EnsembleSimulation facility.

Figure 8.

Example of generating a second subunit related by a ${180}^{°}$ rotation about the z axis relative to the protomer. The segment name of the second subunit is set to “B” while that of the first subunit is set to “A”.

Unlike the normal circumstance where the center of mass location is irrelevant, in strict symmetry calculations, the protomer center of mass location can encode subunit translational distances such as that involved in intersubunit packing. Normally, the center of mass velocities are zeroed at each time step for trajectory stability, but in strict symmetry calculations, one should allow some of this motion through a call to the setResetCMInterval method of IVM objects after a call to protocol.initDynamics so that different packing distances can be sampled during molecular dynamics.

A novel aspect of this strict symmetry implementation is the ability to optimize symmetry operations on the fly, for cases in which the rigid body rotations or translations are not known. For instance, for a molecule with helical symmetry, the amount and/or direction of helical twist can be allowed to float during structure calculations. Floating rotation and translation parameters are encoded in pseudo atoms, and allowed only appropriate degrees of freedom using the IVM.

With the symSimulation strict symmetry facility, there are two representations of the full oligomer: the protomer coordinates (possibly accompanied by pseudo atoms), and the complete set of atomic coordinates. While the StructureLoop facility will output protomer coordinates, for viewing and fitting the full oligomer, it is useful to have a PDB file containing all the coordinates. Such a file can be generated at the end of the calcOneStructure function using protocol.writePDB as shown in Figure 9.

Figure 9.

At the end of the calcOneStructure function introduced in Figure 3, add this call to write out the coordinates of all subunits with the suffix .full. symSim is the SymSimulation object created in Figure 8.

Ensemble Refinement

When a molecular system undergoes significant motion on timescales short relative to that of an experiment, the resulting observables will contain contributions from the various substates. A facility to fit an ensemble of structures to data was introduced73 and expanded significantly since the publication of Ref. 4. We now recommend sum averaging of energy terms over an ensemble to avoid implicit scaling of time so that the setup of an EnsembleSimulation object should now follow that in Figure 10. Most native Python terms which correspond to experimental observables have EnsembleSimulation support.

Figure 10.

Code to create a three‐membered ensemble. Creation of the EnsembleSimulation makes copies of the current atom positions, velocities, and so forth. The constituent structures do not interact except by special ensemble‐aware energy terms. The sum averaging setting specifies that energies (including kinetic energy) increase in proportion to the ensemble size.

A major enhancement to the ensemble refinement facility has been the ability to determine ensemble member populations in concert with structure determination.53 Ensemble populations can be allowed to vary to improve fit, and to reduce the ensemble size required for a good fit. Ensemble populations are encoded in N‐sphere coordinates, x _i:

$$x_1=r\cos ({\varphi }_1)\hspace{0.17em}$$ (4)

$$x_2=r\sin ({\varphi }_1)\cos ({\varphi }_2)\hspace{0.17em}$$ (5)

$$x_3=r\sin ({\varphi }_1)\sin ({\varphi }_2)\cos ({\varphi }_3)\hspace{0.17em}$$ (6)

⋮

$$x_{N_{\mathrm{e}}-1}=r\sin ({\varphi }_1)\cdots \sin ({\varphi }_{N_{\mathrm{e}}-2})\cos ({\varphi }_{N_{\mathrm{e}}-1})\hspace{0.17em}$$ (7)

$$x_{N_{\mathrm{e}}}=r\sin ({\varphi }_1)\cdots \sin ({\varphi }_{N_{\mathrm{e}}-2})\sin ({\varphi }_{N_{\mathrm{e}}-1})\hspace{0.17em},$$ (8)

with the radial component r taken to be 1, and the $N_{\mathrm{e}}-1$ angular coordinates ${\varphi }_{\mathrm{i}}$ encoded as bond‐angles of pseudo atoms. Ensemble populations w_i are then given as

$$w_{\mathrm{i}}=C{x}_{\mathrm{i}}^2+w_{\text{min}}$$ (9)

and they obey the normalization condition ${\displaystyle \sum w_{\mathrm{i}}}=1$. Because it is not useful to compute ensemble members with population zero, we further constrain the populations to lie in a reduced range by specifying $w_{\text{min}}$ to the minimum population we believe we can represent with a given set of data, so that $C=1-N_{\mathrm{e}}{w}_{\text{min}}.$

With this representation of ensemble populations, computation of the gradient with respect to pseudo atom coordinates is straightforward. Facilities within Xplor‐NIH are now provided to make it convenient to optimize ensemble populations for any ensemble energy term by providing the derivative with respect to ensemble population. As of this writing, ensemble population derivative support has been added to the SolnScatPot, SARDCPot, RDCCorrPot, CCRPot, and GyrPot terms. Support for additional terms can be added as needed.

In addition to setting a minimum ensemble population, instabilities due to wild gyrations in ensemble population values early in structure calculations are avoided by introducing a stabilizing energy term:

$$E_{\text{pop}}=k_{\text{pop}}{\displaystyle \sum _{i=1}^{N_{\mathrm{e}}}}{(w_{\mathrm{i}}-w_{\mathrm{i}}^{\mathrm{o}})}^2$$ (10)

where $k_{\text{pop}}$ is a force constant which is generally large at the start of a structure calculation, and small at the end. The target population values $w_{\mathrm{i}}^{\mathrm{o}}$ might initially take values of $1/N_{\mathrm{e}}$, but can be tuned from prior knowledge, or during the course of a structure calculation.

Finally, symmetry may dictate that there be relationships between ensemble populations. Consider a symmetric dimer in which each subunit takes two conformations X and Y, neither of which influences the dimerization interface. In this case, there will be three distinct states denoted XX, YY, and XY, the last of which would be indistinguishable from YX. In this case, if the populations of the two subunit conformations are w_X and w_Y, the populations of the full dimer would be $w_{\mathrm{X}}{w}_{\mathrm{X}},\hspace{0.17em}{w}_{\mathrm{Y}}{w}_{\mathrm{Y}}$ and $w_{\mathrm{X}}{w}_{\mathrm{Y}}$, respectively. Xplor‐NIH now has a facility to derive the three dimer populations from the two subunit populations with a rather general mechanism for specifying constraints between populations. In vector notation one can write

$$w_{\mathrm{i}}=A_{\mathrm{i}}+{\mathbf{B}}_{\mathrm{i}}{\mathbf{w}}_{\mathrm{b}}+{\mathbf{w}}_{\mathrm{b}}^{\mathrm{T}}{\mathbf{C}}_{\mathrm{i}}{\mathbf{w}}_{\mathrm{b}},$$ (11)

where ${\mathbf{w}}_{\mathrm{b}}$ are base populations defined in Eq. (9) and A _i, ${\mathbf{B}}_{\mathrm{i}}$ and ${\mathbf{C}}_{\mathrm{i}}$ contain coefficients which define w _i populations of the system of interest in terms of the base populations. For the dimer example discussed above, A _i = 0, ${\mathbf{B}}_{\mathrm{i}}=0$ for all i and the nonzero elements of the ${\mathbf{C}}_{\mathrm{i}}$ are:

$${\mathbf{C}}_0(0,0)=1,{\mathbf{C}}_1(1,1)=1,{\mathbf{C}}_2(0,1)=2,$$ (12)

where the 0, 1, 2 states correspond to the dimer XX, YY, and XY states, respectively. Figure 11 shows the creation of a pop object which contains a description of the three state symmetric dimer system described above.

Figure 11.

The pop object contains a description of the populations of a three‐state symmetric dimer with two substates in each subunit. The minimal population is set to be $0.1/N_e$. The pop object is also an energy term, implementing the regularizing energy defined in Eq. (10).

Modern Data Formats

The NMR exchange format (NEF)74 is a standard simple file format intended to be used to store NMR data and derived restraints. As of this writing, it supports storing chemical shift data, peak lists from multidimensional NOE experiments, RDCs and distance and torsion angle restraints. Xplor‐NIH can read and write NEF files as shown in Figure 12.

Figure 12.

Examples of reading and writing NEF formatted files. The readNef function will generate PSF information, and additional energy terms can be initialized using content in the cifData object. Here, coordinates are read in mmCIF format. For writing a NEF file the genHeader function will generate connectivity information and the noePotTools.writeNEF will then add restraint data from noe, an NOEPot object defined previously in the script (not shown).

The mmCIF file format is a successor to the venerable PDB format which addresses limitations of the later including a rather limited number of possible chains and fixed precision atomic coordinates. The mmCIF format also allows one to define custom fields to represent per‐atom data. Xplor‐NIH supports reading and writing these files.

Other Xplor‐NIH Facilities

Probabilistic NOE assignment algorithm for automated structure determination (PASD)

Xplor‐NIH includes the PASD facility for automatic NOE assignment from completely automatically peak‐picked multi‐dimensional NMR spectra, with simultaneous structure determination.8 The key features of this facility are:

• An initial analysis of possible assignments before structure determination, giving high‐likelihood to assignments which are consistent with other assignments.

• For a given NOE peak, multiple possible assignments are simultaneously enabled.

• A linear NOE potential is used in early stages of the calculation so that all assignments contribute equal magnitude forces.

• Successive passes of assignment calculation are not based on previously determined structures, thus greatly reducing the chances of converging on incorrect structure/assignment combinations.

More details can be found in Refs. 8 and 75.

The PASD algorithm has been found to be highly robust in the face of bad NOE data (including missing or bad chemical shift assignments), with the ability to tolerate about 80% bad long‐range data (i.e., data between residues separated by more than five residues in primary sequence). Failure of the method is clearly indicated by lack of convergence of assignment likelihoods, and by a large spread (poor precision) in the calculated set of structures. The following input formats are currently supported: NEF, nmrdraw, nmrstar, pipp, and xeasy. It is a simple task to write filters to support additional formats.

The user interface to PASD is a set of Tcl scripts, examples of which can be found in the eginput/pasd/* subdirectories of the Xplor‐NIH distribution. These scripts are written at a very high level such that they are each to understand and modify.

Chirality determination in small molecules

Xplor‐NIH contains support for the progressive stereo locking (PSL) algorithm76 for determination of the chirality of natural products and other small molecules using primarily RDC data measured in aligning media coupled with NOE‐derived distance restraints. In this protocol, chirality at the centers in question are allowed to float during structure calculation by removing the associated improper dihedral term and greatly relaxing the force constants on the associated bond angle terms. It was found that the PSL approach results in a unique configuration (for rigid molecules) or a very small number of configurations (for less rigid molecules), and has been applied to systems with up to 14 chiral centers. Facilities developed for this algorithm include the protocol itself (available in the eginput/psl subdirectory of the Xplor‐NIH distribution) coupled with facilities for determination of absolute chirality in the chirality module.

Analysis and validation

Information on how well a given structure satisfies experimental restraints is given in the standard coordinate files produced by the StructureLoop class introduced in Figure 3. The resulting coordinate files contain a summary of the number of restraints which are violated by more than a given standard (but adjustable) threshold value, and the root‐mean‐square deviation of the difference between calculated and experimental observables. A detailed listing of the specific violations for each term is given in a separate file whose name has a .viols suffix. More global structural analysis is triggered by setting the genViolationStats argument to True, and is based on the top fraction of structures specified by averageTopFraction, after all structures have been sorted from low to high energy using the terms in averageSortPots. The results of the analysis are stored in a file with the .stats suffix, which reports on all the energy terms specified in averagePotList. The .stats file contains averages of fit RMSD and number of violations for each energy term. For some energy terms, averages of associated properties are reported in the .stats file. For instance, average alignment tensor properties and R‐factor fit metric are reported for the RDCPot term. For most terms for which the concept of violation is meaningful, a list of restraints violated most often is listed in the .stats file, along with the fraction of the analyzed set of structures for which the violation was present. A persistently violated restraint frequently indicates some sort of problem with the input data. The averagePotList argument is also used to compute a regularized average structure to which the analyzed structures are fit (using the selection string given in the argument averageFitSel) to report the coordinate precision. Although not exercised in Figure 3, the average structure can be written out by specifying the extra argument averageFilename to StructureLoop. Final validation of a structure can be accomplished using the wwPDB Validation Service.77 This performs the same validation procedure as used during submission of a structure to the PDB.

Helper programs

A number of helper programs are distributed with Xplor‐NIH so that common tasks can be performed from the Unix command line without writing or editing a separate script. These programs include

• targetRMSD—rigid‐body fit of one or more structures to a target structure and compute the positional RMSD.

• calcTensor—given RDC data and one or more structures, compute the alignment tensor via singular value decomposition, and report the fit of back‐calculated RDCs to the data. The back‐calculated RDCs can be output as text, or as a plot.

• calcSARDC—given RDC data measured in steric alignment media and one or more structures, back‐calculate RDCs and report the fit to the data, optionally in graphical form.

• calcDaRh—Calculate an estimate of the alignment tensor D _a and rhombicity from input RDC values (without structures) using the assumption of isotropically distributed bond vectors and a maximum likelihood approach.78

• calcSAXS—Given a molecular structure, compute a SAXS or SANS curve, optionally fitting to experiment.

• torsionReport—Generate report on all protein torsion angle values for one or more PDB files.

• aveStruct—given a set of input files, compute an unregularized average structure.

• ens2pdb—Converts a set of structure files to a single PDB file, with structures separated by MODEL records resulting in a file for PDB submission.

• contactMap—Generate contact map from one or more PDB files.

• ramaStrip—Given one or more input PDB files, generate a sequence of two‐dimensional Ramachandran plots, one for each residue. In each plot is plotted the ϕ/ψ position associated with each input PDB, overlaid on contours indicating residue‐specific allowed regions as determined by the methodology described in Ref. 18.

• scriptMaker—a graphical interface for generating Xplor‐NIH scripts.

A full list and documentation can be found here: https://nmr.cit.nih.gov/xplor-nih/doc/current/helperPrograms/.

Test suite

Xplor‐NIH is distributed with a full suite of regression tests both in the source and binary‐only packages. These tests are essential to obtain confidence that the package operates properly. For end‐users, possible problems can be caused by moving to a system with slightly different hardware or operating system configuration different from those used for compilation. For developers, a seemingly unrelated change might break some other functionality within Xplor‐NIH. These tests provide some assurance that the package does indeed behave as expected, and allows quick identification as to where an error is located. In the source package, components are tested hierarchically: the C++ template library contains a test suite, as does the IVM and each energy term. In both the source and binary distributions, the XPLOR, Python and Tcl interfaces contain a large collection of test scripts along with the expected output. The bin/testDist command invokes an automated procedure which runs each script and reports discrepancies. These tests are essential to validate a new installation of Xplor‐NIH.

Extensive sets of full scripts with all supporting data are present in the eginput subdirectory of a Xplor‐NIH distribution. Basic validation of the suite of example scripts in the eginput subdirectory is performed using the runAll script in that directory, while a more thorough validate script will run a complete calculation for one or more examples, and check that the computed results are within a tolerance of published values.

Conclusion

This article provides an overview of using the Xplor‐NIH Python interface for structure determination. The example code here is by necessity fragmentary and incomplete. Many facilities have not been touched upon at all. Much more complete documentation is available from the Xplor‐NIH website at https://nmr.cit.nih.gov/xplor-nih/doc/current/. Specific questions should be addressed to the Xplor‐NIH mailing list at xplor‐nih@nmr.cit.nih.gov. Proper journal citation for this program should include the original Ref. 1 and this article.