Macros
NUTS has the capability of executing a series of commands contained in a text file. The macro is executed from the File menu or using the keyboard command RU. Several sample macros are available. Note that these sample macros require that NUTS be operating in the 2-letter command mode. The newer command mode, which allows use of commands longer than 2 letters, requires that each command be terminated with <ENTER>. Commas must be inserted following each command, which NUTS will interpret as an <ENTER>.
The text file can be created in the Windows Notepad or any word processor and saved as an ASCII file. To execute a macro, type RU or choose Run Macro from the file menu. For convenience, the macros can be mapped to Control-Fx keyboard keys. The assignments are made in the Nuts.ini file. A macro can also be executed automatically when Nuts is started. The macro to be run is set in the Nuts.ini file, with a line such as
AutoExecMacro = C:\NUTS\MAC\GET_EB.MAC
The first line of a NUTS macro must be
NUTSMacro
A line can be any valid NUTS command or command string, the same as those used in Links. NUTS will ignore blank lines or any line which starts with a space or semicolon. The last line of the macro should be END.
NUTS looks at the first word on each line of a macro and expects to find either a valid NUTS command or SET, ASK, DO, LOOP, IF (new as of 4/05), GOTO (new as of 4/05), CALL or QUESTION, as described below.
Set is used to set the value of some parameter. The format of the Set command is
Set parameter [value]
Some parameters require a value to be specified; others do not. For a list of valid parameters, see below.
Ask is used to request user input. The format of the Ask command is:
Ask parameter where "parameter" can have one of the following values:
FileA, FileB, FileC, FileImport, ExportFile, Shift, SL, LB, GF, T1, T2 and S#
When a value for SL (2D slice number) is entered with the Ask
operation, the slice will be read with the next GA command, not immediately.
When a value is entered for Shift, the shift value is not set until a PR command is executed. PR sets the largest peak in the
displayed region to the value which the user has previously entered.
Do is used to perform an action. The following are valid uses of Do in a macro:
Do DeleteFile filename This deletes a file with name "filename". Wildcards are allowed on the Windows versions but only a single name is allowed on the Macintosh versions. Note that NUTS does not ask for confirmation, so use with caution!
Do Extract_PPM f1 f2 This is used to perform an extraction of a spectral region defined by f1 and f2 (in ppm). This is similar to the XT command.
Do Sleep This command causes the macro to pause. The amount of time must first be specified with Set Sleeptime x, where x is time msec.
Do increment_lf_get_filename Increments file extension for file used by LF routine to open an existing file.
Do increment_lf_write_filename Increments file extension for file used by LF routine to write a file.
Do increment_export_filename Increments file extension for file used by export commands
Do Math -- performs Math functions. There are numerous commands which perform automated calculations. These are described in the Math section.
Loop is used to execute several lines in a macro a certain number of times. The format is
Loop x y where x is how many times the loop is executed, and y is how many macro lines comprise the loop
IF is used to allow the macro to do a conditional branch based on the value of a specified parameter. At the moment (4/7/05), the only parameters that can be used with IF are solvent and nucleus.
An IF statement can be used to either execute or skip the line immediately following. In the macro below, the first few lines place the solvent name (text string) into a text buffer called "strcmp". The IF statement tests whether strcmp is equal to "cdcl3". If it is, the macro executes the line after the IF statement (sets the tallest peak to 0 ppm). Otherwise, that line is skipped. Note that this operation is case sensitive!
NUTSMACRO
2f
solvent,
2n,
if strcmp cdcl3
SZ
end
Currently, the only other use of IF is for nucleus, as shown here. The first 3 lines put the current nucleus name into the text string buffer. In this example, if the nucleus is 13C, the linebroadening is set to 2 Hz.
NUTSMACRO
2f
nucleus,
2n,
if strcmp 13C
set LB 2
end
GOTO can be used to jump to a specific line in a macro. The destination of a GOTO may be either before or after the GOTO. The label must begin with a colon (:). For example, in the macro below, the FT command is skipped.
NUTSMACRO
; the program will jump to the ":theend" label
; and bypass the ft command
goto theend
ft
:theend
end
Call is used to launch an external program. NUTS calls a .pif file, which must be "windowed" (no window will be shown). When specifying the path for the .pif file, all backslashes must be doubled. This is available on in the Windows version of NUTS. Example:
call c:\\copyfile.pif
Question – It is possible to have a macro pause during
execution to display a question and wait for user response.
Each question needs to start with one line which is "QUESTION". The following lines are for the question - up to 15 lines
- then four addition lines
First line starts with YES_BUTTON <desired action>
Next line starts with NO_BUTTON <desired action>
Next line starts with CANCEL_BUTTON <desired action>
4th and LAST line needs to be END_QUESTION
<desired action> can be one of three things
1. ABORT
2. CONTINUE
3. New macro name to start
Sample macro:
nutsmacro
QUESTION
Click YES to continue the macro execution with the next line after this question.
Click NO to abort the macro execution.
Click CANCEL to abort the macro execution.
YES_BUTTON CONTINUE
NO_BUTTON ABORT
CANCEL_BUTTON ABORT
END_QUESTION
ft
end
Control characters in Links and Macros are input using the ^ character (shift-6). For example, ^I (to represent Ctrl-I) can be used to toggle integrals on and off.
^M is used to execute a carriage return, as is needed to exit a subroutine.
Sample macros are supplied which can be used as a starting point for creating customized macros. When writing a new macro, it is advisable to test each new part (by commenting out parts not needing testing) to be sure it does what the user expects. The display is not updated during macro execution (to save time), so it is not possible to see the results of each step (although commands are echoed on the command line); hence the recommendation for testing.
Some of the sample macros perform operations which result in files being written at intermediate stages. The macro sets default names for these files so the user does not need to enter them. Any such macro will overwrite those files the next time it is run, so files which the user wishes to save must be renamed before the macro is run again.
Adhering to two rules in writing macros will help avoid problems:
1. Always follow "Ask FileA" (or "Ask FileB") with a line consisting of "GA" (or "GB"). See explanation below.
2. When using GA (or GB) in a Link where File A (or File B) is a 2D file, always precede the Link with a line consisting of "Set SL 1". The obvious reason for this is to be sure the slice pointer is set to the beginning of the 2D file. See complete explanation below.
Sample macros are included with NUTS and are in a subdirectory of the NUTS directory called mac.
Rule 1:
When using the Set command to specify a file name, the default path name is the current working directory. The current working directory is established each time a GA or GB command is completed. Therefore, executing a GA after an Ask FileA command:
Ask FileA
GA
establishes the working directory, and subsequent Set File commands will use that directory.
If the user wants to specify a different path for a file in a Set command, use
Set FullFileA name
Note that if a new path is specified for file A or B, the working directory will be changed when a GA or GB command is next executed.
Rule 2:
The user needs to be aware that the command GA (open file A) when applied to a 2D file behaves slightly differently in macros or Links from when it is entered directly. The difference lies in whether NUTS reads just a slice of the 2D data or reads both the slice and the data header. While in a Link (either by itself or within a macro), NUTS reads the data header only once, for the first slice. This makes reading subsequent slices faster. When GA is used to read a 2D file in a Link, NUTS assumes that the user loaded the first slice manually (with GA) immediately before executing the Link. This reads in the file header and all is well. If the same Link is embedded in a macro, NUTS can be forced to read the file header by inserting the following line just before the line containing the Link:
Set SL 1
This command allows batch processing of an entire directory of NMR data files. This only makes sense if used in a macro, such as the following:
NUTSMacro batch processing ff ft sa in end
When the macro is executed, NUTS will ask for a file to open. By selecting a file, the user defines the directory whose data is to be processed in batch mode. NUTS will attempt to identify and open each file in that directory. If a file is encountered that cannot be opened, NUTS will display an error message, then continue. The processed data is saved into a subdirectory of the chosen directory called _Target.
Some spectrometer software (eg, Varian) does not save data as a single file, but as a directory which contains several files. The FF command will open each subdirectory of the selected directory and look for identifiable NMR data files, and will import any it finds. This does not work with Bruker XWin data, because the fid file is 2 directory layers down.
The FF command can run into initialization/de-initialization problems if it does not complete its operation of opening every file in the directory. A FF command line argument (reset) can be used to force the FindFile status to be de-initialized.
Parameters which can be set in macros with the SET command.
File names:
FILEA File A; current working directory will be used; See note below
FILEB File B; current working directory will be used; See note below
FILEC File C; current working directory will be used; See note below (File C is used for 2D processing)
ExportFile Name of file to be exported by E1, E2, E3, E4 or E5 command.
FILEIMPORT To set the file name of data to be imported
FULLFILEIMPORT To specify a complete path name for data to be imported
FULLFILEA To specify a complete path for File A; See note below
FULLFILEB To specify a complete path for File B; See note below
FULLFILEC To specify a complete path for File C; See note below
LF_GET_FILENAME To specify filename used by LF routine to read an existing Lines file
LF_WRITE_FILENAME To specify filename used by LF routine to write a Lines file
Display:
DC To set the DC (vertical display) offset of the data
DISPLAYALL Display both real and imaginary points
DISPLAYFULL Display real points
DISPLAYIMAG Display imaginary points
DISPLAYZOOM Expand spectrum to previously set frequency limits
Fonts:
FONT_AXIS +10 To change the font size of the clipboard displayed on screen (in this case, by one point)
FONT_CLIP +10 To change the font size of the clipboard displayed on screen (in this case, by one point)
FONT_PEAK_HORIZONTAL +10 To change the font size of the horizontal peak labels (in this case, by one point)
FONT_PEAK_VERTICAL +10 To change the font size of the vertical peak labels (in this case, by one point)
FONT_INTEGRAL_HORIZONTAL +10 To change the font size of the vertical peak labels (in this case, by one point)
FONT_INTEGRAL_VERTICAL +10 To change the font size of the vertical peak labels (in this case, by one point)
FONT_CmdLine +10 To change the font size of the screen's command line (in this case, by one point)
Axis:
AXISHZ Set axis units to Hz
AXISNONE No axis label
AXISPPM Set axis units to PPM
AXISPT Set axis units to points
Zoom limits:
ZOF1PT Set left hand frequency limit in units of points for Zoom region
ZOF2PT Set right hand frequency limit in units of points for Zoom region
ZOF1PPM Set left hand frequency limit in units of ppm for Zoom region
ZOF2PPM Set right hand frequency limit in units of ppm for Zoom region
ZOF1HZ Set left hand frequency limit in units of Hz for Zoom region
ZOF2HZ Set right hand frequency limit in units of Hz for Zoom region
ZOF1SL Set lower slice limit in second dimension for 2D Zoom region
ZOF2SL Set upper slice limit in second dimension for 2D Zoom region
ZOF12DPPM Set bottom frequency limit in ppm in second dimension for 2D Zoom region
ZOF22DPPM Set top frequency limit in ppm in second dimension for 2D Zoom region
ZOF12DHZ Set bottom frequency limit in Hz in second dimension for 2D Zoom region
ZOF22DHz Set top frequency limit in Hz in second dimension for 2D Zoom region
ZOOM_REGION Allows the user to define up to 10 Zoom regions, similar to Zoom sub-commands 0-9. Syntax is
Set Zoom_Region n f1 f2
where n is the region identifier (0-9) and f1 and f2 are frequency limits in ppm.
Window functions:
GF Gaussian Factor used in Lorentzian/Gaussian resolution enhancement.
LB Linebroadening used with EM, GM, LG and TF commands
S# Set phase shift for sine apodization (MS).
T1 First point for trapezoidal multiplication (TM)
T2 Second point for trapezoidal multiplication (TM)
Linear Prediction:
LNpts Number of points to be predicted by Linear Prediction (LN)
LNmdim Number of points on which Linear Prediction (LN) is based
LNnsig Maximum number of frequencies to be predicted by Linear Prediction (LN)
LNdirection (FORWARD or BACKWARD) used by Linear Prediction (LN)
Integration:
INTEGRAL CLEAR clear all defined integral regions
INTEGRAL 3.0 5.0 to define an integral region (in this case, from 3 to 5)
INTEGRAL 4.2 1.5 5.0 to define and integral (in this case from 4.2 to 1.5) and also assign its value (5, in this case)
Other:
AC Set value for Amplitude Change (AC) command.
AM Set value for Add/Subtract multiplier (AM) command.
ARRAY_ON Enter Arrayed Mode for 2D (original arrayed mode only, does not initiate "pairwise" arrayed mode)
ARRAY_PAIRWISECOMPLEX Enter "pairwise" arrayed mode. Be sure to set the Process Type before executing this command.
ARRAY_OFF Exit Arrayed Mode for 2D
DP_INFO_STRING Enter text which will be entered in the Label field for all peaks when DP is executed.
LINKLIMIT To specify the number of loops for a Link containing IN. The default is to loop until no more files can be found.
MH Minimum height for peak picking
OF1 Sets the o1 frequency (the frequency of the center of the spectrum) to the specified value, in hertz.
OF2 Sets the o2 frequency (the frequency of the center of the spectrum in the second dimension) to the specified value, in hertz.
PA Zero-order phase correction used with PC
PB First-order phase correction used with PC
POINTS_TO_AVERAGE Sets the number of points to be used with baseline correction commands BF and FR. This is the same as the 2A command.
RDpts n where n is the number of pts to rotate with RD command
RDdirection left (or right) used by RD command
RM RMS noise multiplier used in peak picking
S@ Number of points by which SH will reduce the data set
SHIFT 2.5 To set the chemical shift of the largest peak in the current region (in this case, to 2.5 ppm). If a second value is supplied, separated by a space, this command can be used to set the shift in both dimensions at the same time. The values specified must be in ppm.
SL sets 2D slice number
Sleeptime x Sets the number of milliseconds that the macro will pause when Do Sleep is used.
SPPLOTX Sets x offset for an SP plot.
SPPLOTY Sets y offset for an SP plot.
When using the Set command to specify a file name, the default path name is the current working directory. The current working directory is established each time a GA or GB command is completed. Therefore, it is a good practice to execute a GA after an Ask FileA command:
Ask FileA
GA
This establishes the working directory, and subsequent Set FileX commands will use that directory.
If the user wants to specify a different path for a file in a Set command, use
Set FullFileA name
Note that if a new path is specified for file A or B, the working directory will be changed when a GA or GB command is next executed.
Last updated 4/20/05.