vmstopy(1) General Commands Manual vmstopy(1)
NAME
vmstopy - converts IMOD command file to Python script
SYNOPSIS
vmstopy [option] com_filename log_filename [output_file]
DESCRIPTION
Vmstopy is a Python program for converting an IMOD command file into a
Python script that will run commands in the file and direct output to a
log file. Commands can consist of a single line running a program with
command line arguments, or a line running a program followed by entries
that the program will read from standard input. Python statements can
also be included in the file, and variables can be defined in Python
then used in the command or standard input lines. A small number of C-
shell commands will also be recognized and translated to the appropri-
ate Python statements.
The easiest way to use this program is through the submfg script
together with an alias to run submfg in the background, which is pro-
vided in the IMOD startup scripts as the alias subm. If you command
file is named "stuff.pcm", you can give the command "subm stuff". If
it is named with a different extension, such as the traditional ".com",
you need to indicate that the command file is to be run into vmstopy by
using "subm -p stuff". In either case, the file will be executed in
background, a log file stuff.log will be created, and you will be noti-
fied when the job is completed. Type "submfg" to see the usage state-
ment for more details.
Special Characters
Four special characters are used:
$ at the start of a command line. Commands may be continued on multi-
ple lines by ending each line except the last one with a backslash (\).
The continuation lines should not start with a $
> at the start of a Python statement
% for a variable to be substituted; this may occur anywhere in a com-
mand line or a standard input line. Variable substitution will always
convert the variable to a string, so the value can be an unquoted
string or a simple numeric value. Lists of numbers should be quoted
(e.g., '1-5').
# at the start of a line with a comment. A # later in a line will not
be recognized as starting a comment. $! at the start of a line is also
recognized as a comment
Standard input lines do not start with a special character. The pro-
gram will consider any lines between a command line and the next com-
mand line or Python statement as lines to be fed to the command's stan-
dard input.
Indentation and Quoting
If there are any Python statements starting with >, then indentation is
significant, not only in the Python statements but also in the command
lines. Any commands that occur in a Python block must have the appro-
priate indentation; i.e., with extra indentation if they follow a
statement that starts a block; with the same indentation as the last
statement if it is part of the same block, or with less indentation if
it ends a block. A line with a command to run must have the $ in the
first column, and then the appropriate number of spaces of indentation
before the command. If you use no Python at all, spaces between the $
and the command will be removed from command lines to avoid indentation
errors. Lines for standard input to programs need not be indented.
The program will enclose the text that used to run a command, in single
quotes (' ') and text that is input to programs in triple quotes ("""
"""). If you need to pass a command line argument containing spaces to
a program, enclose it in double quotes (" "). Do not escape spaces
with backslashes. Backslashes should appear only in Windows file
paths. These will be converted to forward slashes.
Translations
The following translations will occur. Some of these are generally
useful, some are needed to support constructs in existing command files
for tomogram processing.
$goto label
will skip forward to the next command line starting with
$label:
Unlike in C-shell, the goto can be used only to skip forward, and it
cannot be part of a conditional statement. The goto's and labels are
recognized and removed in a first pass through the command file. Any
more complicated conditional execution must be coded with Python state-
ments.
$if (-e file) command
will be converted to
> if os.path.exists(file):
$ command
$if (! -e file) command
will be converted to
> if not os.path.exists(file):
$ command
In either of these cases, if "file" is quoted with either single or
double quotes, it can contain spaces.
$set tmpdir =
and the 1-3 following lines will replaced by
> tmpdir = imodTempDir()
provided that either the following line contains "settmpdir", or the
next three lines contain "if", "settmpdir", and "endif"
$set variable = value becomes >variable = value
and "value" is quoted unless it can be assigned to a numeric variable
If "$set" has been used at all, $variable will be substituted just like
%variable.
$setenv variable value becomes >os.environ['variable'] = 'value'
This is generally to set the environment for programs that will be run,
but these and other environment variables may be accessed within the
command file provided that they are all upper case (A-Z, 0-9, and
underscore are allowed) and enclosed in braces. In other words,
${ENV_VAR} becomes os.environ('ENV_VAR').
\rm, \rm -f, rm, and rm -f all become b3dremove -g
cp or \cp become b3dcopy, and if the following line has a chmod, -p
is added to the b3dcopy
\rm -r, \rm -rf, rm -r and rm -rf are all replaced by a call to
shutil.rmtree
mkdir is replaced by a call to os.mkdir
\mv becomes mv -f
$if (-e file) mv file file~ is replaced by a call to the makeBackup-
File function
$echo text becomes >print "text" after substituting variables in
"text"
$exit
will cause the rest of the command file to be skipped, whereas
$exit n
will result in calling a function that terminates with sys.exit(n), but
further lines will be processed.
>print "text" becomes >prnstr("text", file=log)
In other words, in Python statements, print commands not directed to a
file will be redirected to the log file. prnstr is function that works
for printing with both Python 2.x and Python 3.x.
b3dremove becomes b3dremove -g on Windows
On other systems, wildcards in the filename list are expanded by the
shell that runs the command, but on Windows, b3dremove needs to glob
the filenames.
$if ($status) goto label
When this construct is present, the program will collect lines between
"label:" and "exit n" and move them into a function. When the con-
struct is encountered after running a command, a call to the function
is inserted in the exception handler for the command.
$vmstocsh com.log < com.com
When this construct is encountered, the line containing it, through a
line containing "csh -ef", are replaced with commands to run vmstopy
and to run the resulting script.
`hostname` is substituted with the computer hostname upon execution;
Note that "hostname" must be enclosed in back-quotes (as for command
execution in a shell); this character may not appear properly here.
$$ is replaced by the PID of the Python running the command file
Certain commands are eliminated from the command file:
$set nonomatch
$matchshifts
$sync (on Windows)
OPTIONS
-x Execute the script with a new Python instance.
-q Suppress output messages about the progress of running the
script.
-c Output "CHUNK DONE" to the log file after successful execution.
-e VAR=val
Set the environment variable VAR to the given value at the
beginning of the script. If no value is needed, "-e VAR" can be
entered. This option can be entered as many times as needed.
-f dir Add the given directory to the front of the system path. This
command may be entered multiple times, or multiple directories
can be included in one entry with the path separator, unless
they are Windows paths that need conversion to Cygwin paths.
-b dir Add the given directory to the back of the system path. This
command may be entered multiple times, or multiple directories
can be included in one entry with the path separator, unless
they are Windows paths that need conversion to Cygwin paths.
-k Keep backslashes in input lines instead of converting them to
forward slashes. Backslashes are converted to ensure that file-
names are processed properly in Windows, but this option can be
used in other situations where it is necessary to pass back-
slashes in text strings.
-n # Increment the process niceness by the given # at the beginning
of the script.
-p Set permissions of the output script file to executable.
-t Run in test mode where all commands are prefixed by "echo2"; the
output should be runnable in Python.
EXAMPLES
# Example 1: Command file to align an image stack
# Note the comments embedded in the input to xftoxg
#
$xftoxg
0 global fit
# Name of input file
g5a.prexf
# Name of output file
g5a.prexg
$newstack -fl 2 -mo 0 -xf g5a.prexg g5a.st g5a.preali
# Example 2: Command file to split a stack into two sets of files
# Note the indentation for Python and command lines
#
>for i in range(100):
> if i % 2:
$ newstack -sec %i data.st oddsec.%i
> else:
$ newstack -sec %i data.st evensec.%i
$header data.st
>print "Splitting done"
AUTHOR
David Mastronarde, mast at colorado dot edu
SEE ALSO
vmstocsh
HISTORY
Why vms and subm? Parts of IMOD started under the VMS operating sys-
tem. The ability to submit command files in this kind of format to a
queue and get a log file with the output was the one good feature of
VMS.
IMOD 5.2.0 vmstopy(1)