925-456-1020 info@acornnmr.com

Macro

Macro

NUTS Help

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:NUTSMACGET_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 (July 2008), 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. The IF statement tests whether that text buffer is equal to "cdcl3". (The keyword "strcmp" is derived from the C programming function to compare text strings.)  If it is, the macro executes the line after the IF statement (sets the tallest peak to 0 ppm in the example below). 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 i
n 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

FF – Find File

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.

SET parameters

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 regi
on

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.

Note:

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.

 

Main Help page

Command Index

 


Last updated: 7/12/08.