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 and installation, and release notes are discussed elsewhere.
This guide is organized under the following headings:
SPIDER can be run either interactively or in a procedure mode. Interactive mode means that user input on the terminal is solicited by messages appearing on the screen. In the procedure mode, control input is taken from a procedure 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) operation.
Log on in your directory, then start SPIDER by typing:
SPIDER will then print some introductory information including:
If the PROJECT/DATA EXTENSION is not given on the command line, SPIDER will then respond with:
The project extension <Prj> consists of a three letter sequence, e.g, 'GLS', is used to identify 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.
[Note that the new extension 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 should 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:'.
SPIDER can accept optional command line parameters in addition to the PROJECT/DATA EXTENSION.
The system now asks:
.OPERATION:
All available operations are specified by two or more letter operations, e.g. LI for Listing selected rows of an image. A list of the operations and their meanings is available in the index of operations which is part of this SPIDER documentation. You may want to obtain a hardcopy listing and post it next to your terminal for reference.]
After an operation 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.
These are sequences of alphanumeric characters, often (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 easily accessed under control of SPIDER DO-loops. The file name (without extension) can have up to 77 characters and the prefix can contain directory information. For example, ../usr/myself/A12BCDE001 is an acceptable filename. In order to still support a legacy naming convention do not use the letter 'x' or 'X' within file names or you may get odd substitutions.
SPIDER can substitute for any portion of the file name at run time using a value contained in a symbolic variable or register variable. Any text entered as part of a filename which is enclosed between "{" and "}" or "[]" brackets is presumed to be part of a desired substitution request.
To substitute a symbolic variable value into a file name, place the sequence symbol at the desired location within the filename. E.g. if the the file name entered is: ABC[file_suffix], and the content of symbolic variable: [file_suffix] is the value _rotated, then the resulting file name is: ABC_rotated.
To substitute a register variable value into a file name, use the sequence {****[register_var]} where the "*" string denotes the number of digits for the substitution and the "[register_var]" denotes the register variable whose numerical value is to be substituted in place of the astericks. E.g. if the the file name entered is: ABC6{***[filenum]} and the run time content of register variable [filenum] is the value: 34, then the resulting filename is: ABC6034. This mechanism can also be used inside a DO-loop to substitute the current DO-loop index value into a filename.
There may be any number of substitution strings within a single filename, e.g. the following is a valid filename: /usr/dir{*[dirnum]}/abcd{****[filenum]}, if the value in [dirnum] only contains a single digit and the value in [filenum] has less than 5 digits. If the register variable value (converted to an integer) to be substituted contains more digits than the number of astericks specified an error will occur.
A few SPIDER operations such as AP SH are designed to operate on a whole series of images. In this case the user is asked for a file name template in which the variant portion of the file name is indicated by astericks '*'. E.g. a file name template: dir/ABC****. The user is also prompted for a list or (document file) containing the numbers of the files to be operated on. This same formalism may be used in procedures.
The full file name is the base 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 operation. 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.
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 an operation that alters the input file is PP LL (Put Lines in image from doc 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).
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>) <NX> <NY> <NZ> CREATED <Date> AT <Time> <D> HEADER BYTES: <BYTES>
Where:
- <ABC###>
- Is the file name.
- <Title>
- Is a title entered by the user with TT.
- <T>
- Is the data type code and has the following values:
'O2' Mixed radix -2D Fourier data corresponding to odd-length real image data. 'E2' Mixed radix -2D Fourier data corresponding to even-length real image data. 'O3' Mixed radix -3D Fourier data corresponding to odd-length real volume data. 'E3' Mixed radix -3D Fourier data corresponding to even-length real volume data. 'R2' 2D real image data. 'R3' 3D real volume data. 'S2' Stacked 2D real image data. 'S3' Stacked 3D real volume data. 'I2' Indexed, stacked 2D real image data. 'I3' Indexed, stacked 3D real volume data. The data 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).
- <NX>,<NY>,<NZ>
- Is the number of sampling points (columns), 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
Example --- :
| PT | ; Put pixel in image |
| PIC001 | ; Output file |
| 44,44 | ; X and Y size |
| P | ; Put point |
| 1 | ; Number of points |
| 20,20 | ; Location |
| N | ; Do not continue |
Gives output:
PIC001
(R ) 44 44 CREATED 08-NOV-2005 AT 12:26:40 N HEADER BYTES: 1056
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.
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 for debugging purposes.
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 one or two digits. Any such file is stored in memory as an "inline file". Ninety-nine inline files are available and they can hold any size image. An example of a filename that denotes an inline file number 2 is: _2.
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 after 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 stack file fil001 is: fil001@4056.
Inline stack files are available 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 one or two digits 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.
Both disk based and inline stack files are available with an index and may be used like normal SPIDER stack files. An indexed stack may be useful if you have a sparsely populated large stack. In an indexed stack there is an extra set of records following the overall header that stores the indices. Unlike a normal stack there is no space wasted for a missing image in the stack. For indexed stacks the first time a particular indexed stack is referenced you will be asked for the maximum number of any image in the index. For indexed inline stacks this number is usually different from the maximum number of images that can be held in the stack. An indexed stack can only be created using the MS I or CP I operations.
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 commas 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:
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:
After successful completion of the operation, the system returns to the operation input status, by printing the solicitation message '.OPERATION:' on the screen.
If you want to terminate the session, you sign off with the EN operation. SPIDER then responds with the terminal message:
SPIDER produces two files as a result of the user session: the RESULTS file and the LOG file. For some operations SPIDER also produces and/or uses document files.
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>.<Version>. Where <Version> is a sequential version number applied by SPIDER to differentiate successive runs within a directory. This file also contains the protocol of any procedure started interactively.
During a procedure session, the RESULTS file contains the protocol of the operation sequence executed, as well as lists generated by it in their logical order.
The 'MD' operation with 'VB OFF' with option: Verbose Off can be used to decrease the amount of output from DO-loops, file opening, and from the 'SD' and 'UD IC' operations. This can decrease the length of RESULTS files by thousands of lines in long procedures.
The 'MY FL' operation can be used to force a write from any accumulation in the systems output buffer to the RESULTS file.
The LOG file, LOG.<Prj>, is a complete record of everything that has been typed in by the user during an interactive session. It is sometimes useful as a record of the session.
Document files are keyed, formatted, sequential files created by executing the SD operation and certain additional operations. Document files are used to permanently store the contents of a group of register variables (e.g., shift coordinates, angles, etc.) as realized in different images (specified by keys). Any subsequent SPIDER run can retrieve these variable 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 switch on and off the execution of procedure files, or include/exclude images of a series from processing depending on the result of previous operations.
Two types of variables are available in SPIDER. Register (numerical) Variables can contain any floating point value. Symbolic (String) Variables are strings of characters. Both types of variables are denoted with '[]' brackets. You should not simultaneously use the same variable name for both a symbolic variable and a register variable within a single procedure. Variable names can contain alphanumeric characters plus '_' and '-'. Variable names should start with a alphabetic letter not a digit. Other special characters including a blank may work but are not supported and may cease to work in the future. Names are case-sensitive.
Register variables are used for storing and transferring numerical values during a SPIDER session. Internally they are stored as double precison values. Register variables now have user specifed names. These variables are denoted with '[]' brackets e.g. [pi]. For backward compatibility we still allow the use of the numerical register notations (e.g. X11) present in older releases of SPIDER, but we recommend that you switch to this newer convention. The number of register variables may be increased using the MD operation with option "SET VARS". However the number of usable register variables in SPIDER is also limited by the combined length of all the defined variable names and this limit can only be increased by recompiling SPIDER. However the amount is quite generous.
Register variables may appear in arithmetic expressions, and mathematical functions.
A register variable can be created in five ways:
Example --- 1:
When SPIDER asks '.OPERATION:', the user may explicity create and set a register variable:
| [pi] = 3.14159 |
Register variable pi will then take on the value: 3.14159. To examine the contents of a variable, the user need only type the name of the variable he/she wishes to examine. E.g. enter: [pi] at the operation prompt and the value of variable [pi], 3.14159, will be printed on the terminal or in the RESULTS file.
Example --- 2:
Some operations can create and set a register variable:
| FS [max] | ; Read image maximum into variable [max] |
| FIL008 | ; File name |
Example --- 3:
A 'DO Loop can create and set a register variable:
| DO [img]=1,100 | ; Loop to set [img] from 1...100 |
Example --- 4:
RR can create and set a register variable:
| RR [pi] | ; Read variable |
| 3.14159 | ; Variable value |
Older releases of SPIDER used numerical system registers called x0...x100 for storing register variables. These system registers were denoted by the appearance of the 'x' or 'X' followed by digits. For backward compatibility we still allow the use of the numerical system register notation present in older releases of SPIDER, but we suggest that you switch to this newer convention with named register variables. Registers: X0...X10 contained special values. X0 contained the most recent content of the DO-loop index (updated after each execution of the ENDDO or LB# statement). Register: X9 held an Error flag (0 if no error occurred and 1 if an error occured in the most recent operation). You will still see numerical system registers in use in many procedures distributed with SPIDER. The values of all the numerical system register variables could be saved and retrieved using the 'SR' operation. The 'SR' operation is no longer available in SPIDER. .
Register variables or arithmetic expressions containing register variables may be used wherever integer or floating point values are solicited by operations.
Example --- 1:
| [size]=33 | ; Create register variable |
| MO | ; Create model image |
| PIC002 | ; Output file |
| [size], [size] | ; Image x and y size |
| T | ; Sine wave image |
Here the contents of register variable: [size] are interpreted as X and Y size of image.
Example --- 2:
| [offset]=29 | ; Create register variable |
| SH | ; Shift image |
| PIC002 | ; Input file |
| PIC003 | ; Output file |
| ([size]-[offset]), SQR([size]-2) | ; Shifts |
Here each arithmetic expression is evaluated first, and the resulting values are interpreted as components of a shift vector.
Note that the register variable 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.
Some operations such as FS, and PK allow the specification on the operation line of register variables to accept output parameters. PK is an operation that searches for the peak positions in a file. It allows specification of output parameters on the operation line (in the example, [locx] and [locy]) where the peak coordinates are to be stored. These variables may be used by subsequent operations needing floating point or integer parameter input. A minus sign may be used to invert the sign of the value input from a variable.
Example --- :
| PK [locx],[locy] | |
| PIC001 | ; Input file |
| 1 | ; Number of peaks to be found |
| SH | ; Shift |
| PIC001 | ; Input file |
| PIC003 | ; Output file |
| -[locx],-[locy] | ; Shifts |
Any number of register variable values can be saved in a permanent file using the SD (Save Document) operation. A subsequent UD or UD IC operation issued in a different (or the same) session, refering to the same document file, retrieves these variable values. For details on saving and unsaving variables, see the SD, UD and UD IC manual chapters.
SPIDER incorporates a "pocket calculator" which evaluates arithmetic operations, expressions, and mathematical functions.
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 |
| Mathematical function |
Expressions can be used within the SPIDER calculator and also in certain operations such as IF, IF...GOTO, IF... THEN, and ELSEIF... THEN.
Expressions are evaluated from left to right with standard rules of precedence with one important exception: a string of adjacent arithmetic operators are not allowed. 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'.
Scientific notation (i.e., 2.3E-4) is allowed.
These operations may be used to manipulate register variables as well. For example, if the user typed the following sequence:
| [var]=4.1 |
| 2*[var] |
SPIDER would respond with 8.2000.
In addition, the user may set a register variables equal to the value of an expression. For example, if the user typed:
| [var]=9.6 |
| [var]=[var]+5 |
SPIDER would store the value: 14.6 in [var].
If the user types an expression that does not conform with the syntax rules of the conversion routines, SPIDER will respond with:
Examples of valid expressions are:
| 2*(-6) | ((3+6)*(7*3))**9.1 | [var0]=([var1]+7)*([var2]/[var2]) | [var1]=3.4e-4*6.0 | |
Examples of invalid expressions are:
| [var]=(2+3 | ; [Unbalanced parenthesis] |
| (2+3/6)) | ; [Unbalanced parenthesis] |
| 2*-6 | ; [Adjacent arithmetic operators] |
| 2*(-6E2) | ; [No dot in the number] |
| 1 - 4 | ; [No blanks allowed inside] |
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 |
| LON(<Expression>) | Natural log of expression |
| SQR(<Expression>) | Square root of expression |
| INT(<Expression>) | Truncates to 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) |
| TAN(<Expression>) | Tangent of expression |
| RAN(<Any variable>) | Pseudo random uniform number generator in range from 0 to 1. |
| RNN(<Any variable>) | Pseudo random number generator, with normal distribution (0,1). |
where <Expression> stands for any valid SPIDER math expression.
All trigonometric functions use arguments (or give results) in degrees.
Examples of valid usage:
| [var] = SIN(4.5/([var]-100.)) | |
| [var] = EXP(-400./[var1]**2) | |
| [var] = [var1]-SIN(45./180.*[var2]) | |
| [var] = SIN(45./180.*[var1]) | |
| [var] = [var1] - COS(LON([var2])) | |
| [var] = RAN([dummy]) | ; Value of [dummy] not altered nor used for anything! |
| IF (INT([i]/2)==[i]/2) [even] = 1 | ; Finding even/odd |
Symbolic (String) Variables are denoted with '[]' brackets e.g. [filename]. The number of symbolic variables in SPIDER is dependent upon the combined length of the variable names and their associated values and can only be increased by recompiling SPIDER. However the amount is quite generous. Symbolic variables are used for storing and substituting character strings. Symbolic variables can be either global or local to a procedure. Symbolic variables are commonly used to store file names. Symbolic variables can be nested so as to contain register variables or other symbolic variables. A symbolic variable can be created in the following ways:
Example --- 1:
| [filename] = 'PIC001' | ; Set a string variable |
This is equivalent to the obsolete sequence:
| FR L | ; Set a string variable |
| [filename]PIC001 |
Example --- 2:
| ; Set a string variable | |
| [filenum] = 2 | ; Set a register variable |
| FI | ; File information operation |
| [filename] | ; File name |
Example --- 3:
| GLOBAL [dir] = 'img' | ; Set a global string variable | |
| GLOBAL [global_file]= '[dir]/IMG055' | ; Set a global string variable | |
| VM | ; Echo current value for the global string variable | |
| echo [global_file] |
Other uses of symbolic variables are discussed in the Procedure Mode section below.
A comment is a non-executable statement that will simply be printed out in the RESULTS file. Comments may be inserted anywhere during a SPIDER run, including on any lines that carry SPIDER operations and parameters, but they are usually used only in SPIDER procedure files. A comment is initiated with a semicolon ';' and anything appearing on a line after a semicolon is ignored during processing. A comment has the form:
; This is a comment
Examples ----:
| 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 coord. arbitrary in this case |
Procedure files are user-created files or scripts containing sequences of operations and parameter values. Procedure files can have any alphanumeric name up to 77 characters but the name must begin with a letter. Instead of taking the input from the terminal, SPIDER uses the control sequence as it appears in the procedure file. All output that would normally appear on the terminal is directed to the RESULTS file, and no LOG file is created.
To invoke a procedure when SPIDER asks '.OPERATION:', the user types an "at" sign @ followed by the name of the procedure file without its extension.
| .OPERATION: @ALIGN10 |
Procedures may be called:
If a procedure is called from interactive session, when a 'RE' operation is encountered inside a procedure, control will return to the terminal. If a procedure is called from another procedure file, control will be passed to the operation following the procedure call.
Procedure files can be used in many different styles within SPIDER including:
Some standard procedures are contained in the SPIDER system's procedure directory 'spider/proc' with the extension 'spi'. These procedures form the standard procedure library for SPIDER.
For any procedure call, SPIDER will first scan the user's directory. If a procedure file under the given name is found, then this procedure is used in the call. If no such procedure is found, SPIDER will attempt to locate the given file with a .spi extension in the SPIDER system's procedure directory.
To pass initial arguments from the procedure caller to the called procedure, the user puts the arguments (if any) needed by the procedure behind the procedure name, enclosed in parenthesis, in the same order as they appear in the called procedure file. Procedures may pass up to 12 register variable 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 called procedure, and must be of the form:
| ([<N1>],[<N2>],[<N3>],...) |
Where: [<N1>],[<N2>],[<N3>],... are register variables appearing in the procedure. NOTE: Prior to 2004 '[]' brackets were used instead of '()'. The calling sequence must have the same number of registers, and must be of the form:
| @<PROCNAME>>([<M1>],[<M2>],[<M3>],...). |
Register variable values are passed in both directions; i.e., from the upper to the lower level and vice-versa.
Example --- :
If the procedure TEST_ARGS is defined as follows:
| ([v10],[v11],[v12]) |
| [v10]=[v10]*2 |
| [v11]=[v11]*[v12] |
| [v12]=[v12]/2 |
| RE |
invoking TEST_ARGS as follows:
| [v20]=1 |
| [v30]=5 |
| [v40]=-4 |
| @TEST_ARGS([v20],[v30],[v40]) |
will result in the following values within the caller:
| [v20] = 2 |
| [v30] = -20 |
| [v40] = -2 |
There are two methods to pass symbolic variables to a called procedure.
Replace the desired parameters inside the called procedure with a solicitation prompt and variable name for the parameters. Place the variable names behind the procedure calling statement in the exact same order as they will be queried in the called procedure. Inside the called procedure indicate that the variables should be obtained from the caller by placing a solicitation prompt enclosed in question marks followed by a symbolic variable name e.g., ?ROTATION ANGLE?[angle] in place of the variable that the user wishes to read.
If the procedure TEST_MASTER contains the following:
| @TEST_VAR | ; Procedure |
| PIC002 | ; 1'st solicited parameter (input filename) |
| 30 | ; 2'nd solicited parameter (angle) |
| EN |
and procedure: TEST_VAR contains the following:
| RT | ; Rotate images operation |
| ?INPUT FILE? | ; Solicit input filename |
| OUT007 | ; Output filename |
| ?ROTATION ANGLE?[angle] | ; Solicit rotation angle and assign to symbol: [angle] |
| RE |
Then '.OPERATION: @TEST_MASTER will read the image PIC002, rotate it by 30 degrees and store it in: OUT007.
Use the FR operation inside the called procedure to create a local symbolic variable by reading its value from a calling procedure.
If the procedure TEST_MASTER2 contains the following:
| @TEST_VAR2 | ; Procedure |
| PIC002 | ; 1'st solicited parameter (input filename) |
| 30 | ; 2'nd solicited parameter (angle) |
| EN |
and procedure: TEST_VAR2 contains the following:
| FR | |
| ?ROTATION ANGLE?[angle] | ; Solicit rotation angle and assign to symbolic variable: [angle] |
| RT | ; Rotate images operation |
| ?INPUT FILE? | ; Solicit input filename |
| OUT007 | ; Output filename |
| [angle] | ; Solicit rotation angle and assign to symbolic variable: [angle] |
| RE |
Again '.OPERATION: @TEST_MASTER2 will read the image PIC002, rotate it by 30 degrees and store it in: OUT007.
DO-Loops are control loops similar to those in FORTRAN. They are initiated with the statement:
DO <C>=<M>,<N>,<O>
and terminated with:
ENDDO
Where:
- <C>
- is a register variable for the DO-loop index.
- <M>,<N>,<O>
- are integers or variables defining beginning, the end of the DO-loop, and the loop counting increment. Successively, the index <C> will be assigned the values <M>, <M>+<O>, <M>+2*<O>, ... <N>. (We advise against using non-integers for these values as their definition may vary in the future.)
DO-loops may be nested, but they must be distinguished by different index variables. Maximum nesting is depth is ''MAXPRC''. See source file: '''CMLIMIT.INC'' for current value of ''MAXPRC''.
Prior to SPIDER release 15.0 there was an earlier syntax for initiating and ending DO-Loops which is still supported but deprecated.
- Loops were initiated:
- DO LB <L> <C>=<M>,<N>,<O>
- and terminated with:
- LB<L>
- Where:
- <L> was a one or two digit integer used for distinguishing the terminating label for this DO-loop.
There are two basically different uses of DO-loops in an image processing application:
<ABC>{<****><C>} E.g.: IMG{****[filenum]}
This convention is suitable for use in self-contained procedures.
<ABC><****><C> E.g.: IMG****[filenum]
This convention is more convenient when using
variable filenames in interactive procedures.
- <ABC>
- is a alphanumerical file prefix
- <***>
- denotes the number of digits to be substituted
- <C>
- is the DO-loop count variable defined above.
Example --- :
| DO [filenum]=1,4 | |
| MR | ; Mirror operation |
| PIC{****[filenum]} | ; Input file |
| OUT{****[filenum]} | ; Output file |
| Y | ; Mirror axis |
| ENDDO |
Inside a DO-Loop, the user may either wish to enter the same parameter (or set of parameters) on each iteration of the loop or alternatively change the parameters with each iteration.
As of SPIDER release 19.+, if the user wants to enter the same numerical parameter(s) on each iteration of a loop the user no longer has to surround the parameter(s) set with "()" parenthesis. If the user has confusing, legacy SPIDER procedures which require this error prone capabilty then he/she can use the MD operation with option: () ON to reactivate this legacy convention and require the ()'s.
Current Example --- :
| DO [filenum]=1,4 | |
| RT | ; Rotate operation |
| PIC{***[filenum]} | ; Input file |
| OUT{****[filenum]} | ; Output file |
| 45. | ; Rotation angle |
| ENDDO |
Here the same value (45.) is to be used for each iteration of the loop.
There are various methods to change the parameter values used on different iterations of the loop. For example to successively use the angles 45, 61 and 78 degrees in a RT operation loop with the pictures PIC001, PIC002, and PIC003:
| DO [filenum]=1,3 | |
| RR S [rotang] | ; Read values |
| 45, 61, 78 | ; List |
| [filenum] | ; Position within list (45,..) |
| RT | ; Rotate operation |
| PIC{****[filenum]} | ; Input file |
| OUT{****[filenum]} | ; Output file |
| [rotang] | ; Rotation angles |
| ENDDO |
| DO [filenum]=1,3 | |
| UD IC [filenum], [rotang] | ; Retrieve value |
| DOC001 | ; Document file that holds values |
| RT | ; Rotate operation |
| PIC{****[filenum]} | ; Input file |
| OUT{****[filenum]} | ; Output file |
| [rotang] | ; Rotation angles |
| ENDDO |
Procedure files can be used in many ways within SPIDER. One such use is to create a interactive procedure which prompts the user at the terminal for relevant input when necessary. This input can be customized by the procedure writer to correspond to the specific purpose of the procedure. To create this sort of interactive procedure file the user:
At execution time, the user-specified solicitation messages are the only messages that will appear on the terminal.
Example --- :
If the procedure TEST_INTER is called from an an interactive session and contains the following:
| AD |
| PIC001 |
| ?PICTURE TO BE ADDED? |
| OUT001 |
| * |
| RE |
Then SPIDER will 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 place the result in: OUT001, and will return to interactive input.
Frequently, one encounters the situation where more same information is required in the procedure more than once. SPIDER allows the user to associate a symbolic variable with any solicitation message (marked by a ?...? ). Later this symbolic variable can be used to instead of repeating the solicitation message.
Example --- :
If the procedure TEST_IVAR which needs to solicit the name of the unaligned image twice from the user is called from an an interactive session and contains the following:
| ; PROCEDURE TO ALIGN IMAGE WITH REFERENCE | |
| PD | |
| ?UNALIGNED IMAGE? [unaligned] | ; Set symbolic variable |
| PAD001 | ; Output image |
| 66,66 | ; Output image size |
| Y | ; Use average for padding value |
| 16,16 | ; Image location within output |
| PD | |
| ?REFERENCE IMAGE?[reference] | |
| PAD002 | ; Output image |
| 66,66 | ; Output image size |
| Y | ; Use average for padding value |
| 16,16 | ; Image location within output |
| AC | |
| PAD001 | ; Input image |
| ALI001 | ; Output image |
| AC | |
| PAD002 | ; Input image |
| ALI002 | ; Output image |
| OR 2 [angle] | |
| ALI001 | ; Input image |
| ALI002 | ; Reference image |
| 5,15 | ; First and last ring radius |
| 1 | ; Ring skip |
| F | ; Full circle |
| RT | |
| [unaligned] | : Reuse symbolic variable that was set above |
| ?OUTPUT IMAGE?[output] | |
| [angle] | |
| RE |
In the interactive session the user will enter:
| .OPERATION: @TEST_IVAR |
| .?UNALIGNED IMAGE?: PIC002 |
| .?REFERENCE IMAGE?: PIC003 |
| .?OUTPUT IMAGE?: OUT009 |
The second potential occurrence of ?UNALIGNED IMAGE? was avoided by reusing the [unaligned] symbolic variable, which was the symbolic variable assigned at the occurance of the ?UNALIGNED IMAGE? prompt.
Symbolic variables that represent a file name template may be modified at run time by appending the value from register variable. The specified digits of the filename are then replaced by new digits according to the current value in the register variable.
Example --- 1:
If the procedure TEST_NAME is called from an an interactive session and contains the following:
| ; Procedure to list file statistics for a file series |
| FR |
| ?ENTER IMAGE FILE TEMPLATE?[file_template] |
| DO [filenum]=2,5 |
| FS |
| [file_template][filenum] |
| ENDDO |
| RE |
and the user enters the following from an interactive session:
| @TEST_NAME |
| PIC*** |
In the DO-loop, PIC*** will then be replaced by PIC002,PIC003, ... , PIC010.
Example --- 2:
If the procedure TEST_NAME2 is called from an an interactive session and contains the following:
| ; Procedure to list file statistics for a file series |
| RR[filenum] |
| ?OUTPUT FILE NUMBER? |
| FI |
| PIC{***[filenum]} |
| RE |
and the user enters the following from an interactive session:
| @TEST_NAME2 |
| 5 |
Example --- 3:
If the procedure TEST_NAME3 is called from an an interactive session and contains the following:
| FR |
| ?ENTER FILE NAME TEMPLATE? [template] |
| RR[filenum] |
| ?PICK OUT FILE NUMBER?[filenum] |
| FS |
| [template][filenum} |
and the user enters the following from an interactive session:
| TEST_NAME3 |
| PIC*** |
| 3 |
In this example, the operation FS is applied to PIC003.
Normal register variables are local to a procedure and are independent the of register variables within other procedures. Register variables can be transferred from a calling procedure to a called procedure, using argument transfer or by using the operation: RR.
Most memory intensive operations make use of run time allocation (and deallocation) of necessary memory.
SPIDER contains Open Multiprocessing directives which can be used by OpenMP capable Fortran compilers. The MD operation with option: 'SET MP' can be used to control the number of processors used during SPIDER execution on such machines.
A few operations in SPIDER contain MPI parallelizing directives which can be activated by appropriate compilation. If you are interested in using MPI please contact us for further info.
Unix systems have queues available for scheduling execution of batch jobs and methods of placing a process in the background. Some old notes on this are contained in: batch-unix_doc.html.
Source: user_doc.html Last update: 27 Oct. 2018 ArDean Leith