Navigator User Guide

Version 6.0, May 13 2004

 

Description

 

The main purpose of this NMRView plug-in in to help the user to easily navigate through multiple spectra, save views in memory and disk, quickly restore them, set spectral limits automatically in multiple spectra, jump to specific planes corresponding to specific residues, etc.

 

The navigator window is an original idea of Vincent Raussens.  It was first implemented in NMRView 3 and has been developed and updated since by Pascal Mercier at the University of Alberta, Edmonton, Canada.  Send any request, ideas and bug report to pascal.mercier@ualberta.ca.

 

This software is free and is provided as is. Please do not distribute this software.  Any changes must be submitted to the author.  Thanks for your collaboration.

 

WhatÕs new in 6.0

 

¥ Compatible with NMRViewJ 6.02.

 

¥ The navigator interacts with pipp_nav to draw assignments lines on your spectra when requesting for the 13C or 15N plane of a give residue, the same way the program Pipp used to do.  Pipp_nav is available for free from StŽphane GagnŽ lab at http://nmr.ulaval.ca/labo/software.html.  Get it now!

 

¥ Options are now turned into shades of gray when deselected.

 

¥ Uses a new approach to restore the last view: before the user takes any action with the navigator, the state of all windows that existed before the change is stored in memory.  Hitting the previous view button retrieves this view for the active window if the globalview option is on, otherwise it only bring back the last state of the active window.

 

¥ The autozoom now takes into account the size of the window and the width to height peak ratios to display peaks as rounded as possible.  Thanks to Ryan Hoffman from Brian SykesÕ lab for this idea.

 

¥ Several bugs were fixed.

 

Current limitations:

 

¥ The navigator is set to work with 2D and 3D spectra only.

¥ Multiple peak lists or datasets displayed in the same spectrum is not supported.

 

 

Standards you should obey to:

 

¥ For the navigator to work properly with 3D experiments, the peak relation of all peak lists should be set.  For 3D experiments, the navigator looks for the presence of ÒD3Ó defined in the Òpeak relationÓ to determine which of the 1st or 2nd dimension of the spectrum has its proton attached to the heteroatom in the 3rd dimension.  The navigator always assumes that the heteroatom (13C or 15N) is located in the 3rd dimension of 3D peak lists.

 

¥ Always name the 3rd dimension of your 3D experiments with a string that contains C or N, like 13C, 13C or C for instance.

 

 

Getting the program

 

The navigator is available for the Nanuc web site (http://www.nanuc.ca/NMRView).   Please do not distribute it.  Any modifications must be submitted to the author.

 

 

Installation

 

The navigator is provided in the form of a compressed tar file.  Untar the file directly where the NMRView program is installed.  For NMRView Aqua on OSX, if you have put NMRView Aqua in the Applications directory, you must move the file to /Applications/NMRViewAqua.app/Contents/Frameworks/NvLib.framework/Versions/5.1/Resources/Scripts/  and untar it from there.

 

The following files and directories will be created:

¥ nanuc_tcl/navig_v6.0.tcl

¥ nvtclC/specattributes.tcl (it will replace the existing one)

¥ images/navigicons/

¥ images/html/navigator_html

 

 

For the navigator to automatically be loaded when NMRView starts, you must do the following:

 

a) for any version of NMRView except NMRViewAqua:

 

To your NMRView startfile, add the line

 

                   source NMRView_installation_directory/nanuc_tcl/navig_v6.0.tcl

 

You can force NMRView to source a series of external scripts by invoking it with the Ðs option in the following way in your NMRView bin script:

 

#!/bin/csh

setenv NMRVIEW5HOME "/usr/local/nmrview5"

setenv TCL_LIBRARY  "${NMRVIEW5HOME}/tcl8.3"

setenv TK_LIBRARY  "${NMRVIEW5HOME}/tcl8.3"

setenv SMARTNOTEBOOK ${SMARTNOTEBOOK_DIR}

${NMRVIEW5HOME}/nmrview5 -- -s $NMRVIEW5HOME/nanuc_tcl/startfile

 

b) For NMRView Aqua:

 

Locate the script main.tcl in the folder /Applications/NMRViewAqua.app/Contents/Frameworks/NvLib.framework/Versions/5.1/Resources/Scripts/nvtcl/ and add the following lines at the very end of the file:

 

set rcFile [file join $NVH/nanuc_tcl startfile]

if {[file exists $rcFile]} {source $rcFile}

 

 

 

 

Overview of the navigator

 

 

 

 

  1. This entry field box displays the current plane number in the spectrum, the unfolded chemical shift of the current plane or the last residue number that was requested, depending on the active mode (see 4).  If the navigator is in multiplane mode (several planes of a 3D experiment displayed at once - see 20), a second row identical to the first one will appear below.  The two rows will display information about the lower and upper limit of the range of planes or chemical shifts of the z-dimension that are currently displayed for a 3D experiment.

    This box is also the userÕs input field to change plane or request a plane corresponding to a specific residue.  The user must select the proper mode (plane, ppm or res) prior to requesting a plane number, a plane corresponding to a given chemical shift (ppm mode) or a plane corresponding to a residue assignment (res mode).  If the user makes a request in the form resnumber.atom (45.CB, or 45.N, or 45.HN for instance), the navigator will automatically switch itself to the res mode. If the user is in res mode and types a number, the extension .N is automatically added to the request.


  2. When in ppm mode, will display the current chemical shift corresponding to the current plane in the z dimension minus 1 sweep width.  When in plane or res mode, nothing is displayed in this field.

  3. When in ppm mode, will display the current chemical shift corresponding to the current plane in the z dimension plus 1 sweep width. When in plane or res mode, nothing is displayed in this field.

  4. Sets the mode in which the navigator operates and displays the appropriate parameters in fields 1, 2 and 3. 

  5. Go button:
    after entering request in 1, activates the change.  As an alternative to clicking this button, the use can simply type return after entering a request in field 1 to activate the desired changes.

    Previous view button:  
    Before the user takes any action with the navigator, the state of all windows that existed before the change is stored in memory.  Hitting the previous view button retrieves this view for the active window if the globalview option is on, otherwise it only bring back the last state of the active window.

  6. Buttons controlling different options and navigator behaviors.  A red square is drawn around the buttons when the options are active (except when ran with NMRView Aqua on MacOS X due to a limitation in TclTk Aqua).  At startup time, all options are on.  Option icons are turned into shades of gray when off.

      Applies zoom and go to all spectra contained in the active window.  If off, will only apply changes to the active spectrum.

      Applies zoom and go to all spectra contained in all windows.

     Turns history record on.  The history is displayed in 10.

     Global view option.  When off, the navigator will save the view only for the active spectrum.  When on, the settings in all spectra are saved (region displayed, contour levels, etc).

     Option to zoom only in related spectra.  The ÒrelationÓ between different spectra is based on the axis labels.  If on, zooming-in on a 3D `15N-NOESY will not affect the spectral limits of a CBCACONNH.  However, it would affect a 3D `15N-TOCSY if both spectra share the same axis labeling.

      Option to turn on cursor auto-positioning after requesting a residue chemical shift.  The red cursor will be positioned on the child proton of the requested atom chemical shift.  In case a C atom has two protons attached, the black cursor will be positioned on the 2nd one.  Details will be output in the console about where each cursor is.

     Option to automatically focus around peaks belonging to a requested residue, after the request is issued.  Only works in ÒresÓ mode.  When working with a 3D experiment, you must have the 3rd dimension displayed in z.  If no peak list is displayed in the spectrum, the navigator will assume that the dimension displayed on the x axis is the directly detected dimension.  If a peak list is displayed, you must have the peak relation set up in the peak reference analysis panel with ÒD3Ó in the dimension that is dependant of the 3rd.

  7. Toggles between reduced size/full size for the navigator window.  When in reduced size, the history and the view parts are not displayed.

  8. Zoom-in , zoom-out  buttons.

  9. Text box to enter the name of a view to save.  After pressing return the name of the view is displayed in 14.

  10.  History list box. All requests made in the navigator are stored there provided that the history record option (see 6) in on.

  11.  Executes the history command selected in 10.  The navigator will automatically switch to multiplane mode if needed.  Similarly, it will automatically turn off the multiplane mode if the command requests a single plane only.

  12.  Deletes the history item selected in 10.

  13.  Deletes the history list.

  14.  List box containing the names of all the views that were saved.

 

  1.  After selecting a view in 10, clicking this button retrieves the view.

 

  1.  Erases the current view selected in 10.

 

  1. Deletes the whole view list.

 

  1. Save the list of views in 14 on disk

 

  1. Retrieves a list of views stored on disk

 

20. New menu and options in version 6.0

a) Multiplane mode
Activates the multiplane mode.  Since version 5, the navigator allows a range of planes to be drawn at once.  This feature will work when operating in the plane or ppm mode.  If you ask for a residue, the multiplane option will automatically be turned off.  Turning the multiplane mode on will display a second row of parameter boxes.

b)  Synchronize assignment panel
This option will update the assignment panel to the requested residue (in res mode)

c) Indirect dimension behavior (res mode)
Since version 6.0, the user has a few options to control how the navigator will control the display limits of the indirect dimension after requesting a residue.  Four modes are available to the user:

    ¥ Do not change the display Ð keep as is: self-explanatory.  The navigator will leave the existing spectral limit of the indirect dimension untouched.

    ¥ Adjust to show the requested residue:  If necessary and applicable, the navigator will change the spectral limit of the indirect dimension to include the chemical shift of the proton attached to the carbon or nitrogen of the requested residue. For instance, if the spectral limits are set between 1 and 2 ppm and the user requests 10.N, the indirect dimension will be modified to include the amide region and thus cover enough shift range to cover 10.HN.

    ¥ Set display limits according to related peaks: The navigator will look for peak related to the requested residue, and adjust the spectral limits to cover the peak with the highest and lowest shifts.  For instance, in a 3D-15N-Noesy experiment, if the user requests 10.N, the navigator will look for all peaks related to 10.N and 10.HN in the peak list, and adjust the spectral limits to cover all the peaks that were found.


   ¥ Set display limits to aliphatic region (up to 5.5 ppm)

   ¥ Set display limits to amide region (from 6.5 ppm)

   ¥ Set display limits to fist half

   ¥ Set display limits to second half

   ¥ Set display limits to maximum range: The navigator will always adjust the indirect dimension to its full range.

d)  Set autozoom x/y ratio from peak list
Since version 6.0, the navigator will attempt to display peaks so that they look as round as possible when the autofocus option is activated.  To accomplish this, the navigator does the following:  it first determines if a peak list is displayed in the spectrum.  If there is not, it tries to find a peak list among the ones present in memory that is related to the dataset displayed.  If the navigator finds a peak list to work with, it will determine the right range of ppm to be displayed in the direct dimension from the peak width/height ratio.  Note that this calculation is only performed once per peak list.

e) Set autozoom x/y ratio from display
The user can ÒteachÓ the navigator about the proper x/y aspect ratio to use by setting the dimensions of the window and the ppm range to be displayed until the peaks look round and by choosing ÒSet autozoom x/y ratio from displayÓ from the menu.

f) Help
Will open the navigator help html page (this documentation)

Written by Pascal Mercier
Department of Biochemistry

University of Alberta

pascal.mercier@ualberta.ca