NAME irDraw - Graphics Interface for Spectral Imaging SYNOPSIS irDraw [-in inName] [-dir dirName] [-file fileExp] [-name defName] [-text textDir] [-read] [-cellX xPix] [-cellY yPix] [-type1 small | medium | large] [-type2 small | medium | large] [-square] [-track] [-scroll] [-repaint] [-norepaint] [-frp repaintCount] [-dbg] [-verb] [-draw] [-clear] [-frzLevels Always | Sometimes | Never] [-frzZoom Always | Sometimes | Never] [-autoScale] [-grid] [-pix] [-image] [-peak] [-vert] [-zero] [-cursor]] [-relative] [-compress] [-iz zPlane] [-ia aPlane] [-func fnTab] [-proc scriptName] [-nosys] [-zfht] [-mult contFactor] [-plev numLevels] [-nlev numLevels]] [-hi firstHeight] [-plot 1 | 2 | 3] [-pcc numColors] [-pHue1 hue] [-pHue2 hue] [-pSat1 saturation] [-pSat2 saturation] [-pVal1 value] [-pVal2 value] [-ncc numColors] [-nHue1 hue] [-nHue2 hue]] [-nSat1 saturation] [-nSat2 saturation] [-nVal1 value] [-nVal2 value] [-XOR Always | Sometimes | Never] [-virt Always | Sometimes | Never] [-virtOff offset] [-labMode Normal | XOR | Overlay] [-svri] [-colors clrList] [-color0 zeroClr] [-color1 1dClr] [-colorC cClr] [-colorG gridClr] [-colorX xClr]] [-colorY yClr] [-colorZ zClr] [-colorA aClr] [-colorL lClr] [-colorE eClr]] [xviewFlags] SPECIAL NOTE This manual page is under development. DESCRIPTION irDraw is a User-oriented X11 graphical interface for inspecting and processing multidimensional data. It works in conjunction with the nmrPipe program for spectral pro- cessing via UNIX pipes. Display of 2D Planes from either processed or unpro- cessed multidimensional data, including interactive and User-specified 2D Zoom, adjustable color schemes, and viewing of the next 2D plane in a series by a single mouse click. Real-time display of one or more 1D slices superimposed over 2D spectral graphics, with interactive adjustment of zoom region, vertical scale, and vertical offset. Interactive processing of 1D slices from any dimension of a spectrum, as well as automatic processing according to pre-defined schemes. Real-time phase correction of one or more 1D slices simultaneously, with coarse and fine phase adjustment, interactive pivot point selection, and automatic reconstruction of imaginary data when needed. An nmrPipe shell-script editor, for creating, saving, and executing multidimensional conversion and processing schemes. Interactive adjustment of chemical shift calibration. Color and monochrome PostScript hard copy plot genera- tion. Other extraction, display, and analysis facilities, includ- ing projections, graphics overlays from one or more spectra, and automated/interactive peak picking, are included or under development. A TYPICAL SESSION WITH IRDRAW There are many possible scenarios for a session with irDraw; a typical session for processing and inspecting a 3D spec- trum might include the following steps: Use the irDraw Macro Edit facility to create, save, and execute a UNIX shell-script which converts an unpro- cessed spectrometer format data file to an nmrPipe for- mat data file. Read and display the converted, unprocessed data file; inspect the raw data to see whether it was acquired and converted successfully. Interactively process a 1D slice from the data file; determine phase correction values and other processing parameters. Create, save and execute a UNIX shell-script to process the first 2D plane from the data, using the interac- tively determined processing parameters. Read and display the processed plane; evaluate the need for any additional processing, such as baseline correc- tion. Create, save, and execute a UNIX shell-script to process the entire 3D spectrum, incorporating the previous 2D scheme. Read and display 2D planes, 1D slices, etc. from the processed 3D spectrum. APPEARANCE OF IRDRAW irDraw has several components, which provide for informa- tional text, command entry, and spectral display. The appearance and behavior of irDraw can be changed by command-line arguments and by other graphics parameters, especially the configuration parameters of the graphics environment (window manager) being used. The usual behavior of irDraw is described here: By default, the irDraw window takes up the entire screen. The window border at the top edge of the screen describes the current functions of the mouse buttons, if any. It is also sometimes used to display information about the current data. The command panel, which extends across the top of the irDraw window, contains pull-down menu buttons for com- mand entry, numerical fields for specifying spectral locations and display parameters, and slider bars for adjusting phase correction values interactively. The command panel usually has a gray background. The canvas takes up the remaining portion of the irDraw window; it has a purple background by default. The can- vas contains a rectangular spectral graphics area, where displays such as contour plots will be drawn. By default, this graphics area has a black background. Many facilities of irDraw make use of the mouse; in these cases, the mouse buttons will perform one set of actions while the mouse pointer is inside the spectral graphics area, and a different set of actions when the mouse pointer is to the left or below the graphics area, in the purple borders. As mentioned above, the mouse button functions will be displayed the the topmost border of the irDraw window. In addition to irDraw's primary window, one or more pop-up windows may appear during a session. These win- dows are used for special-purpose command entry, such as selection of the current data file. More than one pop-up may appear on the screen at a given time. As with irDraw's primary window, the top border of a pop-up will often display useful information. Most pop-ups have a Done Button, which should be used to close the pop-up and remove it from the screen. Note that if you remove a pop-up by other means, such as via window manager commands, you may not be able to use the pop-up again during the session. IRDRAW AND YOUR WINDOW MANAGER As noted before, some functions of irDraw are under the con- trol of the window manager, the program which coordinates the display of multiple windows on the screen. The window manager controls the behavior of the keyboard, mouse but- tons, and window borders. It also controls default placement of windows on the screen, and the details of mov- ing, re-sizing, iconifying and restoring windows. So, you may wish to investigate or adjust the details of your own window environment in order to make the best use of irDraw. The current version of irDraw has been developed with the XView Toolkit V2.0, for use with X11R4. It has been used most extensively with the twm and OpenLook window managers. In these cases, the following aspects of the window environ- ment seem to have the strongest influence on the behavior and appearance of irDraw: Which mouse button is used to view pull-down menus, and which is used to select a command. Whether pop-up windows are placed automatically or by hand. Whether graphics drawn in overlapping or iconified win- dows is discarded or maintained. The colors and fonts used for window borders, etc. RUNNING AND EXITING IRDRAW In the usual installation, the irDraw program can be run by typing the command: irDraw This command executes the UNIX shell-script file called irDraw, which in turn runs the program itself, which is called nmrdraw. You can customize many aspects of irDraw by editing a version of the irDraw shell-script, to change the various arguments used to invoke the program. You can also include arguments directly on the irDraw command-line. For instance, as a short-cut, you can specify the default data directory or data name: irDraw -dir ft -name test%03d.ft3 In order to exit the irDraw program, you can select the Quit irDraw command from the irDraw File Menu. You can also exit the program by moving the mouse pointer into the spectral graphics area and typing the character Q (upper-case Q) at the keyboard. ENTERING COMMANDS IN IRDRAW irDraw is operated by a combination of commands entered via the mouse and keyboard. Many commands and parameters are selected by using the mouse with graphical items on the screen; the general nature of some common graphical items is described in more detail below. The primary commands are selected via Menu Buttons in the command panel. For instance, the command to draw a contour plot on the screen is listed under the Draw pop-up menu as "d) Contours", and can be selected via the mouse. As an alternative, the command can be selected from the keyboard without the need to use the mouse. In this case, the com- mand can be selected by typing d (lower-case d), as indi- cated at the beginning of the Command Text. You can only type commands from the keyboard if the keyboard focus is set to the spectral graphics area. This generally means that the mouse pointer will have to be positioned inside the graphics area before commands are entered. The outer edge of the graphics area will usually be hilighted to indicate that commands can be entered. You can restore key- board focus at any time by moving the mouse pointer out of, then back in to, the graphics area. SOME GRAPHICAL COMMAND ITEMS Buttons Buttons are graphical items intended to resemble actual push-buttons with rounded edges. They are used to display a single command or command choice. To select a Button's command, point to the Button with the mouse, and click the left mouse-button. Example: most pop-up windows have a Done Button, which can be used to close the pop-up and remove it from the screen. Menu Buttons Menu Buttons are special Buttons which cause a pop-up menu of additional options to be displayed. Menu But- tons look like ordinary Buttons, but they also include a triangular caret symbol after the button text; this caret signifies that there is a menu associated with the button. To view the pop-up menu associated with a Menu Button, press and hold the right mouse-button; the menu will appear, and will stay on the screen as long as the mouse-button is held. Command options in the pop-up menu can be selected by dragging the mouse to highlight the desired option, then releasing the mouse. The first command entry in any given menu is called the default command. The menus are often arranged so this default command is a commonly used one. As a short-cut, it is possible to select this default com- mand without the need to pop-up the menu. To do this, use the left mouse-button (to select the default command) rather than the right mouse-button (used to make the pop-up menu appear). In this respect, Menu Buttons behave like ordinary Buttons, since the left mouse-button is used in both cases to select the Button's command. Example: the irDraw Command Panel includes Menu Buttons marked File, Draw, and Mouse. The default commands for these menus are the often-used options to read a file, draw a contour plot, and view 1D slices. Character Text Item Character Text Items are one-line regions on the screen used for entering text information such as a file name from the keyboard. Text Items have a label on the left-hand side, followed by a horizontal line where text typed from the keyboard will be entered. In order to enter text into a Text Item, point to the item with the mouse and click the left mouse-button before typing from the keyboard. In some cases, entering a carriage return at the end of the input line will cause irDraw to perform some action related to the input text. Example: the Select File pop-up window includes Text Items which are used to specify the current data file and directory; these text items are labeled "File:" and "Directory:". Typing a file name in the "File:" field followed by a carriage return will cause irDraw to read the specified file. Floating-Point Text Item Floating-Point Text Items look the same as character text items, but they are used specifically to enter floating-point numbers. They will have a floating-point number as a default value. Example: the command panel includes floating-point text items labeled "P0:" and "P1:"; these are used to display or change the current phase correction values. Integer Text Item Integer Text Items look the same as character text items, but they also include a pair of square caret buttons to the right of the one-line text field. As the name implies, the integer text item is used for entering an integer value; the caret buttons can be used to increment or decrement the current integer value. Example: the command panel includes integer text fields labeled "X:", "Y:", "Z:", and "A:", used for displaying or setting the point locations of 1D and 2D data being displayed. Slider Bar Slider bars are used for interactive specification of some continuous value, for instance zero or first order phase. Slider bars have the appearance of a rectangu- lar button in a vertical or horizontal groove. The value associated with a Slider can be adjusted by pointing to the Slider's Button with the mouse, then dragging the mouse with the left mouse-button pressed. In addition, you can increment or decrement the slider value by clicking left mouse-button while pointing to either end of the Slider bar groove. Example: the command panel includes a pair of slider bars marked "P0:" for coarse and fine zero-order phase, and a second pair of slider bars marked "P1:" for first order phase. Edit Window An Edit Window is a rectangular region used for displaying or editing lines of text. You can enter text at a particular position in the window by first pointing to that position with the mouse and clicking the left mouse-button, then typing text at the key- board. In addition, pressing and holding the right mouse-button in an Edit Window will create a pop-up menu of text editing options, which allow you to read or save text files, cut and paste text selections, and so on. Example: the command Macro Edit in the File Menu will create a pop-up which includes a light-blue Edit Win- dow, used for creating UNIX shell-scripts that do spec- tral processing. THE COMMAND PANEL The command panel contains several graphical items for adjusting commonly-used parameters. An outline of the func- tions of these items follows: X: Use this to increment, decrement, or select a particu- lar 1D slice when viewing 1D slices from the X-Axis of the current data. Y: Use this to increment, decrement, or select a particu- lar 1D slice when viewing 1D slices from the Y-Axis of the current data. Z: Use this to increment, decrement, or select a particu- lar Z-Axis plane. Under default settings, the plane will be automatically read and drawn with the previous zoom region and contour settings. This option requires selection of data as a 3D or 4D template. A: Use this to increment, decrement, or select a particu- lar A-Axis coordinate. Under default settings, a new plane will be automatically read and drawn with the previous zoom region and contour settings. This option requires selection of data as 4D template. Plus: Use this to change the number of positive contour lev- els to use the next time the data is drawn. Minus: Use this to change the number of negative contour lev- els to use the next time the data is drawn. First: Use this to select the height of the first contour used the next time the data is drawn. Negative contours will begin at the negative of this height. Factor: Use this to select the spacing factor between adjacent contours used the next time the data is drawn. (+) Use this button to increment the first contour height used the next time the data is drawn. (-) Use this button to decrement the first contour height used the next time the data is drawn. P0: (Sliders) These sliders control the coarse and fine zero-order phase applied at the selected pivot point of the current 1D spectra. These sliders will only work if a 1D slice is selected, and the Phasing Toggle button is ON. P1: (Sliders) These sliders control the coarse and fine first-order phase correction. These sliders will only work if a 1D slice is selected, and the Phasing Toggle button is ON. P0: (Text) Displays or changes the current P0 phase value; this value can be used directly with nmrPipe regardless of the pivot setting. P1: (Text) Displays or changes the current P1 phase value; this value can be used directly with nmrPipe regardless of the pivot setting. Pivot: Displays or changes the position of the phasing pivot. The pivot position can also be selected via the mouse when viewing 1D slices. Phasing Toggle This toggle button must be set to ON in order to apply phasing to the current 1D data. But, once the toggle is turned ON, the current 1D spectra will not be rephased until a slider or phase value is adjusted. THE FILE MENU The File Menu includes commands to select the spectral data of interest, as well as commands to read or re-read the selected data. It also includes commands for creating and modifying other kinds of files, such as UNIX shell-scripts. Importantly, the File Menu includes the command used to Exit from irDraw. Read This command reads a 2D file plane into irDraw's data memory; depending on the 2D Settings, a 2D plot of the plane may be drawn automatically once the data is read. The name of the data to read is specified by the Select File command in the File Menu; 1D and 2D data sets are selected according to their file names, while 3D and 4D data are selected according to their template names. In the case of 3D and 4D data, the Z-Axis and A-Axis loca- tions for the plane to read are taken from the Z: and A: fields in the command panel. Select File This command is used to specify the file or template name of the spectral data to read. Select 1D and 2D data according to their file names. Select 3D and 4D data according to their template names. Read Only This command is similar to the Read command in the File Menu, however it will not cause any graphics to be drawn regardless of other settings. Use this command if you would like to adjust the display parameters before a plot is drawn. Previous Data This command will read the previous data file. It is commonly used to switch between orthogonal planes of a 3D dataset, as created by commands in the 1D Menu. Parameters This command displays the file parameters of the current spectral data. The parameter listing is gen- erated by the program showhdr;, it is displayed in the Info Window, which will pop up automatically. Calibrate PPM Provides a pop-up to re-calibrate the chemical shifts of any axis in the current data: 1. Change the axis selection, axis label, or any other parameter which needs to be adjusted. 3. Enter the PPM value for the selected point; the default point will be set according to the positions of the last 1D slices being viewed. 4. Use the "Apply" button to re-calculate the chemi- cal shifts according to the new parameters. 5. Use the "Save" button to write the new calibra- tion data. Macro Edit This command is used to create and execute UNIX shell-scripts for spectral processing. It provides a point-and-click text editor augmented with a series of predefined conversion and processing scripts. It also allows edited scripts to be saved on the disk and exe- cuted. Note that this command could use much more documentation here. Hard Copy Plot This command creates simple PostScript plots of the current data, and optionally sends the plots to a printer queue. The plots are generated according to the current display settings such as first contour height, number of contour levels, etc. Info Window This command pops up the Info Window, a text editing window used for displaying information such as file parameters. Quit irDraw This command exits the irDraw program; no confirmation to exit is requested. THE DRAW MENU Contours Draws a 2D contour plot of the current data on the screen, using the current contour settings. PixMap Draws a 2D pixmap of the current data on the screen, using the current contour settings. It is used as the default mode for drawing mixed time-frequency mode planes. Dot Plot Draws a 2D dotplot of the current data. The dotplot is a display which shows intensity as a varying density of dots. It is used as the default mode for drawing time-domain data planes. Clear Graphics Erases the spectrum in the graphics area. Erase Screen Erases the entire screen, both inside and outside the graphics area. 2D Full Restores the full view of the current data plane. 2D Toggle Toggles the 2D display on or off by changing the color- map. 2D Colors Provides a pop-up for adjusting the range of colors used to display positive and negative data. Estimate Noise Estimates the standard deviation of the spectral noise, and resets the first contour height accordingly. Note that the estimate may be crude. 2D Limits Provides a pop-up for selecting a data region in spec- tral units such as PPM. 2D Settings Provides a pop-up for selecting various 2D drawing pro- perties, such as whether or not to use grid lines. THE MOUSE MENU The Mouse Menu provides a list of functions that are per- formed interactively with the mouse, such as extracting and drawing 1D slices from the current data. Whenever the mouse is active, the topmost border of irDraw will report the functions of the mouse buttons. The buttons perform dif- ferent actions depending on whether the mouse pointer is inside the spectral graphics region, or outside in the pur- ple borders. When a given slice is extracted with one of the Mouse Menu commands, several other commands can be used on it: It can be kept on the screen with other 1D slices using the Append 1D command in the 1D Menu. It can be phase corrected interactively using the tools in the command panel. It can be processed or inverse-processed using NMRPipe Command or Auto-Process 1D in the Proc Menu 1D Horizontal Real-time extraction of 1D slices from the horizon- tal axis of the current display. Mouse functions allow real-time vertical offset and scale adjust- ment, and graphical selection of phase pivot. 1D Vertical Real-time extraction of 1D slices from the vertical axis of the current display. Mouse functions allow real-time vertical offset and scale adjustment, and graphical selection of phase pivot. 1D Both Real-time extraction of 1D slices from both the hor- izontal and vertical axis of the current display at the same time. Mouse functions allow real-time vertical offset and scale adjustment, and graphical selection of phase pivot. 1D Z-Axis Extraction of individual 1D slices from along the Z-Axis of the current display. This requires that a 3D or 4D data template is selected. 1D A-Axis Extraction of individual 1D slices from along the Z-Axis of the current display. This requires that a 4D data template is selected. 2D Location Real-time display of cursor location and the corresponding data value. Information is displayed in the topmost border of irDraw. 1D Zoom Provides a zoom-box for selecting and expanding a region of the current 1D slice being displayed. 2D Zoom Provides a zoom-box for selecting and expanding a region of the current 2D plane being displayed. Exit Mode Turns off the current mouse function. THE 1D MENU The 1D Menu contains some commands which effect or relate to the 1D data being viewed. Append 1D Appends the current 1D slice to the list of slices which will be kept on the screen. This allows two or more slices to be viewed at the same time. Delete 1D Deletes all the 1D slices being viewed from the screen. 1D Full Restores the full view of the current 1D slice. 1D Toggle Toggles the 1D display on and off. Extract 2D H (3D Data Only) Extracts the orthogonal 2D plane which corresponds to the horizontal 1D slice currently selected. The 2D plane will be extracted as a file called "ext.dat". The File Menu command Previous Data can be used to return to the original 3D data. Extract 2D V (3D Data Only) Extracts the orthogonal 2D plane which corresponds to the vertical 1D slice currently selected. The 2D plane will be extracted as a file called "ext.dat". The File Menu command Previous Data can be used to return to the original 3D data. Axis Toggle Toggles the 1D axis display on and off. 1D Settings Provides a pop-up which adjusts the properties of 1D displays, including whether the zero-level is displayed. THE PROC MENU The Proc Menu provides two ways to process the current 1D slice, as explained here: NMRPipe Command Provides a pop-up window for executing individual nmrPipe processing functions on the current 1D slice. To perform processing, enter the name of an nmrPipe function on the given command line, along with any additional arguments; For instance, "ft -inv" would be the command for inverse Fourier transform. As an alter- native to typing the function and arguments, a small menu of common functions is provided. Once the func- tion is entered, execute the processing by typing a carriage return, or by clicking the Execute button. Auto-Process 1D This command will execute a pre-defined macro which is responsible for processing the current 1D slice. The macro used is specified by the command-line argument -proc in the irDraw script. The default version of the macro will apply a window, zero fill, and FT to time-domain data; if the axis name is "HN", a solvent filter and extraction of an amide chemical shift range will also be applied. In the case of frequency-domain data, inverse process- ing will be applied, automatically restoring the current 1D slice it to its original time-domain form as best as possible. FILE OPTIONS -in inName Sets the default Input Name, and reads the data on start-up. -dir dirName Default input directory. -file fileExp Expressions for directory list filter provided in the File/Select File pop-up menu. -name defName Sets the default Input Name, but does not read data on start-up. -text textDir Specifies the Help Text Directory. -read Toggles Auto-Read of data on startup. GENERAL OPTIONS -cellX xPix Specifies the estimated character cell cidth in pixels; this value is used to adjust the placement of graphics and text on the screen. -cellY yPix Specifies the estimated character cell height in pix- els; this value is used to adjust the placement of graphics and text on the screen. -type1 size General specification for the irDraw ordinary font; use key- words "small", "medium", "large", or "extraLarge". -type2 size General specification for the irDraw large font; use keywords "small", "medium", "large", or "extraLarge". -square Make the spectral graphics area square. -track When a mouse mode is turned on, the default 1D location tracks the mouse. -scroll Use Scrollable Panel. -repaint Force Manual Repaint Mode; use this mode when the computer's X11 graphics server does not repaint windows automatically. -norepaint Avoid Manual Repaint Mode. -frp First Repaint Count. -dbg Debug Message Level. -verb Toggle Verbose Mode On. 2D DISPLAY OPTIONS -draw Auto-Draw with Read. -clear Auto-Clear when Drawing. -frzLevels Freeze Contour Levels: Always Sometimes Never -frzZoom Freeze 2D Zoom Region: Always Sometimes Never -autoScale Auto-Calc Contour Level. -grid Draw Grid Lines. -pix PixMap Display is Default. -image Image Display Setup. 1D DISPLAY OPTIONS -vert Enable Vertical Plots. -zero Draw 1D Zero Level Line. -cursor Draw 1D Position Cursor. -relative Relative 1D Scaling. -compress 1D Display Compression. COORDINATE OPTIONS -iz Z-Plane Number. -ia A-Plane Number. PROCESSING OPTIONS -func fnTab Function Table Name. -proc script Processing script used for automatic 1D processing. -nosys Suppress system calls. -zfht Enable temporary zero fill with Hilbert transform. CONTOUR LEVEL OPTIONS -mult contFactor Contour Level Factor. -plev numLevels Number of Positive Levels. -nlev numLevels Number of Negative Levels. -hi firstHeight First Contour Height. 2D DRAWING COLOR OPTIONS -plot plotMode Color mode for hard-copy plots; these will be selected from inside the program in future versions: 1 = Black and White 2 = Gray Scale (Not supported yet) 3 = Color 2D DRAWING COLOR OPTIONS -pcc numColors Positive Color Count. -pHue1 hue Positive colors, First Hue [0-1]. -pHue2 hue Positive colors, Last Hue [0-1]. -pSat1 saturation Positive colors, First Saturation [0-1]. -pSat2 saturation Positive colors, Last Saturation [0-1]. -pVal1 value Positive colors, First Value [0-1]. -pVal2 value Positive colors, Last Value [0-1]. -ncc numColors Negative Color Count. -nHue1 hue Negative colors, First Hue [0-1]. -nHue2 hue Negative colors, Last Hue [0-1]. -nSat1 saturation Negative colors, First Saturation [0-1]. -nSat2 saturation Negative colors, Last Saturation [0-1]. -nVal1 value Negative colors, First Value [0-1]. -nVal2 value Negative colors, Last Value [0-1]. 1D/2D OVERLAY DRAWING OPTIONS -XOR XOR Drawing Keyword: Always Sometimes Never -svri Server Image Color Palette. -virt Virtual colormap usage keyword: Always Sometimes Never -virtOff Virtual colormap offset. -colors clrList Color Name List. -color0 zeroClr Zero Line Color. -color1 1dClr Active 1D Plot Color. -colorC cClr Cursor Bar Color. -colorG gridClr Grid Line Color. -colorX xClr X-Axis 1D Plot Color. -colorY yClr Y-Axis 1D Plot Color. -colorZ zClr Z-Axis 1D Plot Color. -colorA aClr A-Axis 1D Plot Color. -colorL lClr Label Color. -colorE eClr Background Color. Color Name Options: black red orange yellow green blue violet cyan magenta lightGray dimGray white