Subsections

• Examples of the SEQUENCE Command Usage

  SEQUENCE

The SEQUENCE command is almost certainly the most powerful and also the most complicated command within FIT2D. To cope with its complication much explanation of required input is available by entering a question mark (?) for each prompt. The SEQUENCE command allows a pre-defined macro to be run automatically on a whole series of files with automatic definition of program variables (See Macros Section 19, Page , and the START MACRO command Section 15.108, Page ). The SEQUENCE command can also be used to repeatedly run a macro without changing any file names, but this possibility is largely uninteresting unless an input or output file name is changed.

Often a large number of files exist in some sequence and it is required to perform some operation on the files and produce some output or a similar sequence of outputs. The output may data files, or may be graphics PostScript files. Such a sequence of input files typically looks like:

lys1_001.pmi
lys1_002.pmi
lys1_003.pmi

$\dots$

lys1_178.pmi
lys1_179.pmi
lys1_180.pmi

File sequences of this sort can be treated, but in fact much more flexibility is available:

• The value of the first file does not need to be one
• Steps other than unity are also available
• The number of characters used to store the numerical part of the file name is user controlled
• The number of characters used to store the numerical part of the file name may be variable
• The variable numerical part of the file name may be at the start, middle, or end of the file name
• The file name (variable value) does not have to vary
• Output file names can be very similar to input file names e.g. Only the file extension changes, or the name can be defined very differently e.g. The output files can be output in the reverse numerical order to the input files

The SEQUENCE command allows a macro to be run for each file in the sequence, with control over the variable values e.g. file names, of a variable number of program variables. A loop is run a number of times, controlled by a loop variable, which has a start value, a maximum value, and a step increment value. The value of the loop variable can be used to define the values (translations) of the program variables.

The starting value of the loop counter variable is set and for each loop:

• Program variables are defined, based directly, based indirectly, or independent of the loop value
• A named macro is called, and run with the defined variable values
• The loop counter value is incremented
• If the loop counter value is within the end condition value, the previous operations are repeated

To define the sequence, first the loop counter variable's initial value, end limit value (maximum or minimum inclusive limit value depending on increasing or decreasing counter values), and the increment step value are defined. A valid finite loop must be declared or FIT2D will re-prompt for the input values:

LOOP COUNT START VALUE [1]:
LOOP COUNT END LIMIT VALUE (INCLUSIVE) [10]:3
LOOP COUNT INCREMENT STEP [1]:

The increment step value may be a value other than 1, and may be negative. If the increment step is negative the END LIMIT VALUE must be less than or equal to the START VALUE. The loop will always be run at least once; if you decide that you do not want to continue the SEQUENCE command now or later, enter user escape ($\backslash$$\backslash$).

When the looping conditions are properly defined, FIT2D prompts for the name of the macro file to be run.

INPUT MACRO FILE NAME [fit2d.mac]:

The entered file name is checked to exist and be a valid macro file.

Next the number of automatically controlled program variables and variable values (translations) is defined. Program variables can also have been previously defined using the DEFINE VARIABLE command, but their values (translations) will be static, whereas here they can be defined to change dynamically.

NUMBER OF VARIABLES TO DEFINE (Range: 0 to 20) [2]:

For each such definable program variable FIT2D prompts for the name of the variable, followed by a number of other prompts which allow different values to be defined depending on the loop counter value. e.g.

ENTER VARIABLE NAME [#IN]:
ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:
VARIABLE VALUE BASE [lys1_]:test_
VARIABLE PART FIXED LENGTH [YES]:
NUMBER OF CHARACTERS IN VARIABLE PART (Range: 0 to 20) [3]:2
ARITHMETIC ON LOOP COUNT VALUE [NO]:y
MULTIPLIER FOR LOOP COUNT VALUE [-1.00000]:
CONSTANT TO ADD TO MODIFIED LOOP COUNT VALUE [21.0]:
VARIABLE VALUE EXTENSION [.pmi]:.temp

The ENTER VARIABLE NAME prompt requires names of required variables to be entered. Any string may be entered, but clearly it only makes sense to enter program variables which are used within the macro to be run (See Section 19, Page ). By default the first variable name is # IN and the second is # OUT.

The data type of the variable is defined: ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:. This allows the generated values to be of type INTEGER, FLOATING POINT REAL, or CHARACTER STRING. All file names and other general strings should be defined of type CHARACTER STRING. Numeric values may be floating point or integer. These values are generated directly from the loop counter, or the loop counter multiplied by the multipler and added to the entered constant. Integer values are the nearest rounded integer to the floating point number.

Character string variable values are constructed from a fixed initial component, a numerically based changing middle component, and a fixed end component. The variable value may be up to a total of 256 characters in length. Any of the three parts may be blank, allowing the changing component to be at the beginning or end, and allowing non-changing variable values. To define a component as blank a special program variable exists: ##BLANK²⁹. (##BLANK is a special variable which is defined by FIT2D on start-up.)

For character string variables only, first the base part of the variable values is entered: VARIABLE VALUE BASE [lys1_]:.

VARIABLE PART FIXED LENGTH [YES]: prompts for whether or not the changing part of the variable values should contain a fixed number of characters or a variable number.

If a variable number of characters is selected FIT2D prompts for the number of characters: NUMBER OF CHARACTERS IN VARIABLE PART (Range: 0 to 20) [3]:. Otherwise this prompt does not occur.

If a fixed number of characters is chosen, numbers which take less characters than the input number are padded out with preceding zeros. If at any time during the sequence the number is too big to be represented in the given number of characters, the sequence processing will stop. If a variable number is chosen, only the characters necessary to represent the number will be used.

For all variable types the loop counter value can be used directly or indirectly to define the value or variable part of the variable values. If indirect use is required enter YES to the ARITHMETIC ON LOOP COUNT VALUE [NO]: prompt. The default is NO. Entering YES allows the counter value to be multiplied by an input multiplier and then added with an input addition constant prior to it being used to form the variable value. The constants are input as real values, and real arithmetic is performed.

For floating point real variables:

$$variable\_real\_value = Real(loop\_value) * multiplier + add\_constant$$ (3)

Where: Real converts an integer number to a real number

For integer variables and any numeric part of character string values the result is converted to the nearest integer prior to being used to form part of the variable value. e.g. The integer used is defined:

$$variable\_integer\_value = Nint(Real(loop\_value) * multiplier + add\_constant)$$ (4)

Where: Real converts an integer number to a real number

           Nint converts a real number to the nearest integer

MULTIPLIER FOR LOOP COUNT VALUE [-1.00000]: inputs the multiplier to be used and
CONSTANT TO ADD TO MODIFIED LOOP COUNT VALUE [21.0]: inputs the addition constant.

By using a negative multiplier and defining a suitable addition constant it is easy to define a sequence of program variables which count in the opposite direction to the loop counter value.

For character string variables ony the latter part of the variable value is entered: VARIABLE VALUE EXTENSION [.pmi]:. Note: The required input is not the file name extension, but all the characters following the changing part of the value, including the dot (.).

Note: The SEQUENCE command cannot be used within a macro. Thus, if you have entered the START MACRO command and are in the process of creating a macro, entering the SEQUENCE command will result in a warning message.

Examples of the SEQUENCE Command Usage

For normal use the SEQUENCE command should be relatively straightforward to use, but to exploit the full potential may require some careful thought. In either case some examples are useful.

The following example shows how the macro to correct for spatial distortion defined in Section 30.4, Page  may be used to process a file sequence starting with lys04.gel and ending with lys20.gel. The corresponding output files should have the same name as the input file, but with the extension .dat instead of .gel. The macro file is called lyso.mac and uses two program variables: #IN for the input file and #OUT for the output file. The following is the program output and user input for this sequence definition:

Main menu: ENTER COMMAND [INPUT DATA]:sequence
LOOP COUNT START VALUE [1]:4
LOOP COUNT MAXIMUM VALUE (INCLUSIVE) [10]:20
LOOP COUNT INCREMENT STEP [1]:
INPUT MACRO FILE NAME [fit2d.mac]:lyso.mac
NUMBER OF VARIABLES TO DEFINE (Range: 0 to 20) [2]:
ENTER VARIABLE NAME [#IN]:
ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:s
VARIABLE VALUE BASE [lys1_]:lys
VARIABLE PART FIXED LENGTH [YES]:
NUMBER OF CHARACTERS IN VARIABLE PART (Range: 0 to 20) [3]:2
ARITHMETIC ON LOOP COUNT VALUE [NO]:
VARIABLE VALUE EXTENSION [.pmi]:.gel
ENTER VARIABLE NAME [#OUT]:
ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:s
VARIABLE VALUE BASE [lys]:
VARIABLE PART FIXED LENGTH [YES]:
NUMBER OF CHARACTERS IN VARIABLE PART (Range: 0 to 20) [2]:
ARITHMETIC ON LOOP COUNT VALUE [NO]:
VARIABLE VALUE EXTENSION [.cor]:.dat

As an example of a slightly more complicated task we look at re-numbering a file sequence in reverse numerical order. The first file is ice1.dat and the last file is ice10.dat. The output file corresponding to ice1.dat is to be called ICE10.OUT and the output file corresponding to ice10.dat is to be called ICE1.OUT. The macro is called ice.mac and uses the program variables: #IN for the input file and #OUT for the output file. The following is the program output and user input for this sequence definition:

Main menu: ENTER COMMAND [INPUT DATA]:seq
LOOP COUNT START VALUE [4]:1
LOOP COUNT MAXIMUM VALUE (INCLUSIVE) [20]:10
LOOP COUNT INCREMENT STEP [1]:
INPUT MACRO FILE NAME [ice.mac]:
NUMBER OF VARIABLES TO DEFINE (Range: 0 to 20) [1]:2
ENTER VARIABLE NAME [#IN]:
ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:
VARIABLE VALUE BASE [lys]:ice
VARIABLE PART FIXED LENGTH [NO]:
ARITHMETIC ON LOOP COUNT VALUE [NO]:
VARIABLE VALUE EXTENSION [.gel]:.dat
ENTER VARIABLE NAME [#OUT]:
ENTER DATA TYPE OF VARIABLE [CHARACTER STRING VALUE]:s
VARIABLE VALUE BASE [ice]:ICE
VARIABLE PART FIXED LENGTH [NO]:
ARITHMETIC ON LOOP COUNT VALUE [NO]:y
MULTIPLIER FOR LOOP COUNT VALUE [1.00000]:-1
CONSTANT TO ADD TO MODIFIED LOOP COUNT VALUE [0.0]:11
VARIABLE VALUE EXTENSION [.dat]:.OUT