HOME GUIDE OPERATIONS DOCS ERRORS FORMATS INSTALL NEW TIPS WEB SITES

WORKING WITH SPIDER - A USER'S GUIDE

This Guide covers issues relating to the syntax, conventions, and running of SPIDER. It also has a section that discusses procedures and how to write them. Error handling, specialized techniques and tools, details on file formats, and distribution, installation and release notes, are discussed elsewhere.

This guide is classified under the following headings:


SPIDER can be run either interactively or in a batch mode. Interactive means that user input on the terminal is solicited by messages appearing on the screen. In the batch mode, control input is taken from a batch control file where it has to appear in exactly the same sequence as in an interactive session.

Running SPIDER Interactively

We call a session the entire sequence of operations from the start of SPIDER to the execution of the EN (ENd) command.

Starting The Session

Log on in your directory, then start SPIDER by typing:
spider
   or
spider <Prj>/<Dat>

SPIDER will then print the some introductory information including:

The version number, issue date for this version, and the maximum amount of run_time memory you have requested.
If the PROJECT/DATA EXTENSION is not given on the command line, SPIDER will then respond with:
.ENTER PROJECT/DATA EXTENSION: <Prj>/<Dat>
The project extension <Prj> consists of a three letter sequence, e.g, 'GLS', and is used to identify batch files, procedure files, the LOG file, and the RESULTS file by attaching this sequence to the file names as an extension.

The data extension <Dat> is optional. It consists of a three letter sequence, e.g., 'SCI', and is used to identify the data files by attaching this sequence to data file names as an extension.

For example, an image file specified as 'ACF001' during the SPIDER session will have as a full filename 'ACF001.SCI' if the above data extension 'SCI' is used.

A file created as an output file of a SPIDER operation will have the <Dat> extension attached to its SPIDER file name. If no data extension is given, the system uses the project extension as data extension.

The set of files having the same data extension can be thought of as a library. Within one session of SPIDER, all image files accessed and created belong to the same library.

[Note, however, that the new operation NC (New Code) may be used within the SPIDER run to redefine the project extension/data extension.]

If more than one SPIDER session is being run in the same directory, different project extensions must be used.

Each input line typed by the user is echoed by SPIDER on the subsequent line so that typing errors become apparent.

Each line produced by SPIDER that requires input is preceded by a period, e.g., '.INPUT FILE:'.

The Command Input Status

The system now asks:
.OPERATION:
All available operations are specified by two or more letter commands, e.g. LI for LIsting selected rows of an image. A list of the commands and their meanings can be obtained by entering the MEnu command ME.

[The menu listing is also available as an index of operations which is part of this SPIDER documentation. We recommend that you obtain a hardcopy listing of this and post it next to the terminal for reference.]

User-Solicited Information

After a command is entered, additional information needed to carry out the operation is solicited from the user. This information may be grouped into the following categories: (a) File information on input and output (mostly image) files, and (b) Values of parameters. These types of input are described in what follows.

File Names

These are sequences of alphanumeric characters, normally (but not necessarily) of the form <ABC><###> where <ABC> is any sequence of three or more characters (the prefix), and <###> is three or more digit number. If this convention is followed, files can be accessed under control of SPIDER DO-loops. The file name (without extension) can have up to 79 characters and the prefix can contain directory information. For example, ../usr/people/myself/A12BCDE001 is acceptable.

SPIDER can substitute for any portion of the file name at run time using a numerical value contained in registers or the value of the DO-loop index. Any text entered as part of a filename which is enclosed between "{" and "}" brackets is presumed to be part of a desired substitution request.

To substitute a register value into a file name, use the sequence {****X<##>} where the "*" string denotes the number of digits for the substitution and the "##" denote the register whose contents are to be substituted in place of the astericks. Any register from 0...99 may be used for substitution. E.g. if the the file name entered is ABC6{***X11} and the run time contents of register X11 is the value 34, then the resulting filename is: ABC6034.

In batch mode inside a DO-loop, the the current DO-loop index value can be substituted into a filename. To substitute a DO-loop index value into a file name, use the sequence {****<C>} where the "*" (s) denote the number of digits for the substitution and the "C" denotes a single character for the do loop index whose value is to be substituted in place of the astericks. Any index from A...Z may be used for substitution. E.g. if the file name entered is ABC{****I} and the run time value of do-loop index I is the value 34, then the resulting filename is: ABC0034. There may be any number of substitution strings within a single filename, e.g. on Unix in batch mode within a do-loop, the following is a valid filename: /usr/dir{*I}/abcd{****X34} . If the value to be substituted contains more digits than the number of astericks specified an error will occur .

A less powerfull and more ambiguous old formalism for filename substitution is still recognized but its futher use is no longer recommended.

The full file name is the above character string amended with .<Dat>, where <Dat> is the data extension specified at the beginning of the session.

The use of the character '*' as the first character (subsequent ones are ignored) of the file name terminates the current operation and makes the system ready to accept a new command. Some operations with implied DO-loops continue to solicit input files until the escape character '*' is used as a file name. Examples include AD and SU.

File Handling

The file whose name is typed in is either an input or an output file.

Input files are assumed to exist and contain data used as input to the operation. The fact that a file is input to the operation does not necessarily exclude changes to the file; An example of operations that changes the file is PP LL (Put Lines in image from doc file) .

If an operation requires more than one input file, these are distinguished in the solicitation messages as 'INPUT1', 'INPUT2', etc.

In the case of the Cross-Correlation operation (CC), one of the input files is used as a reference file, and is solicited as 'REFERENCE FILE'.

Output files can be either files that already exist, or files that are to be created under the name specified by the user. Already existing files having the same name are overwritten without a warning message.

The dimensions of the output file are dependent on the operation, and are either copied from the input file (e.g SHift, RoTate) or are solicited from the user (e.g. InterPolate, WIndow).

File Opening

After each input file or output file specification, SPIDER will attempt to open the file. After the file is opened, a statement is written on the terminal which has the following form:
<ABC><###> /<Title>
(<T>) <NSAM> <NROW> <NSLICE> CREATED <Date> AT <Time> <D> HEADER BYTES: <BYTES>

where:
<ABC><###>
is the file name.

<Title>
is the title previously entered by the user.

<T>
is the data type code and has the following values:
'F' for radix -2 Fourier data.
'FE' for mixed radix -2 Fourier data corresponding to even-length real data.
'FO' for mixed radix -2 Fourier data corresponding to odd-length real data.
'R' for Real data.

The type code in the file label is used to prevent operations inconsistent with the data format from being carried out (e.g., Real data cannot be inversely Fourier transformed)

<NSAM>,<NROW>,<NSLICE>
is the number of sampling points, number of rows, and number of slices in the image. In the case of Fourier transforms, the numbers correspond to those of the transformed image.

<Date>,<Time>
is the date and time of file creation.

<D>
is the disposition of the file. The following codes are used:
'N' if file is newly created
'O' if file is old

<BYTES>
is the number of bytes in the SPIDER header for this file

If the file represents 3-D information, the third dimension <NSLICE> is listed along with <NSAM> and <NROW>. In case of abnormal termination of the session, the user should carefully check the opening information of all files that were open when the program failed. This will tell him/her if the image format was correct, and if the correct image file has been accessed.

Image File Storage

The exact format in which images and volumes are stored on disk along with their headers, and the contents of the headers is detailed elsewhere. The only operation that accesses the image or volume files by explicit record numbers is LI (LIst). This operation is useful for dumping image contents or debugging purposes.

Inline Files

Many SPIDER uses involve the creation of temporary image files which undergo further processing later in the session. Computer access to these files is faster when they are kept in memory instead of being written out to disk. A inline file is referred to as: <_#>. Where <_#> is one to three underscore symbol(s) followed by a single digit. Any such file is stored in memory as an "inline file". On Unix SPIDER nine inline files are available and they can hold any size image. The inline file connotation of file names beginning with "_" can be toggled on/off (for testing) with a MD option. An example of a filename that denotes an inline file number 2 is: _2.

Image Stacks

Multiple images can be stored within a single SPIDER "stack file". A stack file differs from a SPIDER volume in that each image keeps its own full header. A stacked image is referred to as: <ABC><###>@<###> where <ABC> is a sequence of alphanumeric characters and <###> is a sequence of digits. The digits afer the '@' symbol represent the image number within a stack. Stacked images can be used anywhere a normal SPIDER file name would be used. An example of a filename that denotes image number 4056 inside a stack file is: fil001@4056.

Inline Stack Files

Inline stack files are available in Unix SPIDER and should be useful on machines with large physical memory. An inline stacked image is referred to as: <_#>@<###>. Where <_#> is one to three underscore symbol(s) followed by a single digit and <###> is a sequence of digits. The digits afer the '@' symbol represent the image number within a stack. Inline stacked images can be used anywhere a normal SPIDER file name would be used. In this case, the first time a particular inline stack is referenced you will be asked for the total number of images in the stack. Alternatively, a stack can be created using the MS (Make Stack) operation. An example of a filename that denotes image number 4056 inside inline stack number two is: _2@4056.

Parameter Values

Values of parameters solicited by an operation can be real, integer, or alphanumeric. Alphanumeric parameters are used to specify options (e.g., (S)ine or (C)osine).

Real and integer parameters are read in without formatting rules; they can be at any place on the line, separated by commata or any number of blanks, and spread out over any number of (non-blank) lines. They are checked for correct type and possible typing errors. Such errors and type inconsistencies result in an error message:

.BAD INPUT PARAMETER(S). RE-ENTER:
The user then has to re-enter the entire line containing the error. For example, in IP (InterPolate), the user enters the dimensions of the output file:
41 50.0
where only integer input is allowed. After the error message, he has to re-enter:
41 50
However, if he had entered the two parameter values on two separate lines:
41
50
then the error message would relate to the last line only, and it is this line only which he has to re-enter by typing:
50

Completion of an Operation

After successful completion of the operation, the system returns to the command input status, by printing the solicitation message '.OPERATION:' on the screen.

Ending a SPIDER Session

If you want to terminate the session, you sign off with the EN command. SPIDER then responds with the terminal message:
SPIDER NORMAL STOP

Non-Image files used by SPIDER

SPIDER produces two files as a result of the user session: the RESULTS file and the LOG file

SPIDER also produces and uses document files. Document files are keyed, formatted, sequential text files used to store register contents and misc. numerical data. Unlike image files, they can be read and edited.

[In the case of batch or procedure operations, the system produces a temporary file from each permanent batch or procedure file used in the session. These temporary files contain all user-solicited information, or information solicited from the next higher level batch or procedure file, as well as replacements for symbolic references. The temporary file has the name <ABN>X.<Prj> where <ABN> is the batch or procedure file name and <Prj> is the project extension.]

RESULTS file

During an interactive session, any listings generated that are too lengthy to be listed at the terminal are written instead to the RESULTS file, RESULTS.<Prj>. This file also contains the protocol of any procedure started interactively.

During a batch session, the RESULTS file contains the protocol of the command sequence executed, as well as lists generated by it in their logical order.

The 'MD' operation with 'VB OFF' (Verbose Off) can be used to decrease the amount of output from batch loops and from the 'SD' and 'UD IC' operations. This can decrease the length of RESULTS files by thousands of lines.

LOG file

The LOG file, LOG.<Prj>, is a complete record of everything that has been typed in by the user during the interactive session. It is sometimes useful as a record of the session.

Document files

These are keyed, formatted, sequential files created by executing the SD command and certain additional operations. Document files are used to permanently store the contents of a group of registers (e.g., shift coordinates, angles, etc.) as realized in different images (specified by keys). Any subsequent SPIDER run can retrieve these register values by their keys.

Document files are also used for communication between Web and SPIDER. For example the "particle picking" operation in Web creates a set of document files used by certain operations in SPIDER.

Document files may also be used to define a processing protocol; switch on and off the execution of batch and procedure files, or include/exclude images of a series from processing depending on the result of previous operations.

Registers

SPIDER has 100 system registers available, X0-X99. These are used for the storing and transferring of parameter values in batch or procedure runs. A register can be filled in one of two ways:
  1. as output resulting from an operation
  2. by being explicitly set equal to a value or an arithmetic expression
For example, when SPIDER asks '.OPERATION:', the user may type:
X10=3.14159
System register X10 will then have the value 3.14159. To examine the contents of a register, the user need only type the register he/she wishes to examine. If 'X10' was entered in the above example, the contents of X10, 3.14159, would be printed on the screen.

All registers are set equal to zero at the start of the SPIDER session.

Special System Registers

The first 10 registers, X0-X9, are reserved for SPIDER internal use. Currently, X0-X6 and X9 contain important values. Since they are constantly updated, they may not be used for parameter transfer between operations. [They are meant to be used for dynamic dimensioning and arithmetic adjustments of images in the course of procedure runs. For example, padding of an image having arbitrary dimensions into an image having the nearest power-of-two dimensions is possible.

The contents of these special registers are:

X0     Index     current value of the DO-loop index
    (updated after each execution of the LB# statement)
X1     NSAM    number of samples of the last image opened
X2     NROW    number of rows of the last image opened
X3     FMAX    maximum of the image
X4     FMIN    minimum of the image
X5     AV    average of the image
X6     SIG    standard deviation
X7     NSLICE    number of slices in last image opened
X8     NSTACK    number of images in stack
X9     Error flag     [0 if no error occurred and 1 if an error occured
    in the most recent operation]
Note that FMAX, FMIN, AV, and SIG are only available if the image has ever been searched for these values. [Examples of operations that do this computation: FC, FS, HI, MN S, PR] Otherwise, the values of FMAX, FMIN, and AV will remain zero, and that of SIG will remain -1.

Registers may appear in arithmetic expressions, mathematical functions, as input parameters, and as output parameters in command lines.

Registers [or Arithmetic Expressions] as Input Parameters

Registers or valid arithmetic expressions containing registers may be used wherever integer or floating point values are solicited by operations.

Example 1:
RT
PIC001
PIC002
X11
is a valid sequence: the contents of register X11 are interpreted as a rotation angle.

Example 2:
SH
PIC001
PIC002
X11,X12
Here the contents of X11,X12 are interpreted as components of a shift vector.

Example 3:
SH
PIC001
PIC002
(X114.3-X10),SIN(X123.14/180.)
Here each arithmetic expression is evaluated first, and the resulting values are interpreted as components of a shift vector.

Note that the register content is always a floating point number. If read in as an integer, the closest integer value is used, e.g. 4 for 3.8, 3 for 3.2, -4 for -4.25, etc.

Rules for use of registers or expressions as value input:

  1. Mixing of registers or expressions with numbers is not allowed in the input; e.g. X11,5 may not be used in Example 2.
  2. In DO-loops, only one register [or register pair, respectively] or one expression [or expression pair] may be used. This will be applied to each run of the DO-loop.
    Example:
    DO LB1 I=1,5
    SH
    PIC00I
    OUT00I
    X11,X12
    LB1
    This sequence will apply the values of X11,X12 to each run of the DO-loop. Parentheses around X11,X12 are not needed: if each run of the DO-loop requires different values, these may be introduced before the operation by an RR operation.

    Example:
    DO LB1 I=1,5
    RR X11 3.3, 1.5, 6.0, -8.1, 0.0
    RR X12 -7.5, 5.1, 3.2, -0.4, 8.1
    SH F
    PIC00I
    OUT00I
    X11,X12
    LB1

Registers as Output Parameters

Some operations such as FS, OR, and PK allow the specification of registers to accept output values. For example, PK X11,X12. After completion of the PK operation, the peak position components are contained in X11,X12.

As an example for a value transfer between operations by registers, consider the following sequence:

PK X11,X12
COR001
3
SH
PIC001
NEW001
-X11,-X12
PK is an operation that searches for the peak position in a file, normally a cross-correlation function. It allows specification of output registers (in the example, X11,X12) where the peak coordinates are to be stored. These registers may be used by any subsequent operation as floating point or integer input, in this example by SH (SHift). A minus sign may be used to invert the sign of the value input from a register. Note that mixed input will not be accepted where parameters are solicited. For example:
SH
PIC001
NEW001
-X11,15
will result in an error. In this case, the value 15 should be introduced into one of the registers prior to the 'SH' command, like this:
X12=15
SH
PIC001
NEW001
-X11,X12
A number of registers, X98-X103, are reserved for keeping track of certain device-dependent parameters.

Saving and Unsaving Registers

At any given time during the session or batch run, the contents of the registers X0 - X99 can be saved by using the SR command with the "save" option. Any subsequent operations on registers do not affect this stored register set. Execution of the SR command with "unsave" option will fetch the stored register set into the working register area.

Any number of register values can be saved in a permanent file by using the SD (Save Document) command. A subsequent UD command issued in a different (or the same) session, refering to the same document file, retrieves these register values. For details on saving and unsaving registers, see the SD and UD manual chapters.

SPIDER's Pocket Calculator

SPIDER incorporates a "pocket calculator" which evaluates arithmetic operations, expressions, and simple mathematical functions.

Arithmetic Operations

At the operation prompt in SPIDER, the user may type:
2*3+5
SPIDER will then respond with '11.0000'.

Available arithmetic operations are:

+     Addition
-     Subtraction
*     Multiplication
/     Division
**     Exponentiation
Square Root     available as mathematical function

Expressions

Epressions can be used within the SPIDER calculator and also in certain operations such as IF, IF, and IF. Expressions are evaluated from left to right with standard rules of precedence. In addition, the user may specify negative numbers and parentheses just as he/she would normally. For example, if the user typed:
(3*-2)*(2+6)
SPIDER would respond with '-48.0000'.

These operations may be used to manipulate registers as well. For example, if the user typed the following sequence:

X11=4.1
2*X11
SPIDER would respond with 8.2000.

In addition, the user may set a register equal to an expression. For example, if the user typed:

X12=9.6
X12=X12+5
SPIDER would store in X12 the value 14.6.

If the user types an expression that does not conform with the syntax rules of the conversion routines, SPIDER will respond with:

*** INVALID EXPRESSION
Examples of valid expressions are:
2*-6
((3+6)*(7*3))**9.1
X11=(X12+7)*(X16/X13)
X11=3.4e-4*1.0
Examples of invalid expressions are:
X100             [Register number exceeds 99]
X12=(2+3     [Unbalanced parenthesis]
(2+3/6))         [Unbalanced parenthesis]

Mathematical functions

Available mathematical functions are:

PAD(<Expression>)      next highest power of two of expression
SIN(<Expression>)      sine of expression
COS(<Expression>)      cosine of expression
EXP(<Expression>)      exponential of expression
LOG(<Expression>)      logarithm (Base 10) of expression
SQR(<Expression>)      square root of expression
MOD(N1,N2)      N1 modulo N2
INT(<Expression>)      rounded up/off integer
ABS(<Expression>)      absolute value of expression
ATA(<Expression>)      arc tangent of expression (in degrees)
ASI(<Expression>)      arc sine of expression (in degrees)
ACO(<Expression>)      arc cosine of expression (in degrees)
LN(<Expression>)      natural log of expression
RAN(<Dummy>)      pseudo-random number from uniform (0,1) distribution

where <Expression> stands for any valid expression, N1,N2 are numbers or registers, and <Dummy> is a dummy parameter which is not modified by the function.

Examples of valid usage:

SIN(4.5/(X5-100.))
X10=EXP(-400./X11**2)
Note that the mathematical functions may only be used in the outermost position. They may not be used inside of an arithmetic expression. An example of invalid usage:
X15=X14-SIN(45./180.*X91)
In this case, use the sequence:
X16=SIN(45./180.*X91)
X15=X14-X16

Running SPIDER in Batch Mode

Batch Control Files

Batch control files are user-created files containing sequences of commands and parameter values. Instead of taking the input from the terminal, SPIDER uses the control sequence as it appears in the batch file. All output that would normally appear on the terminal is directed to the RESULTS file, and no LOG file is created.

Procedures are special batch control sequences that allow run-time specifications. They are formally equivalent to subroutines in FORTRAN. To invoke a batch control sequence, the user types the name of the batch file without its extension. A batch file is named according to the following convention:

B<N><M>
where <M> and <N> are digits.

When calling a procedure from a batch file, the user puts the parameters (if any) solicited by the procedure behind the calling statement in the same order as they appear in the procedure file. For example:

Let AD1 contain the following:
AD
PIC001
?SECOND PICTURE TO BE ADDED?
*
RE
and let B01 contain the following:
RT
WOW001
OUT001
180.00
AD1
OUT001
EN
Then '.OPERATION: B01' will cause WOW001 to be rotated by 180 degrees, and stored in OUT001. OUT001 will then be added to PIC001. SPIDER will ultimately return to the level of the batch file, and terminate the session.

Comments

Comment lines may be inserted in either batch or procedure files. A comment has the form:
; This is a comment
A comment is a non-executable statement that will simply be printed out in the RESULTS file.

Comments may also appear on any lines that carry SPIDER statements. They must be separated from the last character of such a statement by at least one blank and a semicolon. Example:

PD ; Now pad input image
PIC001 ; From previous window
PAD005 ; Output will be used for FT
128,128 ; Next power of two dimensions
Y ; Use average for padding
1,1 ; Top left coos arbitrary in
; this case

Exceptions are statements that specify sets of numbers using hyphens, e.g., in the input to operation AS: 1-7,15-20. No comment is allowed in this type of statement.

DO-Loops

DO-Loops similar to those in FORTRAN are available in SPIDER. They are started by the statement:
DO LB<L>   <C>=<M>,<N>
and terminated by:
LB<L>

where
<L>
is a one or two digit integer used for distinguishing the terminating label and the associated DO-loops.

<C>
is a one-character symbol denoting the DO-loop index.

<M>,<N>
are positive-valued integers or registers defining beginning and end of the DO-loop. Successively, the index <C> will be assigned the values <M>, <M>+1, <M>+2, ... <N>. Note that <N> must be greater than <M>. <M> and <N> must be < 100,000.

Note that registers and constants may not be mixed. For instance:
DO LB1 I=X10,5
cannot be used. Instead, use:
X11=5
DO LB1 I=X10,X11
DO-loops may be nested, but they must be distinguished by different labels and different index symbols.

Variable Value Input in DO-Loops

There are basically two different uses of DO-loops in an image processing application:
  1. Applying the same sequence of operations with the same parameter values to different images, distinguished by numbered file names.
  2. Applying the same sequence of operations with different parameter values to the same image.

To serve the first application, variable file names are provided:
<ABC>00<C>

where:
<ABC>
is a three-character file prefix identifying the file series;

<C>
is the DO-loop count defined above.

To make variable parameter input possible, values may be entered as arrays, to be picked according to the DO-loop count. Example:
DO LB1 I=1,3
RT
PIC00I
OUT00I
45. 61. 78
LB1
In this example, RT uses the angles 45, 61 and 78 degrees with the pictures PIC001, PIC002, and PIC003, respectively.

In the case of operations requiring a pair of numbers (e.g., shift coordinates), one pair has to be provided for each run of the DO-loop. However, if the same floating point number or pair of numbers should be used for each run of the DO-loop, this may be specified by using a single number (or pair of numbers) enclosed in parentheses. Example:

DO LB7 B=5,9
SH
ALL00B
SHI00B
(15,8)
LB7
In this case, the shift parameter values 15,8 are applied to each image, starting with ALL005 and ending with ALL009.


Procedures

Procedures are control sequences stored in files that allow run-time replacements of specified parameters. Procedure files are similar to batch files, except that they are named by one of the two following conventions:
<AB><N>.<PRJ>
    or
<ABCDEFGH>.<PRJ>
where <AB> are any two letters, <N> is a digit, <PRJ> is the project extension used in this session, and <ABCDEFGH> are any 8 alphanumeric characters starting with an alphabetic character,, and The first part of the procedure file name preceeding the SPIDER file extension is called the procedure name. For example, a legal procedure name using the first naming convention would be:
PR2.DAT
A legal procedure file name using the second naming convention would be:
ALIGN10.DAT
To invoke a procedure using the first naming convention, when SPIDER asks '.OPERATION:', the user types in the procedure name, for example:

.OPERATION: PR2
To invoke a procedure using the the second naming convention type '@' in front of the procedure name:
.OPERATION: @ALIGN10
Solicitation messages enclosed by question marks will appear in the order they are defined in the procedure command sequence..

Procedures may be called from:

  1. a batch command file
  2. another procedure
  3. an interactive session
If called from a batch command file, the commands stored in the procedure file will be executed until a RE (REturn) command is encountered. At that time, control will be returned to the command following the procedure call in the calling batch file.

If called from the interactive mode, when a 'RE' command is encountered, control will return to the terminal. If called from another procedure file, control will be passed to the command following the procedure call.

Procedures allow the user to specify parameters at run time. If called from a batch file or another procedure, the procedure requires parameter values in the order they have been internally defined when the procedure was written.

When called in the interactive mode, the procedure will solicit the required parameters from the terminal.

Execution Rules

Standard procedures are contained in the system's directory with the extension 'SYS'. These procedures form the standard procedure library (SPL).

For any procedure call, SPIDER will first scan the user's directory. If a procedure file under the name <AB><N>.<PRJ> is found, then this procedure becomes effective in the call. Only if no such procedure is found, SPIDER will attempt to locate the file <AB><N>.SYS in the system directory.

[When SPIDER encounters a reference to a batch or procedure file, it creates a temporary version of it which has all open run-time references filled. The name of this file is <AB><N>X.<PRJ> if <AB><N>.<PRJ> or <AB><N>.SYS is the name of the original control file. Procedure files <ABC...>.<PRJ> with the new naming convention are temporarily translated into a file named <ABC...>X.<PRJ>. Looking at this file sometimes helps in debugging new batch or procedure files.]

Writing New Procedures

To create a procedure file from a batch file, the user has to:
  1. Replace the batch file name by a name for the procedure that follows the conventions outlined above.
  2. Replace any parameter in the batch file that the user wishes to specify at run time by a solicitation message enclosed in question marks, e.g., ?PICTURE TO BE ADDED? (See below).
  3. Replace the EN command at the end by a RE command.
At execution time, the user-specified solicitation messages are the only messages that will appear on the terminal.

For example, if the following procedure were called from the interactive mode:

AD
PIC001
?PICTURE TO BE ADDED?
*
RE
SPIDER would print '?PICTURE TO BE ADDED?' at the terminal and wait for the user to specify the file to be added to PIC001. It would then add the two pictures, and upon encountering the RE command, will return to the interactive mode.

Some restrictions exist on the definition of procedures:

  1. A procedure file may not call a batch file, since batch files are generally created for a specific purpose and normally run only once, whereas procedures are used several times in different projects.
  2. The parameter to be specified at run time may not be a command. This restriction is imposed because each command may produce a different number of subsequent solicitations.

Symbolic Parameters

Frequently, one encounters the situation where more than once the same information is required in the procedure. For example, the following procedure definition solicits the name of the image to be aligned twice from the user:
; PR2 ALIGN IMAGE WITH REFERENCE
PD
?IMAGE TO BE ALIGNED? <1>
ACF001
128,128
N
33,33
PD
?REFERENCE IMAGE?
ACF002
128,128
N
33,33
AC
ACF001
AC
ACF002
OR X10
ACF001
ACF002
5
RT
?IMAGE TO BE ALIGNED?
?OUTPUT IMAGE?
X10
RE
A special feature of SPIDER allows the user to tie a symbolic parameter label to any procedure solicitation message (marked by a ?...? ). Later this symbolic parameter label can be used in place of the repeated solicitation message. The format for the label is: <N>, where N may be any one or two-digit number. Note that the <> brackets are necessary here to indicate a symbolic parameter label!

In the example for a procedure definition given above, the second occurrence of ?IMAGE TO BE ALIGNED? may therefore be replaced by <1>, since this is the label assigned at the first occurance of the ?IMAGE TO BE ALIGNED? use. A run-time specification for ?IMAGE TO BE ALIGNED? will then be automatically applied to the input.

Variable Symbolic Parameters

Symbolic parameters that represent file names may be modified at run time by attaching a DO-loop index or register to it. The three digits of the filename are then replaced by new digits according to the current value of the register.
Example 1:
; PR1
FR
?ENTER FIRST IMAGE?<1>
DO LB1 I=2,10
PR
<1>I
N
LB1
RE
Calling sequence:
PR1
PIC001
In the DO-loop, PIC001 will then be replaced by PIC002, PIC003, ... , PIC010.
Example 2:
; PR2
RR X15
?PICK OUT FILE NUMBER?
FI
PICX15
RE
Calling sequence:
PR2
5.
In this example, the operation FI is applied to PIC005.
Example 3:
;PR3
FR
?ENTER ANY IMAGE OF SERIES? <1>
RR X10
?PICK OUT FILE NUMBER?<2>
FS
<1>X10
Calling sequence:
PR3
PIC003
20.
In this example, the operation FS is applied to PIC020.

Symbolic Parameters in DO-Loops

Symbolic parameters cause a transfer of the whole input line at the time of the execution, not just the transfer of a single number. It is therefore possible to use the symbolic reference in DO-loops.
Example:
;PR4
DO LB1 I=1,5
SH
PIC00I
OUT00I
?ENTER SHIFT COMPONENTS?<1>
SH
PAD00I
SCR00I
<1>
LB1
RE
Calling sequence:
PR4
5,1 4,3 8,5 10,1 0,0
In this example, each pair of components is applied to both SH operations; i.e. 5,1 for I=1, 4,3 for I=2, etc. See DO-loops.

Using Registers in Nested Procedures (or Procedures called from Batch Files)

Registers, in calling batch or procedure control files, are independent of registers within the procedures called. However, if values need to be transferred from the calling procedure to the procedure called, either argument transfer or the command RR may be used.

Argument Transfer

Procedure calls may contain up to 6 register arguments if these are matched by a defining argument sequence in the procedure called. The defining argument sequence must appear as the first line of the procedure (before any comments), and must be of the form:
[X<N1>,X<N2>,X<N3>,...]
where X<N1>,X<N2>,X<N3>,... are registers appearing in the procedure. The calling sequence must have the same number of registers, and must be of the form:
@<PROCNAME>[X<M1>,X<M2>,X<M3>,...].
Register values are passed in both directions; i.e., from the upper to the lower level and vice-versa.
X20=1
X30=5
X40=-4
@PROC[X20,X30,X40]
will result in the values:
X20=2
X30=-20
X40=-2
if the procedure is defined as follows:
[X10,X11,X12]
X10=X10*2
X11=X11*X12
X12=X12/2
RE

Procedure calls in DO-Loops

An important restriction applies if a procedure is called within a DO-loop. Specifically, if different parameter values are to be used in the different runs of the DO-loop, they must not be entered as a string of numbers:
DO LB1 I=1,5
PS1
6.5 7.3 8.1 4.9 3.3
LB1
will result in the value 6.5 being repeatedly used by procedure PS1. To use different values, the numbers must be successively stored in a register which transfers them to PS1 (See also DO-loops):
DO LB1 I=1,5
RR X20
6.5 7.3 8.1 4.9 3.3
PS1
X20
LB1

Memory Allocation & Multiprocessors

In Unix SPIDER most memory intensive operations now make use of run time allocation (and deallocation) of necessary memory. In order to prevent SPIDER from interfering with other simultaneous processes, the user can limit the memory available to SPIDER. This limit will default to 50 MB. The limit can be reset by defining the Unix environmental variable SP_MEMALLOC or by using the MD with 'SET MEM'

Unix SPIDER contains comments which can be used by the parallelizing Fortran compiler available on SGI multiprocessor machines. The MD operation with 'SET MP' can be used to limit the number of processors used during SPIDER execution on such SGI machines.


Submitting Batch Jobs on UNIX systems

Most Unix systems have queues available for scheduling execution of batch jobs and methods of placing a process in the background. Some notes on this are contained in: batch-unix_doc.html.

Source: user_doc.html     Last update: 5 February 1998     ArDean Leith


© Copyright Notice /       Enquiries: spider@wadsworth.org