
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.
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:
- as output resulting from an operation
- 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:
- Mixing of registers or expressions with numbers is not
allowed in the input; e.g. X11,5 may not be used in
Example 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
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:
-
Applying the same sequence of operations with the
same parameter values to different images,
distinguished by numbered file names.
-
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 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:
- a batch command file
- another procedure
- 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:
- Replace the batch file name by a name for the
procedure that follows the conventions outlined above.
- 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).
- 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:
- 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.
- 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
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.
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