NOESHOW(1)

NAME

noeshow - show AMBER INTERFACE format NMR-derived constraints mardishow - show MARDIGRAS format NMR-derived constraints

SUPPORT PROGRAMS

sander2amber - convert AMBER SANDER namelist-style distance
constraints to AMBER INTERFACE format

xplor2amber - convert X-PLOR distance constraints to AMBER
INTERFACE format

xplor2tors - convert X-PLOR torsion angle information to
AMBER style

diana2amber - convert DIANA distance constraints to AMBER
INTERFACE format

MIDAS COMMAND SYNTAX

Command: noeshow [ options ] constraint_file [ torsion_file ] or Command: mardishow [ options ] constraint_file

SHELL COMMAND SYNTAX

sander2amber pdb_file sander_input_constraints > reformatted_constraints diana2amber [ -v viol_add ] pdb_file diana_low_bounds diana_high_bounds > reformatted_constraints xplor2amber [ -c chain_ID ] [ -v viol_add ] pdb_file xplor_constraints > reformatted_constraints xplor2tors [ options ] xplor_torsion_output > reformatted_torsion_file

DESCRIPTION

Noeshow and mardishow are programs for displaying NMR- derived constraints on model structures in MIDAS. Noeshow can display distance constraints in AMBER INTERFACE format and, via format conversion programs, constraints in X-PLOR, DIANA, MARDIGRAS (output), or AMBER SANDER (namelist) formats. Mardishow can display constraints in MARDIGRAS input or output formats. Noeshow's functionality is generally a superset of that provided with mardishow, and mardishow is provided principally for its ability to display MARDIGRAS input format constraints. If a conversion program for MARDIGRAS input format is developed, mardishow may be withdrawn.

Noeshow can also show torsion angle constraints if given the restraint analysis output from the SANDER AMBER module. The conversion program xplor2tors can be used to convert X-PLOR torsion angle information to a form usable by noeshow.

Finally, noeshow can be used to indicate all hydrogens within a given cutoff distance of one or more designated hydrogens. This capability can be used with or without an accompanying set of distance constraints.

USAGE

Distance constraint preparation
If your distance constraints are in AMBER INTERFACE format, they need no further preparation to be used by noeshow. If you have constraints in MARDIGRAS input format, they are ready for use in mardishow (see the ``Mardishow'' section, below). Constraints in other formats will need to be converted. If you are not certain what format your constraints are in, examples of each are provided in the ``Constraint formats'' section below.

Constraints in AMBER INTERFACE format have an ``energy well'' for each constraint. There are two upper-bound values and two lower-bound values. The lower of the two upper-bound values is where (if the distance exceeds the bound) an energy penalty begins to be applied (in the AMBER simulation) and the higher upper-bound value is where the penalty reaches a maximum. The lower bounds are similar, but apply to short distances. Some constraint formats (e.g. X-PLOR) describe only one upper and one lower bound. How this is mapped to the AMBER INTERFACE-type constraint style depends on the conversion procedure. The conversion procedure for the various formats are:

X-PLOR
Running the xplor2amber conversion script (as shown in the SHELL COMMAND SYNTAX section, above) will produce a file of equivalent constraints in AMBER INTERFACE format. The bounds given in the X-PLOR constraint file are taken as describing the ``floor'' of the energy well required for the AMBER INTERFACE format description, i.e. the distances where an energy penalty would begin to be applied. The distances where the energy penalty reaches a maximum is taken to be 0.5 angstroms beyond the given bounds on either side. The default value of 0.5 can be changed by giving the -v option flag to xplor2amber, followed by the desired distance. As described later, the bounds of the energy well determine whether the constraint will be shown as satisfied or violated (see the ``Basic usage'' section).

Xplor2amber will normally interpret segids in the X- PLOR constraint file as chain IDs in the converted file. The ``-c chain_ID'' option to xplor2amber will cause it to give all atoms the specified chain ID. Note that specifying chain_ID as " " (a quoted space) will give the atoms no chain ID, even if segids are present in the X-PLOR constraint file.

DIANA
DIANA format constraints are handled in almost the same manner as the just-described X-PLOR format constraints. The only differences are that the conversion script is diana2amber instead of xplor2amber, and that instead of specifying a single bounds file on the command line, separate lower- and upper-bounds files (in that order) are specified. Also, there is no -c option for diana2amber.

AMBER SANDER (namelist)
Running the sander2amber conversion script (as shown in the SHELL COMMAND SYNTAX section, above) will produce a file of equivalent constraints in AMBER INTERFACE format. Since AMBER SANDER constraints already describe an energy well, the mapping to an AMBER INTERFACE energy well description is straightforward.

MARDIGRAS (output)
Although mardishow is capable of displaying MARDIGRAS (output) format constraints without conversion, it may nonetheless be desirable in certain circumstances to convert the constraints for use with noeshow in order to make use of features only present in the latter program. Such a conversion is a two-step process. First, the constraints are run through the mardi2amber program to convert them to AMBER SANDER (namelist) format. The mardi2sander program is provided with the MARDIGRAS package, and is documented there. The second step is to convert the AMBER SANDER format constraints to AMBER INTERFACE format, as detailed in the paragraph above.

Torsion angle constraint preparation
You need not have torsion angle constraint information in order to use noeshow or mardishow; such information is optional. In fact, mardishow cannot display torsion angle constraint information, only noeshow can.

Noeshow uses the output torsion angle restraint information from the SANDER AMBER module, rather than the input torsion angle info. This is because it uses the energy penalty information provided by AMBER to color the torsion constraints. A sample of the kind of information it expects can be found in the ``Constraint formats'' section of this document.

Torsion angle information from X-PLOR can be converted for use with noeshow. Again, this is output information and, again, an example is provided in the ``Constraint formats'' section. The X-PLOR output information can be converted to the AMBER format with the xplor2tors program, the procedure for which is shown in the SHELL COMMAND SYNTAX section, above. X-PLOR torsion constraints are expressed as a desired angle and an allowable range about that angle. Xplor2tors has two options to control the transition from satisfied (green) to slightly violated (yellow) to badly violated (red). The ``-a degrees'' option controls how close to the edge of the range an angle can be before it is shown as slightly violated (default: 5 degrees). The ``-A degrees'' option controls how far beyond the edge of the range an angle can be before it is shown as badly violated (default: 10 degrees).

Basic usage
This section will discuss how to use noeshow to display NMR constraints in MIDAS. Mardishow is used in a very similar manner, and any differences will be discussed in the ``Mardishow'' section, below.

Noeshow is run from within MIDAS, so the first step is to display the model structure (or structures) in MIDAS. Once you've done that, invoke noeshow as shown in the MIDAS COMMAND SYNTAX section above. The parts of the command enclosed in brackets ([]) are optional and can be omitted.

Noeshow will read the file(s) you specify and generate and display a graphics object depicting the distance constraints and torsion angle constraints (if any). For the curious, graphics objects are discussed in the ``Non-Molecular Graphics Objects'' section of the MidasPlus manual, though it is not necessary to read that section to use noeshow effectively. The graphics object will be opened in the lowest unused model number.

Distance constraints will be depicted as lines connecting the atoms involved in the constraint. If one of the ``atoms'' is actually a pseudo-atom composed of several atoms, then the constraint will be drawn to the nearest of the atoms. The distance constraints will be colored according to how well they are satisfied:

Color      Meaning
red      distance exceeds both upper bounds
yellow      distance between the upper bounds
green      distance satisfies constraint
cyan      distance between lower bounds
blue      distance less than both lower bounds

Note that by default noeshow does not display the satisfied constraints (the -a flag causes them to be displayed).

Torsion angle constraints (if any) will be displayed as ``cages'' surrounding the central bond of the dihedral. The coloring of the cage is as follows:

Color      Meaning (AMBER)Meaning (X-PLOR)
red      energy penalty > 4.0violation > 10 degrees
orange      energy penalty > 1.0violation < 10 degrees
yellow      energy penalty > 0.0satisfied, but within 5 degrees of violated
green      energy penalty = 0.0satisfied and not within 5 degrees of violated

Note that X-PLOR torsion coloring can be adjusted with options to the xplor2tors conversion script.

By default, noeshow will not display the satisfied torsion angle constraints. The -A option flag will cause them to be displayed as well.

Restricting display
By default, noeshow displays all the violated constraints present in the constraint file. At times, this may be more information than is desired. There are several methods of restricting the displayed constraints to those of interest, detailed below.

In the early stages of structure refinement, it may be desirable to show only the badly violated constraints (if you are uncertain about all the cross-peak assignments, for example). Giving noeshow the -v option will restrict the display to only badly violated constraints (i.e. those colored red or blue).

The simplest way to restrict constraint display to specific areas of the structure is to undisplay the parts of the structure where you don't want constraints shown. Noeshow will not show constraints where one or both ends would be on an undisplayed part of the structure. To get this effect, you have to undisplay the undesired regions before running noeshow. You could then redisplay the whole structure after having generated the constraints of interest. Undisplaying parts of the structure after running noeshow has no effect on displayed constraints.

There is a somewhat more complicated method for restricting constraint display that offers finer-grain control than the above method. It involves using the relatively new mark and makemark commands of MIDAS. You may want to read the documentation for the above two commands in the MidasPlus manual if you are unfamiliar with them. These commands allow you to mark a set of atoms with a name. If you mark a set of atoms with the name ``noemark1,'' then noeshow will only show constraints where at least one end involves an atom in the marked set. If you also mark some atoms with the name ``noemark2,'' then noeshow will only show constraints where one end is in the first set and the other end is in the second set. For example:

makemark noemark1

would create the mark name ``noemark1'' for use, and:

mark noemark1 :12-14

would mark all atoms in residues 12 through 14 with the name ``noemark1.'' Running noeshow at this point would show only those constraints that had at least one end in residues 12 to 14.

Note that running the mark command with the same name a second time will add to the set of marked atoms, not replace the set with a new set. To replace, you would have to clear the mark with ``~mark name'' and then mark with the new set.

Structure Ensembles
To determine constraint satisfaction across an ensemble of structures displayed in MIDAS, noeshow uses exponential averaging (``R to the minus sixth''). The color-coded results are displayed on the highest-numbered open model. The same flags used to control pseudo-atom averaging (-D and -x) also control the ensemble averaging (see Options section). The -c flag, however, is ignored for ensemble averaging. If you want simple numerical averaging for the constraints, use ``-x 1'' instead of -c.

Normally, noeshow will give equal weight to each member of an ensemble. It is possible, however, to give the members unequal weightings. This could be useful, for example, if the ensemble had been generated by a program such as PARSE [1], which assigns a probability to each member of the ensemble. To indicate the weights to noeshow, there must be a line in each PDB file, as follows:

USER STRUCTURE WEIGHT weight

where weight is any non-negative number. Note that there are two spaces after the USER. Structures lacking a line such as the above will be given a weight of 1.0 (and therefore, if no structures have the above line, all will have equal weight).

Showing possible H-H interactions
Noeshow has one capability that is designed to be used primarily without a set of distance constraints: it can show all hydrogens within a given cutoff distance of one or more designated hydrogens. The general procedure to do this is to use the marking mechanisms discussed in the ``Restricting display'' section to designate both the hydrogens of interest (marked with noemark1) as well as the neighboring hydrogens that should be considered for the cutoff (marked with noemark2). Then noeshow would be run with the ``-h cutoff'' option to specify the cutoff distance. Noeshow will draw a pink line between each pair of hydrogens satisfying the cutoff criterion and will show the corresponding distance at the midway point of the line.

Since noeshow is implemented as a perl script, it is not very fast at numerical calculations. It is therefore best if you limit the marked sets of atoms to the smallest sets that still have all the atoms of interest. For example, let's say you have marked one or more hydrogens with noemark1, and you intend to run noeshow with a cutoff distance of 5 angstroms. You could simply not mark any atoms with noemark2, in which case noeshow would have to calculate the distance from every hydrogen marked with noemark1 to every other hydrogen in the molecule. It would speed things up considerably to use noemark2 to mark only those atoms that could possibly satisfy the cutoff, with a command such as:

mark noemark2 /mark=noemark1 za<5.1

which marks all atoms within 5.1 angstoms of the atoms in noemark1 with the mark noemark2 (this is one of the more advanced uses of atom specifiers; you may want to look at ``Referencing Models, Residues, and Atoms'' in the MidasPlus manual for further information, particularly the section ``Atom Properties'').

You need not mark one very small set of atoms and one larger set; you could mark approximately equally sized sets of atoms as long as the set size isn't too large (perhaps a few dozen atoms each). For example, if you were working with a nucleic acid structure and marked all H1*'s with both noemark1 and noemark2, and then used a cutoff of about 5 angstroms, the resulting helical ``chain'' of H-H lines would show where the structure had fairly even distances as well as where there were ``breaks'' in the structure.

The -h option was designed to be used with no distance constraint file, and is the only option that allows the distance constraint file to be omitted from the command line. Nonetheless, you can specify a distance constraint file and it will be shown normally. Note that since the marking mechanism is normally used to restrict constraint display, any marks used to delimit H-H interactions will also restrict displayed constraints.

Tips on usage
Displaying multiple constraint sets
There are times that it is desirable to display several different constraint files separately. For example, if you've divided your constraints into positive constraints (distances determined from a cross-peak: the atoms must be at most a certain distance apart) and negative constraints (distances determined from the absence of a cross-peak: the atoms must be at least a certain distance apart), then you might like to show these sets separately at first and then together. To do this, you would run noeshow once for each constraint set you want displayed. Noeshow will open each successive graphics object in a different model number (the lowest available at the time). You can then undisplay specific graphics objects with the ``~objdisplay modelnum'' command. ``objdisplay modelnum'' will, of course, redisplay them while ``close modelnum'' will dispose of them permanently.

Showing only torsion restraints
Showing torsion constraints with no distance constraints may seem problematic at first, since noeshow requires an argument specifying a file of distance constraints. However, this is simple to get around by specifying a distance constraint file that is empty. On UNIX systems (such as the SGI) there is a special system file that is always guaranteed to be empty: /dev/null. Therefore, invoking noeshow as:

noeshow [ options ] /dev/null torsion_file

would display only the torsion constraints in torsion_file.

Options
Many default behaviors of noeshow can be modified by command-line option flags. The options supported by noeshow are:

-a
Show all constraints, including satisfied constraints.

-A
Show all torsions, including satisfied torsions.

-c
For multi-atom pseudo-atoms, measure constraint to geometric centers of atoms rather than doing exponential averaging. See also the -D and -x flags.

-D
Don't divide by number of atoms when doing exponential averaging of pseudo-atoms. See the -x flag for more info.

-e lowbound
Change the lower energy penalty threshold (where torsion colors change from green to yellow) to lowbound. Default is 1.0.

-E hibound
Change the upper energy penalty threshold (where torsion colors change from yellow to red) to hibound. Default is 4.0.

-f file
Store violated constraints in a file named file, sorted by magnitude of violation. See also the -n flag.

-F
Don't quit on encountering the first error; continue to report errors. This is useful when debugging problems using noeshow, which is discussed in the next section.

-h cutoff
Show hydrogen-hydrogen interactions that are no more than cutoff angstroms apart. See the ``Showing possible H-H interactions'' section for a description of this option. If this option is specified, the constraint file command-line argument can be omitted.

-l
Label atoms involved in unsatisfied constraints. For pseudo-atoms, only the atom that the constraint is drawn to (the closest) is labeled.

-L
Expect LEaP nomenclature for atom names. LEaP is a module provided with AMBER. If you don't know what LEaP is, you don't care about this flag!

-n
Used in conjunction with the -f flag; show signs as well as magnitudes of violated constraints.

-v
Show only badly violated distance constraints.

-V
Show only badly violated torsion constraints.

-x exponent
Control the exponent used in exponential averaging of distances involving pseudo-atoms. Unless given the -c flag, noeshow does exponentially-weighted averaging of distances involving pseudo-atoms. If a constraint involves n atoms on one end and m atoms on its other end, then the weighted average distance is:

          |RR|c->n-c->m|exponent|____1   
          |n_m__________________|exponent
          |        n.m        |
          |                   |
          where ci is the coordinate position of the ith atom.
          The default exponent is -6.  Use of the -D flag
          prevents the division by n.m.
Errors
Noeshow displays error messages in the MIDAS reply area. Errors typically occur when there are problems matching atom names in the constraint file with those in the PDB file. Frequently in such cases many error messages are generated. In the Iris GL version of MIDAS, only the last few of these can be seen in the reply area.

If it is necessary to see all the error messages at once, this can be done by running noeshow outside of MIDAS . The first step is to get a PDB file from MIDAS to use as input to noeshow. In MIDAS, issue the command:

pdbrun cat > inputfile

This will save an annotated PDB file describing the current MIDAS display into a file called inputfile. Next, from a shell window, run:

/usr/local/midas/lib/midas/noeshow options_used_in_Midas < inputfile

The output from the above command will be a series of MIDAS commands. The output commands that start with echo are the ones that would display messages in the MIDAS reply area. Note that one of the output commands starts with !rm. This is to get MIDAS to remove a temporary file that noeshow produces. You may wish to remove this temporary file yourself by typing in the output ``rm'' command to the shell window, less the leading ``!.''

Mardishow
Mardishow is used to display constraints that are in MARDIGRAS input format and can be used to display constraints in MARDIGRAS output format, though noeshow can be used to display MARDIGRAS output also, as outlined in the ``Distance constraint preparation'' section, above. This section will outline the salient differences between using noeshow and mardishow.

Mardishow displays constraints in the two MARDIGRAS formats directly, i.e. the constraints do not need to be converted to an intermediate format, unlike the procedure for noeshow.

Since neither MARDIGRAS input nor MARDIGRAS output format constraints have an ``energy well'' associated with them, displayed constraint violations are color-coded differently than in noeshow. When showing MARDIGRAS output format constraints, mardishow constructs a ``fake energy well'' by using the given upper and lower bounds to define the ``floor'' of the energy well. The ``edges'' of the well are placed 0.5 angstroms beyond the given bounds (this margin can be changed with the -d option). Coloring is then as in noeshow. For MARDIGRAS input format constraints, the coloring scheme is simple: if the distance is less than 5 angstroms then the constraint is colored green, if between 5 and 6 angstroms yellow, and greater than 6 angstroms red.

Mardishow does not support restricting constraint display, either through the ``marking'' mechanism of noeshow or by undisplaying parts of the molecule. Bad things will happen if you try.

Pseudo-atom constraints are measured to the heavy atom connected to the hydrogens, rather than involving any kind of averaging.

Mardishow is designed to work with a single model structure rather than an ensemble. The only way to use mardishow in conjunction with an ensemble is to display one structure of the ensemble at a time.

Mardishow supports a subset of the flags of noeshow, namely: -a, -f, -F, -l, and -n. In addition, it has the following flags:

-d amount
When displaying MARDIGRAS output format constraints, make the outside bounds of the ``energy well'' amount angstroms from the inner bounds (which are given in the constraint file).

-s
Enable ``stereospecific'' constraints. If a constraint names a hydrogen involved in a rotamer and this option is given, then the constraint will be measured and drawn to that hydrogen. Otherwise, the constraint will go to the connected heavy atom.

FORMAT EXAMPLES

AMBER INTERFACE format
restraint/ at1=2:HA /at2=2:HN \
/r1=2.664 /r2=3.164 /r3=3.252 /r4=3.752 /k2=1.000 /k3=1.000 \

     and/or
     restraint / at1=1:H23 /at2 =1:H25 \
      /r1 = 0.0/r2=1.8000/r3=2.5980/r4=4.5980/k2=10.0/k3=10.0 \
      /grpat1 =1:H23,1:H24
     and/or
     restraint / at1=275 /at2 =290 \
      /r1 = 0.0/r2=1.8000/r3=2.5980/r4=4.5980/k2=10.0/k3=10.0 \
      /grpat1 =275, 276
AMBER SANDER namelist format
&rst
iat = 37, 35, iresid = 1, atnam(1)='H8 ',atnam(2)='H2''2', r1 = 0.000, r2 = 2.895, r3 = 2.945, r4 = 4.945, rk2 =10.000, rk3 =10.000, &end and/or &rst iat = 108, -1, igr2 = 143,144,145,0, r1 = 0.000, r2 = 3.315, r3 = 3.395, r4 = 5.395, rk2 =10.000, rk3 =10.000, &end

X-PLOR distance constraint format
     assign (resid    6 and  name HB   )(resid    7 and  name HN   ) 4.0 2.2 1.0
     assign (resid   34 and  name HB#  )(resid   39 and  name HN   ) 4.0 3.7 2.5 !
     assign (resid   37 and  name HB1  )(resid   39 and  name HN   ) 4.0 2.2 1.0
     assign (resid   23 and  name HB#  )(resid   26 and  name HB#  ) 4.0 5.2 4.0 ! !#
     assign (resid   22 and  name HB2  )(resid   24 and  name HN   ) 4.0 2.2 1.0
     assign (resid   20 and  name HB#  )(resid   22 and  name HN   ) 3.0 2.7 2.0 !
DIANA low and high bound constraint format
14 TYR HN      10 VAL O      2.00 1.00E+00 # H-Bond
13 ARG HN      14 TYR HN      2.90 1.00E+00 # N(i)-N(i+1)
11 VAL HA      14 TYR HN      5.00 1.00E+00 # ha(i)-hn(i+3)
14 TYR HA      17 ALA QB      3.80 1.00E+00 # ha(i)-hb(i+3)
14 TYR HA      29 LEU QD1      3.80 1.00E+00 # helix1-helix2
14 TYR QR      15 VAL QG2      7.80 1.00E+00 # sequential
18 LEU QD1      14 TYR QR      7.80 1.00E+00 #
24 ASP O      28 ALA HN      1.80 1.00E+00 # hbond
25 GLY HA1      28 ALA HN      5.00 1.00E+00 # aH(i)-HN(i+3)

AMBER torsion information format
------------------------------------------------------------------------------

Final Restraint Analysis for coords: min8.rst

      Restraints, deviations, and energy contributions:    pencut =     .00
      ------------------------------------------------------------------------------
          First atom        Last atom      curr. value target   deviation  penalty
      ------------------------------------------------------------------------------
               .
               .
               .
       CA   CYX   16 --  CB   CYX   16:    212.978   210.000     2.978      .863
       CA   SER   17 --  CB   SER   17:     29.656    30.000      .344      .011
       N    SER   19 --  CA   SER   19:   -158.920   -60.000      .000      .000
       CA   SER   19 --  CB   SER   19:     41.668    90.000      .000      .000
       CA   CYX   20 --  CB   CYX   20:    188.804   210.000      .000      .000
       N    ARG   23 --  CA   ARG   23:    -59.704   -60.000      .296      .009
X-PLOR torsion information format
     ---------------------------------------------------
     Number of dihedral angle constraints=   130
       overall scale =  200.0000
      ========================================
           3    GLN  C
           4    LYS  N
           4    LYS  CA
           4    LYS  C
      Dihedral= -126.639  Energy=    0.000 C=    1.000 Equil= -157.500 Delta=   -0.86
     1
      Range=  30.000 Exponent=  2
      ========================================
           4    LYS  C
           5    THR  N
           5    THR  CA
           5    THR  C
      Dihedral= -111.196  Energy=    0.000 C=    1.000 Equil= -120.000 Delta=    0.00
     0
      Range=  30.000 Exponent=  2
      ========================================

FEEDBACK

Feel free to mail suggestions or questions to pett@cgl.ucsf.edu .

NOTE

Noeshow and mardishow are perl scripts and, as such, require a perl command interpreter in order to work. Most systems already have a perl interpreter installed. If yours does not, one is provided in the MidasPlus distribution. Consult the MidasPlus Installation Guide for further details.

REFERENCES

[1] Ulyanov NB; Schmitz U; Kumar A; James TL.
Probability assessment of conformational ensembles: sugar repuckering in a DNA duplex in solution. Biophysical Journal, 1995 Jan, 68(1):13-24.

AUTHOR

Eric Pettersen
UCSF Computer Graphics Laboratory

ACKNOWLEDGEMENTS

Noeshow and mardishow could not have been written without the assistance and encouragement of Dr. Shauna Farr-Jones.

Xplor2amber was written with the assistance of Dr. Bryan Finn and Dr. David Schweisguth, and xplor2tors with the assistance of Dr. Brian Jones. Diana2amber was written with the assistance of Dr. Michael Zawrotny.