Cindy User Guide

VERSION 1.7b May 6th 2006

AUTHORS

Andre Padilla

CBS Faculte de Pharmacie

34060 Montpellier

email : andre@cbs.cnrs.fr

 

Isabelle Roux & Pierre Coillard

EPSI

34090 Montpellier

 

 

______________________________________________________________________

 

 

1. Introduction

 

Cindy is a graphic software for the analysis of 2D-3D NMR spectra. Thousand  of spectra can be displayed and peaks added on graphics layers. Two types of layers are used. The « peak layers » to annotate,  assign, integrate peaks, and the spin system layer to keep,  display,  analyse spin system data.

Superimposition of several spectra, selection of spin-systems and labels  are some of the tools designed to show and keep the user information. Cindy uses OpenGL®, X® graphics and Tcl/Tk® interface. Macros access internal software data and new functions can be implemented by Tcl/Tk macros.

The software has a simple peak picking function and assignment macros but the basic  tools were mainly designed to simplify some  tasks, like spin-system editing, display, (and more), peak facilities, like editing labels, spectrum integration and conversion to constraint file.

 

1.1. Data Display

All the data is shown in the main window. All coordinates are in ppm from right to left and bottom to top for increasing ppm values. The Display in not limited by the spectrum itself as it is shown in the example below. The Homonuclear 2D spectrum in Yellow is centered at the water resonance (about 4.7 ppm) in both directions. The 13C-15N-1H 3D spectrum (in Red) is just below. The 15N-1H HSQC (in Cyan) is at the bottom of the view.

 

 

All these spectra can be inspected independantly. They can be moved to retrieve proper signal alignments  in the case where they were not properly referenced, for example. This lets open  many possibilities.

 

Loading Files is done by the File Open Menu. Data opens  NMR and ascii files using simple file selection. Macros runs Cindy configuration macros. Tcl runs Tcl/Tk macros. 3D Slices opens slices within a directory containing individual slices (2D contour extracted from a 3D spectrum). File format is automatically determined.

 

The program recognizes  type of files according to the codes given below.

___________________________________________________________________

Codes                                       Files Types

___________________________________________________________________

[ 1 ]                              1D bruker files, 1rr file (binary)

[ 2 ]                              2D NMR spectrum contour map (binary)

[ 3 ]                              3D data (stack of 2D contour maps)

[ 4 ]                              PDB file (ascii)

[ 5 ]                              Peaks and drawings in 2D (ascii)

[ 6 ]                              Spin systems (ascii)

[ 7 ]                              3D Bruker spectrum 3rrr file (binary)

[ 8 ]                              Peaks and drawings in 3D (ascii)

[ 9 ]                              Caculated Noes from structure

[ 10 ]                            2D bruker spectrum, 2rr file (binary)

[ 99 ]                            Unknown

 

The ppm scales are attached to a reference layer, indicated by the Main flag when using the Layers Info or List command. Changing this must be done carefully when one (or several) Layers were previously  shifted.

1.2. Demos

All demos are found in the demos directory.

Drawing demo

Titration demo

Homo_assignments

 

A simple Tutorial version can be started by sourcing the « tutorial.tcl » macro in the

Demos/TUTORIAL directory. To do this use the File è Open è Tcl command and double-click on the « tutorial.tcl » file. Do not try other files, results are not garanteed.

 

Tutorial & Easy Startup are more complete tools to start with Cindy.

Refer to the Help è Tutorial command  to have an overview of how to inspect and analyse spectra.

Briefly, the NMR spectra must be converted first to contour maps. This is done on the fly, by loading the raw data (only Bruker files), converting them to contour and writing the result to disk. An other way is using utility programs (in the util directory) to convert from bruker files. Finally,  in Gifa® the fplot command  can convert Gifa data to a contour file.

Cindy program version 1.7a is able to display NMR spectra, scale and translate in x, y directions using the mouse. Each spectrum is a layer which has its own behaviour and color. Cross peaks are added in an independant layer and are small objects (lines or rectangles) with their own labels, colors and linewidth. Naming Conventions of labels are set to manage peaks, to recognize assignments and to dialog with the spin system table.

 

The spin system table allows :

 

o spin system display by connected lines or by crosses, and labelling

o spin system identification by chemical shift matching

o sequential NOE search using peaks and spin systems :

-        in 2D using dNN, daN, dbN chemical shift matching

-        in 3D using HNCA and HNCO matching

o dipeptide - sequence comparizon to set sequence specific assignments

 

 

 

 

1.3. Mouse and Keyboarding

 

 

 

BUTTONS                           

            ACTIONS

 

 

  LEFT                                   

            picking and menu selection

  MIDDLE                            

            x and y translations

  RIGHT                                

            x and y rotations        

  MIDDLE + RIGHT           

            scale

  LEFT + RIGHT                  

            z rotation

  LEFT + MIDDLE + RIGHT         

            slab position

 

 

 

 

 

KEYS  + BUTTONS            

            ACTIONS

 

 

  Ctrl  + LEFT           

            not used

  Ctrl  + MIDDLE     

            x or y freezing

  Ctrl  + RIGHT        

            normal mode

  Shift + LEFT                       

            show next one

  Shift + MIDDLE                

            show previous

  Alt   + LEFT                       

            display all

  Alt   + MIDDLE     

            blank

 

 

  1.3.1.  Standard Mouse Buttons

 

  The three buttons are used to translate, change the scale and select menu or annotations.

 

  1.3.1.1.  Left Button

            Use this button to select items from the menus. In the case you want to select peak labels, be sure that the layer you want to select in is ready for selection. If you are not sure, look to the selection flag in the "Layers Info" menu.

 

  1.3.1.2.  Middle Button

            Use this button to apply translations (horizontal or vertical). Click on and drag the mouse.

 

  1.3.1.3.  Right Button 

            Use this button to apply rotations (horizontal or vertical). This action is only possible for 3D objects. Click on and drag the mouse.

 

  1.3.1.4.  Middle & Right Buttons

            Pressing both middle and right buttons enters in the scaling mode. Click on and drag the mouse.

 

  1.3.1.5.  Left & Right Buttons

            Pressing both left and right buttons enters in the rotation mode. This action is only possible for 3D objects, and rotates in the z axis. Click on and drag the mouse.

 

  1.3.1.6.  Left & Middle & Right Buttons

            Pressing all three buttons enters in the slab position operation mode. This action is only possible for 3D objects, and changes the clipping plan.  Click on and drag the mouse.

 

  1.3.2.  Other Possibilities

 

  Pressing special keyboard keys and buttons will do the job

 

  1.3.2.1.  Ctrl & Left Button

            not used

           

  1.3.2.2.  Ctrl & Middle Button

            Use this combination of Ctrl key and the middle button to freeze scaling and translation actions. The next direction you move by translation defines the other to freeze.

 

  1.3.2.3.  Ctrl & Right Button

            Use this combination of Ctrl key and the right button to restore translation and scaling.

 

  1.3.2.4.  Shift & Left Button

            Use this combination of Shift key and the left button to display the next layer in the stack.

 

  1.3.2.5.  Shift & Middle Button

            Use this combination of Shift key and the middle button to display the previous layer in the stack.

 

  1.3.2.6.  Alt & Left Button

            Use this combination of Alt key and the left button to display all the selected  layers.

 

  1.3.2.7.  Alt & Middle Button

            Use this combination of Alt key and the middle button to mask all the selected layers.

 

 

1.4. Hardware & Memory requirements

 

Cindy runs on SGI stations with IRIX 5 or 6, PCs under Linux and MacOsX.

Some examples are given below:

 

o INDIGO R4000 IP20 Graphics board: LG1

o INDIGO R4000 IP20 Graphics board: GR2-XS24 with Z-buffer

o INDIGO R4000 IP20 Graphics board: GR2-Elan

o INDY R4000 IP22 Graphics board: Indy 8-bit

o Pentium II 300 MHz, Graphics board: Matrox Millenium II AGP Linux RedHat

o  PowerMac G5 2x450 MHz, MacOsX 10.3.9

 

The program loads all contour maps in the memory. A regular 2D contour file requires about 2 to 3 Mb.

The SWAP configuration is at least a few hundred Mb. See swap (1M) - swap administrative interface - for more details.

When starting the program you must specify the amount of memory (space allocated to Cindy  process). This is done by giving a number which indicates the amount of MegaBytes of the data array. By Default 8 MegaBytes are allocated.

 

> cindy 512

 

The above example  sets 512 MegaBytes memory which is sufficient to open 2D and 3D experiments.

 

For information on MEMORY settings see ´´Appendix B''

 

1.5. Capabilities of version cindy 1.6a

 

The maximum loadable data is given below, with corresponding internal variables within brackets. These variables are specific to the program’s  version

 

o Maximum number of total layers [cny_isizez + cny_maxmodels + cny_maxlayers + cny_max3d + 1]

o Maximum number of one dimensional spectra [cny_isizez]

o Maximum number of two dimensional spectra 4096 [cny_isizez]

o Maximum number of three dimensional spectra 32 [cny_max3d]

o Number of 2D or 3D bruker spectra 1

o Maximum number of molecules 8 [cny_maxmodels] (4000 atoms, 400 residues)

o Maximum number of drawing layers 16 [cny_maxlayers] with a maximum of 2000 peaks [cny_maxarrow]

o Maximum number of spin systems 350 [cny_maxsets]

o Maximum number of spin topics 40 [cny_maxspins]

 

o NOTE : Maximum number of loadable 1D spectra or 2D – 3D maps depends also on the size of the data buffer (see ´´Section 1.4. Memory requirements'' for more informations).

 

1.6. Installation note

 

(A) Uncompress the file using the command

> gunzip cindy.tar.gz

 

then extract the files by the command

> tar xvf cindy.tar

 

(B) Configure the swap area if needed (see section ´´Memory requirements'')

 

(C) The location of the Tcl library must be defined with the environment

variable CNY_LIBRARY. An example is shown in the Cindy.env file

provided with this release.

 

Go to your home directory, edit your .cshrc file and add the lines :

 

setenv CNY_LIBRARY /my_prog_disk/cindy/library

setenv TCL_LIBRARY /my_prog_disk/cindy/library/tcl

setenv TK_LIBRARY /my_prog_disk/cindy/library/tk

 

according to the "library" directory . In the example above, the

"/my_prog_disk/cindy" directory should be changed to fit your configuration. Save this file, to update changes.

 

source your .cshrc file by entering the command

 

> source .cshrc

 

First select the appropriate executable. Starting the program is done by entering the command

> /my_prog_disk/cindy-1.5/Bin/my_machine/cindy 32

 

This will start the program with 32 Mbytes of data.

 

To set the window size at startup create and edit the file « CindyGlx « in your home directory

 

!------------------------------------------------------

!       Cindy 1.7a

!------------------------------------------------------

CindyGlx*geometry: =960x960

 

Next startup size will be 960 pixels by 960 pixels

 

Start cindy and  save a preference file in your home directory. Using

 

File -> Preferences -> Write

 

1.7. Some definitions and conventions

 

1.7.1. Command Syntax

All commands in CINDY start with the prefix cy_, except some special commands used to update the graphic display. The main commands are cy_file, cy_edit, cy_arrange, cy_tools, cy_one_D, cy_two_D, cy_three_D. However, they are used in the top menu without prefix. A more complet listing of the commands is obtained from the starting shell using the Tcl info command:

 

% info commands  cy_*

 

Commands for updating the graphics are obtained by:

 

% info commands  update*

 

All variables in the program start with the prefix cny_. The list of all variables known by the program may be obtained by the command:

 

% info var cny_*

 

 

1.7.2. Drawing Layer (or peak labels)

This is a graphic layer which contains drawings like lines, rectangles, circles, etc. This is the default graphic layer type created by CINDY, when using the command "cy_file new". This type of graphic layer is used to keep Peaks with or without assignments. Usually, an assignment label is attached to a line which starts from the peak center. However, it is possible to use rectangles as well (to delimitate a peak area, for example to integrate), but this may give something unreadable, especially in crowded spectral areas.

 

1.7.3. Contour Map

This is a graphic layer which contains 2D contour lines. The 3D spectrum is a stack of 2D contour maps. Usually the first loaded contour map will be the main layer.

 

1.7.4. Peak Annotation

This is a line which belongs to a drawing layer which starts at the center of a cross peak.

 

Example of cross peak annotations

Selected lines (or rectangles) can be resized by click & drag on the selection handles.

 

1.7.5. Cross Peak Syntax

The cross peak assignment syntax to give assignment  to a peak is the following:

ATOM1 (RES1) ATOM2 (RES2)

 

The first ATOM item correspond to the first spin (for example HA, HN, HB, etc) of the first residue NUMBER (in this example RES1). This is taken from the vertical direction (i.e. the F1 dimension of the 2D spectrum). The second ATOM and RES2 must be set with the same rules, but applied to the second dimension (i.e. horizontal, F2 dimension of the 2D spectrum). Intra-residual cross peaks have RES1= RES2. Parenthesis are delimiters used to recognize the label. For an unassigned cross peak there is no label .

1.7.6. Spin System Layer and Syntax

There is only ONE possible Spin System Layer (text in ascii file). Its graphic rendering is build from the text itself, The spin system names follow the same general rules just described for cross peaks labels. Spin system names are build according to information found in the RESIDU, NUMBER and SPIN columns found in the text file with is used for spin system management.

 

1.8. Interfacing with other programs

 

Programs to convert files are provided with Cindy in the directory "util". User defined labels and annotations files may be obtained using conversion tools. (UNIX awk or other programs).

 

1.8.1. From GIFA

 

The contour files loaded in CINDY can be obtained from GIFA using the GIFA command "fplot" followed by a file name.

 

1.8.2. Utility Programs to Translate data

 

1.8.2.1. ux2cindy

 

The utility program "ux2cindy" can be used to convert, 2rr bruker files from X32 computer. You must be in the "/u/data/user/nmr/expname/expnum/pdata/procnum" directory when running this program. ux2cindy creates a file named contour_file using parameters found in procs, proc2s and levels bruker files. When the conversion is done, the best is to move the contour_file in your working directory. Do not forget to change the name of the contour_file with a self explanatory name like noesy_ph5_305K for example.

 

usage: ux2cindy

 

1.8.2.2. sgi2cindy

 

The utility program "sgi2cindy" may be used to convert, 2rr bruker files from sgi or specstation1 computers. You must be in the "/u/data/user/nmr/expname/expnum/pdata/procnum" directory when running this program. sgi2cindy creates a file named contour_file using parameters found in procs, proc2s and levels bruker files. When the conversion is done, the best is to move the contour_file in your working directory. Do not forget to change the name of the contour_file with a self explanatory name like noesy_ph5_305K for example.

 

usage: sgi2cindy

 

1.8.2.3. invert_contour

 

The program invert_contour is used to switch x y co-ordinates for each line in a contour map file. It is useful to invert a 2D homonuclear spectrum to check symmetry of cross peaks.

 

usage: invert_contour -i file -o output

 

1.8.2.4. labels

 

The program labels is useful to build a file containing annotations at x y co-ordinates given by two files of chemical shifts and a file defining what contacts to use. The contact file can be constructed to obtain sequential or medium range or whatever connectivities.

 

usage: labels -ix ppm1 -iy ppm2 -co contacts -l label -o output

 

Where:

 

ppm1 is a file with a sequential list of chemical shifts in ppm used for the x direction

 

ppm2 is a file with a sequential list of chemical shifts in ppm used for the y direction

 

contacts is a file with a list of contacts according to entries in the ppm1 and ppm2 files

 

label is a string used for annotations

 

output is the file name of the output file.(in drawing layer format used by CINDY).

 

File Formats are described in ´´Appendix A''

 

1.8.2.5. extract_contour

 

The program extract_contour may be used to extract a sub region from an already existing 2D map file. It is useful for cutting a 2D spectrum according to user needs (removing water area, artefacts or extracting a residue spin system by bands).

 

usage: extract_contour -i file -x regions -o output

 

Where:

 

file is the input 2D map file

 

regions is a file having the definitions of regions to extract in ppms

 

output is 2D map file containing the extracted regions.

 

See ´´Appendix A''

 

1.8.3. From Bruker (1D, 2D and 3D)

 

Bruker files may also be directly loaded by the program. In the case of 1D spectra the number of possible spectra depends on the configuration of the data stack which is at least of 64 Mb.

 

For 2D or 3D data sets : only one spectrum of that type can be loaded at the time. This is because  levels must be changed by the user, when needed  and thus the corresponding contour map size is not defined. When levels are defined the contour must be computed, before saving it. When the contour map is done it is possible to read again a new 2D or 3D data set in bruker format.

 

2. Loading Files

 

Cindy commands  are selected from the top menu just by pressing the left mouse button.

 

 

Top menu

 

Commands may also be entered from the terminal window. The command should start with the header "cy_", followed by the rest of the command. For example "file open" must be entered as "cy_file open". The command syntax is given in the related topics in section ´´Commands''.

 

2.1. Loading 1D Bruker file

 

Got to the 1D/pdata/1 in the data directory . Selected the 1r file and Choose "Open" from the menu.

 

 

Opening a data file

 

 

The Open button will load the spectrum and will display the spectral region close to 0.0 ppm. In the case of heteronuclear spectra the best is to set the layer containing the 1D spectrum as the main layer (Layers Info) and to display the x ppm scale (Tools Toolbox) in order to be able to display on screen the spectral region of interest.

To View a 1D spectrum with ppm scale

 

2.2. Loading 2D Bruker file

 

Reading processed 2D bruker bruker files is similar.

 

 

Initially the spectrum is shown in intensity mode with low resolution. This mode is used to set up the number of levels as well as the levels themselves. They are shown in a message box with commande Contours > 2D contour.

 

Intensity Mode Display

 

Levels are those found in the "level" file set up with the "defplot" bruker command. Changing levels in Cindy is done by clicking on one of the levels and using "Contour 2D Bruker Levels" command.

The new levels are shown on the screen only when the Levels button is pressed. When proper levels have been set, it is possible to compute the corresponding 2D contour map using the "Contours" button.

 

2D Spectrum in Contour Map mode

 

The 2D contour map is not automatically saved on disk. In order to save it to a file you must use the "File Save" menu

 

2.3. Loading 2D contour maps

Contours file (in Cindy format) are loaded directly. This is faster than reading a Bruker File and converting it to a 2D contour layer. See Translation Programs in section 1.8.3 ´´From Bruker (1D and 2D)''.

2.4. Loading 3D Bruker file

For 3D data the conversion steps are identical than for 2D except that the readding direction must be set prior readding. This is done by setting the variable « cny_plan_normal » to a value , 1 , 2 (default) or 3. In the interpreter window :

set cny_plan_normal  1

sets the readding direction orthogonal to dimension 1, e.g. allows readding of 3D plans of frequency dimensions 2 and 3.

Levels selections are done by Contours > 3D bruker levels which shows a selection window. Clicking on the level button displays new selected levels for a 3D slice. The slice ID must be set in the corresponding slice selection window. Contours are computed by pressing the Contour button.

2.5. Working Environment

When working on a project it is often better to create a working directory with one or several "configuration" files and data files. The 2D contour files may optionally be located in the working directory. It is safe to put the graphic layer files (Peaks) and spin system files in the working directory.

 

A "configuration" file generally will performed the following tasks:

o open contour maps (NMR spectra)

o open layer files (Peaks)

o open the spin system file

o set RGB colours for contour maps

o open the toolbox and mini spectrum, and set the ppm scales

 

Opening files is done using the "file open" command (see section 6. ´´Commands'' for a complete description of commands). Setting colours is done using the "make colour" command, and opening toolbox and mini spectrum are done by the "tools toolbox" and "tools mini" commands, respectively.

 

A generic "cindy.config" file is listed below and may be used to set up your own "config" file. Just replace file names and the directory name /my_working_directory/ with the appropriate names. Several contour maps and graphic layers can be opened this way. However, only one spin_system file can be opened.

 

cy_file open /my_working_directory/contour_file 2 contour_name

cy_file open /my_working_directory/annotations 5 graphic_layer_name

cy_file open /my_working_directory/spin_system_file 6 spin_systems

cy_make colour 1 255 255 255

cy_tools toolbox

cy_tools mini

cy_two_D x_scale

cy_two_D y_scale

 

3. The Mouse

The control of the graphic display works with the mouse and sequences of keyboard keys and mouse buttons (see section 1.3). Picking and menu selection is done using the left mouse button. Translation of layers in the xy plane is done by pressing the middle mouse button and moving the mouse. Similarly, xy rotations are done using the right mouse button. Rotations only apply to Molecule  type layers and are not active for 2D type layers. Pressing both middle & right mouse buttons and moving will change scales in x and y directions independently for 2D layers, and the whole scale of a 3D type layer. Rotation around the z axis for 3D type layers is done by pressing left & right mouse buttons and moving the mouse.

 

Special keyboard key and mouse button sequences are used to perform other tasks. Text annotation apply to the last selected drawing and is done by using the sequence "ctrl" key & left mouse button. A new window appears called "label dialog_popup" where the text may be edited.

 

 

 

Click here for Picture ´´@eval loadHelpImage doc11.gif''

Label window opened using "ctrl" & left mouse button

 

Enter the text just below the line "Enter label" and pressing OK will append

the string to the selected item.

 

Sometimes it is useful to avoid translation of layers along one of the x or

y directions. This is done by the sequence "ctrl" & middle mouse button.

After this has been done the program waits for the first direction to be

translated, and blocks any possibility of translation for the other.

Releasing both x and y translations is done by repeatting the sequence

"ctrl" & middle mouse button, or by using the sequence "ctrl" & right mouse

button.

 

For an already existing annotation it is also possible to change its

orientation or position. Changing position is simply done by selecting the

item with the left mouse button but still pressing the left button by moving

the mouse. Doing this on the Selected item of the figure below will change

its coordinates without changing those of the Unselected item.

 

Click here for Picture ´´@eval loadHelpImage doc12.gif''

Changing orientation of an existing item is done by selecting it and

choosing the "double arrow" button in the toolbox.

 

Click here for Picture ´´@eval loadHelpImage doc13.gif''

 

Part of the toolbox showing drawing modes and utilities.

 

The "double arrow" is located at the bottom.

 

Meaning of the items defining modes is shown below:

 

Line drawing pen filled rectangle buffer h line

 

Rectangle drawing cross filled circle buffer v line

 

Circle drawing eraser double arrow normal (hand)

 

The pen, cross and buffer lines items apply only to the buffer and will not

add anything to drawing layers.

 

At any time the user may handle layers, i.e. Display or blank a layer. This

is done within the toolbox according to three different status flags

associated to a given graphic layer. The first column in the layer stack

indicates the status of the mouse, i.e. whether or not the mouse actions

will be applied to the layer. This status is shown by the letter "M". The

second column in the layer stack indicates if the layer is visible ("D") or

blanked if the flag D is not present in that column. The third column in the

layer stack indicates if the layer is active for change or selection. This

is shown by the status letter "C".

 

Click here for Picture ´´@eval loadHelpImage doc14.gif''

 

Part of the toolbox showing the layer stack and the drawing mode selection

buttons.

 

In the case of this layer, all flag are activated. This mean that the

spectrum will be displayed on the screen, and translations and scaling are

possible. Its status flag "C" means that the content of this layer can be

changed, as well as its colour. The rubber item is selected in the toolbox,

and contour lines may be erased. This is done by clicking at the lower left

corner of the area to delete and moving the mouse to the upper left corner

still pressing the left mouse button.

 

Click here for Picture ´´@eval loadHelpImage doc15.gif''

 

Part of the initial spectrum

 

Click here for Picture ´´@eval loadHelpImage doc16.gif''

 

Definition of the area to delete

 

Click here for Picture ´´@eval loadHelpImage doc17.gif''

 

Deleting the area is done by releasing the mouse button

 

Spectrum overview is done through what is called the mini spectrum. This is

an image of the main layer, i.e. usually a 2D contour map. The mini spectrum

also indicates to the user the actual region which is displayed in the main

window. The user as well may directly zoom in (and zoom out) just by

clicking in the mini spectrum. Zoom expansions in x and y directions are

adjusted by two scroll bars, one horizontal for the x direction and the

vertical for the y dimension.

 

Click here for Picture ´´@eval loadHelpImage doc18.gif''

 

View of the mini spectrum window

 

4. The Tools

Tools è Toolbox

 

 

5. Spin System Edition

The spin systems in Cindy are defined using an ascii text. Example of such files are given with the cindy/USER/spin_standard.txt and cindy/tutorial/example.spin files. Pressing the OK button within the spin editor window will process the text according to KEY words. The spin editor (SpinSys Edit) is divided in two parts. At the top of the window is found the Chemical Shifts Clipboard which contains a list of the chemical shifts obtained from the annotations copyied in the buffer using the "Edit Copy" command. The Edit button allows copy/paste actions to be applied within the text subwindow.

In the Spin Editor the Copied chemical shifts are listed sequentially and are separated by vertical lines

Spin Editor Text Area. The Display button is used to process the text.

 

The syntax rules applied to the text is done according to the following list of KEY words (in capitals):

 

SPIN, COLOR, NOE, SEQUENCE, WORDS, SET, END, RESIDU, NUMBER, DISPLAY, LABEL,

NEXT, FIND.

 

The first step involve definition of the spin names which is done by a line starting with the key word SPIN.

 

This is shown in the next line which defines something called HN which is expected between 12 and 5 ppm.

 

SPIN HN 12.00 5.00 defines proton HN (12.00 and 5.00 specify the ppm range allowed for NH)

 

Other examples are

 

SPIN HA 6.00 2.50 defines proton HA (used also for HA1 of GLY or when HA1 and HA2 are superimposed)

 

SPIN HA2 5.00 3.00 defines proton HA2 (for GLY)

 

SPIN HB 4.00 1.00 defines proton HB (used also for HB1, or when HB1 abd HB2 are superimposed)

 

SPIN HB2 4.00 1.00 defines proton HB2

 

Colours are defined by a line starting with the key word COLOR. The white colour is default, i.e. if a colour is not defined but is still used then the progam takes by default the white colour. The next line shows how to define the red colour, its name is "red" and 255 0 0 numbers is the corresponding RGB code.

 

COLOR red 255 0 0 defines red colour

 

Other examples

 

COLOR green 0 255 0 defines green colour

 

COLOR blue 0 0 255 defines blue colour

 

COLOR cyan 0 255 255 defines cyan colour

 

NOEs are defined when the line starts with the key word NOE. The first argument is the name which will be used to define the NOE. The second and third arguments are the names of the two spins which are involved in the NOE. These two spins must have been previously defined with a SPIN definition. The last argument is a number which corresponds to the position in the list (in case of multiple possible assignments). For example defining a sequential alpha to NH NOE, and asking to select the closest in ppm (first position) is done by the line:

 

key word noe name 1st spin 2nd spin position in the list

 

NOE dan HA HN 1

 

Other Examples

 

NOE dbn HB HN 1 defines sequential noe dbn (id)

 

NOE dnn HN HN 1 defines sequential noe dnn (id)

 

NOE dan1 HA HN 2 defines sequential noe dan (the second candidate)

 

NOE dnn1 HN HN 2 defines sequential noe dnn (id)

 

Definition of the sequence is done in one or several lines. Each line must start with the key word SEQUENCE. Each of the words after the key word SEQUENCE are added to the sequence array and are supposed to correspond to the names which will be found in the RESIDU column.

 

SEQUENCE ALA ALA

 

The sequence continues in the next line

 

SEQUENCE GLY ASP LEU ARG ASN PHE

 

The total sequence will be (ALA ALA GLY ASP LEU ARG ASN PHE)

 

The start of the real data block (i.e. spin systems) is done when the line

starts with WORDS. Then the program expects ONLY !!! key words on this line

with the following Rules !!

 

Generic KEY words must be present as well as all SPIN names and all NOE

names. This is shown in the following line :

 

WORDS RESIDU NUMBER HN HA HA2 HB HB2 DISPLAY LABEL COLOR dan dbn dnn dan1

dnn1 NEXT

 

Note that ALL PREVIOUSLY DEFINED SPINS AND NOES MUST APPEAR ON THE "WORDS

LINE" IN ANY ORDER.

 

Then each spin system is defined by a line which must start with the SET key

word otherwise it will not be processed. Key Words within each column for a

given spin system have the following code :

 

RESIDU NUMBER DISPLAY LABEL COLOR NEXT

 

RECOGNIZED ANY ANY CROSS 1+2 USER FIND

 

STRING BOXES 1 DEFINED ANY

 

CHOICE ANY 2

 

ANY

 

NOTE: ANY means that any string may be used. If the decoder expect a key

word and if it is not recognised then no action will be taken. For example

if the user does not use CROSS or BOXES in the DISPLAY field then the

corresponding SET will not be displayed on the screen.

 

Key words 1+2, 1 and 2 in the LABEL column are used to display spin systems

names according to what is found in the RESIDU and NUMBER columns. The Key

word FIND in the NEXT column tells the program for searching NOEs when the

"spin connect" command is selected from the menu.

 

When the line starts with END then the program stop processing. This key

word is optional and is useful only when a fragment of the text needs to be

processed. This is mainly the case when several experimental conditions are

used and thus spin systems exist in multiple copies within the text file.

 

A simple example of SET lines is shown below :

 

WORDS RESIDU NUMBER HN HA HA2 HB HB2 DISPLAY LABEL COLOR dan dbn dnn dan1

dnn1 NEXT

 

SET ALA 1 10.22 4.30 ---- 1.40 ---- CROSS OFF white --- --- --- --- --- FIND

 

SET ALA 2 9.22 4.20 ---- 1.50 ---- BOXES 1+2 red --- --- --- --- --- ---

 

With this three lines two spin systems will be displayed. The first one,

named ALA 1, will appear on the screen in white colour crosses without

labels. The second spin system named ALA 2 will be displayed with red lines

and labels will be present at the intercepts of lines. Issuing the "spin

connect" command will search for dan, dbn, dnn, dan1 and dnn1 NOEs for the

first spin system. See "spin connect" topic for more details.

 

6. Commands

Generated from ./ with ROBODoc v4.99.6 on Mon May 29 14:51:49 2006


[Variables] /cny_alarme

[top]

NAME

 cny_alarme gives the time laps between backups  cny_alarme 

SEE ALSO

 Library/simple_save 

[Variables] /cny_blue_index

[top]

NAME

 cny_blue_index tells blue color index of layer iobj  cny_blue_index(iobj) with iobj is the layer id 

[Variables] /cny_bnow

[top]

NAME

 cny_bnow tells the blue color index of the toolbox 

SEE ALSO

 Library/tools 

[Variables] /cny_dat_name

[top]

NAME

 cny_dat_name tells the name of the file associated with layer iobj  cny_dat_name(iobj) with iobj is the layer id 

[Variables] /cny_font

[top]

NAME

 cny_font sets the font used for ppm and labels in the graphic window  cny_font needs a valid font input 

[Variables] /cny_gnow

[top]

NAME

 cny_gnow tells the green color index of the toolbox 

SEE ALSO

 Library/tools 

[Variables] /cny_green_index

[top]

NAME

 cny_green_index tells green color index of layer iobj  cny_green_index(iobj) with iobj is the layer id 

[Variables] /cny_icount

[top]

NAME

 cny_icount gives the number of contour line of a NMR layer i  cny_icount(i) where i is the stack order of iobj 

SEE ALSO

 cny_object_status(iobj, 5) 

[Variables] /cny_idx_data

[top]

NAME

 cny_idx_data returns the index value of coordinate i for line j in spectrum k  cny_idx_data( i, j, k) where i : 0, 1, 2 or 3                               j : contour line number (integer)                               k : spectrum id in the stack 

SEE ALSO

 cny_object_status(iobj, 5) 

[Variables] /cny_imain

[top]

NAME

 cny_imain tells which layer is reference for ppm scales and values 

[Variables] /cny_interact

[top]

NAME

 cny_interact tells interaction status. What you are doing with the mouse.  cny_interact   0 : selection (change) mode, show x and y ppm values                 1 : single line drawing (right button opens line width panel)                 2 : single boxe drawing                 3 : single circle drawing                 5 : cross at cursor position                 6 : erase contour when a 2D layer is selected                 7 : plain boxe drawing                 8 : plain circle drawing                 9 : single line change                10 : horizontal line at cursor                11 : vertical line at cursor 

SEE ALSO

 Library/tools 

[Variables] /cny_isizex

[top]

NAME

 cny_isizex number of sub-cuts in x direction for spectrum ist   cny_isizex(ist) where ist is the spectrum id in the stack 

[Variables] /cny_isizey

[top]

NAME

 cny_isizey number of sub-cuts in y direction for spectrum ist   cny_isizey(ist) where ist is the spectrum id in the stack 

[Variables] /cny_nlines_cutoff

[top]

NAME

 cny_nlines_cutoff maximum number of contour lines displayed (cut off if exceeded)  cny_nline_cut_off applies for all spectra 

[Variables] /cny_number_objects

[top]

NAME

 cny_number_objects tells how many layers are loaded 

[Variables] /cny_numlin

[top]

NAME

 cny_numlin returns a value giving the total number of contour lines at ix, iy sub-square  Only valid for 2D contours (and 3D)   cny_numlin(ix, iy, ist) where ix : 1 .. cny_isizex                                iy : 1 .. cny_isizey                                ist: spectrum id in the stack 

[Variables] /cny_obj_name

[top]

NAME

 cny_obj_name tells the name for layer iobj  cny_obj_name(iobj) with iobj is the layer id 

[Variables] /cny_object_status

[top]

NAME

 cny_object_status tells infos for layer iobj  cny_object_status(i, iobj) with i=1 (active status, 0 or 1)                                  i=2 (type 1, 2, 3, ..., 10)                                  i=3 (display status, 0 or 1)                                  i=4 (selection status 0 or 1)                                  i=5 (stack order) 

[Variables] /cny_red_index

[top]

NAME

 cny_red_index tells red color index of layer iobj  cny_red_index(iobj) with iobj is the layer id 

[Variables] /cny_reverse_bytes

[top]

NAME

 cny_reverse_bytes re-order bytes when readding binary data   cny_reverse_bytes internal use (should be carefully used otherwise) 

[Variables] /cny_rnow

[top]

NAME

 cny_rnow tells the red color index of the toolbox 

SEE ALSO

 Library/tools 

[Variables] /cny_xdata

[top]

NAME

 cny_xdata show NMR raw data values  cny_xdata 

[Variables] /cny_xmax

[top]

NAME

 cny_xmax maximum ppm value in x direction for spectrum ist   cny_xmax(ist) where ist is the spectrum id in the stack 

[Variables] /cny_xmin

[top]

NAME

 cny_xmin minimum ppm value in x direction for spectrum ist   cny_xmin(ist) where ist is the spectrum id in the stack 

[Variables] /cny_xnow

[top]

NAME

 cny_xnow tells horizontal ppm value of cny_imain layer 

SEE ALSO

 cny_imain 

[Variables] /cny_xrot

[top]

NAME

 cny_xrot rotation on horizontal axis for layer iobj  cny_xrot(iobj) with iobj is the layer id (MOL) 

[Variables] /cny_xsca

[top]

NAME

 cny_xsca horizontal scaling for layer iobj  cny_xsca(iobj) with iobj is the layer id 

[Variables] /cny_xtrans

[top]

NAME

 cny_xtrans horizontal translation for layer iobj  cny_xtrans(iobj) with iobj is the layer id 

[Variables] /cny_ymax

[top]

NAME

 cny_ymax maximum ppm value in y direction for spectrum ist   cny_ymax(ist) where ist is the spectrum id in the stack 

[Variables] /cny_ymin

[top]

NAME

 cny_ymin minimum ppm value in y direction for spectrum ist   cny_ymin(ist) where ist is the spectrum id in the stack 

[Variables] /cny_ynow

[top]

NAME

 cny_ynow tells vertical ppm value of cny_imain layer 

SEE ALSO

 cny_imain 

[Variables] /cny_yrot

[top]

NAME

 cny_yrot rotation on vertical axis for layer iobj  cny_yrot(iobj) with iobj is the layer id (MOL) 

[Variables] /cny_ysca

[top]

NAME

 cny_ysca vertical scaling for layer iobj  cny_ysca(iobj) with iobj is the layer id 

[Variables] /cny_ytrans

[top]

NAME

 cny_ytrans vertical translation for layer iobj  cny_ytrans(iobj) with iobj is the layer id 

[Variables] /cny_zrot

[top]

NAME

 cny_zrot rotation on Z axis for layer iobj  cny_zrot(iobj) with iobj is the layer id (MOL) 

[Variables] /cny_zsca

[top]

NAME

 cny_zsca Z scaling for layer iobj  cny_zsca(iobj) with iobj is the layer id 

[Variables] /cny_ztrans

[top]

NAME

 cny_ztrans Z translation for layer iobj  cny_ztrans(iobj) with iobj is the layer id 

[Functions] /cy_file

[top]

SUMMARY

 File open, save, close, new . 

USAGE

 cy_file options 

FUNCTION

 General File routine 

INPUTS

 open         :  new          :   new3D        :  backup       :  print        :   quit         : 

OUTPUTS

 error code if error else zero 

SEE ALSO


[Functions] /cy_make

[top]

SUMMARY

 Mouse behaviour, Reset display, Zoom . 

USAGE

 cy_make options 

FUNCTION

 General Display Behaviour 

INPUTS

mouse+       : increase by a factor of 2 translation & scaling  
mouse-       : reduce   by a factor of 2 translation & scaling
reset_mouse  : reset translation & scaling factor  zmouse+      : idem  
zmouse-      : idem  
reset_zmouse : idem  
main         : set the first selected layer to be the main layer                 
NB: avoid to set a PDB layer  
link         :   
colour       :  
reset        :  
active       :  
unactive     :  
zoom         : 

OUTPUTS

 error code if error else zero 

SEE ALSO


[Functions] /cy_one_D

[top]

SUMMARY

 Display ppm scale of a one d NMR spectrum 

USAGE

 cy_one_D scale 

FUNCTION

 Display at the bottom of the window a ppm scale  anchored to the main layer 

INPUTS

 x scale  : horizontal ppm scale  scale    : idem  

OUTPUTS

 error code if error or zero 

SEE ALSO

 cy_two_D 

[Functions] /cy_two_D

[top]

SUMMARY

 Display ppm scale of a two d NMR spectrum 

USAGE

 cy_two_D (x or y) scale 

FUNCTION

 Display at the left or bottom of the window a ppm scale  anchored to the main layer 

INPUTS

 x scale  : horizontal ppm scale  x scale  : vertical   ppm scale  

OUTPUTS

 error code if error or zero 

SEE ALSO

 cy_one_D 

[Functions] /delete_data

[top]

SUMMARY

 Remove data from stack 

USAGE

 delete_data layer(id#) 

FUNCTION

 Delete data of layer(id#) 

INPUTS

 layer(id#)  : integer giving the layer id number 

OUTPUTS

 error code if error or zero 

SEE ALSO


[Functions] /update_display

[top]

SUMMARY

 Show change in dispay 

USAGE

 update_display 

FUNCTION

 Display Refresh 

INPUTS

 none 

OUTPUTS

 none 

SEE ALSO

 

7. Appendix A

 

FILE FORMATS

 

(1) One dimensional spectrum

The format is assumed to follow Bruker conventions, for the proc, procs, 1rr files. The file open command expects the name of the directory containing these files (ex: datname/1/pdata/1). The ID type is 1.

 

(2) Contour Maps

A contour map is stored in a binary file and consists of sets of co-ordinates describing lines. Thus 4 real numbers will correspond to a 2 dimensional line, and 6 real numbers to a 3 D line. The ID type is 2.

 

(3) Two dimensional spectrum, in Bruker Format

The format is assumed to follow Bruker conventions, for the proc2, proc2s, 2rr and level files. The file open command expects the name of the directory containing these files (ex: datname/1/pdata/1). The ID type is 10.

 

(4) Molecule

The molecule format is assumed to follow PDB conventions. The occupancy field is assumed to contain chemical shifts in ppm. The ID type is 4

 

(5) Drawing Layers

A drawing layer is stored in an ASCII file, each line describing an object. The ID type is 5. The object types are coded like:

 

TYPE CODE

a simple line 1

a rectangle 2

a circle 3

a dashed line 4

another dashed line 5

a filled rectangle 7

a filled circle 8

The format : (4f8.3, 6i5,a)

The meaning: x starting position |

y starting position | line co-ordinates

x ending position |

y ending position |

red code |

green code | colour

blue code |

line width

type of the object

group number (0 = no group)

text label (a string)

 

Optional : If groups are defined then the names of each group is found at

the end of the file after the key word GROUPS.

 

(6) Text File

This is an ASCII file without format. However, key words defined in section 5. ´´Spin System Edition'' must be used if the user wants to use the "spin connect"  and "spin sequence" commands. The ID type is 6.

 

An example is provided in the tutorial directory with the name "example.spin".

 

(7) Ppm and Contact files used in the label utility program

 

EXAMPLES

 

ppm1 file contains the list of shifts from residue 1 to n

 

10.0

 

12.0

 

9.0

 

10.0

 

12.0

 

etc....

 

ppm2 file contains the list of shifts from residue 1 to n

 

9.0

 

8.0

 

10.0

 

12.0

 

etc...

 

contacts file contains residues numbers : e.g. res1, res2 (separated by a

comma ",")

 

1 , 2

 

2 , 3

 

3 , 4

 

4 , 5

 

etc...

 

Starting the program with

 

> labels -ix ppm1 -iy ppm2 -co contacts -l label -o output

 

will create a file named "output" which contains lines (in this example

sequential connectivities).

 

at co-ordinates 10.0/8.0

 

12.0/10.0

 

9.0/12.0

 

labelled with the word "label"

 

(8) Region file used in extract_contour utility program

 

The next line defines a region centred at 6/5 ppm.

 

(x direction fields) (y direction fields)

 

6.0 , 0.5 , 10.0 , 5.0 , 10.0 , 0.0

 

ppm +/-large shift ppm +/-large shift

 

The extract_contour utility will create a subset of the initial contour file

spanning the region 6.5,5.5ppm/15.0,-5.0ppm; The output contour file will be

shifted by 10.0 ppm in the x direction.

 

______________________________________________________________________