excludeviews(1) General Commands Manual excludeviews(1)
NAME
excludeviews - Reversibly remove views from a tilt series stack
SYNOPSIS
excludeviews options stack_name
DESCRIPTION
Excludeviews removes images from a stack, saves them in another stack,
and replaces the original stack with one without those images. This
operation is most useful for excluding views from a tilt series. It
works with montaged or single-frame images. Information about the
operation is kept in a file with extension ".info"; this allows the
operation to be run in reverse to restore the original image file.
Because of this reversibility, it is safe to remove the original files
with the -delete option.
The program can be run repeatedly (up to 100 times), and each succes-
sive exclusion is similarly reversible. This capability is achieved by
including an iteration number in the names of the ancillary files pro-
duced on each run. The program searches for the info file with the
highest number and applies the next highest number in another exclu-
sion, or restores the exclusion on that iteration. When running a new
exclusion, the list of views entered are numbered by their positions in
the current stack, not the original one.
Ancillary data are always preserved in both directions of operation.
Specifically, if there is a ".rawtlt" file with tilt angles or a
".mdoc" file with metadata, it will be split in two or recombined
appropriately. If the stack is identified as a montage by internal
data or by giving the -montage option, a ".pl" file with piece coordi-
nates will also be split or recombined. Metadata will also preserved
appropriately when the input and/or output files are HDF files; specif-
ically, metadata in an HDF file will be placed into an .mdoc file when
the output is MRC type, metadata in a .mdoc file associated with an MRC
file will be stored as attributes when the output is an HDF file; and
attributes will be transferred between HDF files with appropriate modi-
fications. This transfer is accomplished with the -mdoc option to New-
stack(1) or Edmont.
OPTIONS
Excludeviews uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-stack (-s) OR -StackName File name
Name of the image stack to operate on, from which a rootname and
extension can be derived. However, if restoring with the -orig
option, this should be the rootname and extension without the
"_orig". This is a required entry; if it is not entered with
this option, the first non-option argument will be taken as the
image stack name.
-altstack (-a) OR -AlternateStackName File name
Name of the alternate image stack to operate on, applying the
same sequence of exclusions that have been done previously on
the main image stack. The name should include the extension.
If exclusions have already been done on the alternate stack but
more iterations have been done on the main stack, the additional
exclusions will be applied. Old files are deleted on a particu-
lar iteration if the "_allviews" stack is not present for the
main stack. The Z size of the alternate stack must match the
size in the info file for the first exclusion iteration to be
applied. No other entries besides -stack are allowed when this
option is given.
-views (-v) OR -ViewsToExclude List of integer ranges
List of views to exclude, numbered from 1. This entry is
required unless -restore is entered. When restoring a stack, it
is not necessary to enter the view list, and it is better not
to, if an info file is present from when the views were first
excluded. However, if there is no info file, a view list is
needed; this would be the original list of views given for the
exclusion.
-montage (-m) OR -MontagedImages
The image stack consists of montaged images. If this option is
not entered, the program will detect whether a file is a montage
automatically, if the piece coordinates are contained in the
header of an MRC file, the attributes of an HDF file, or an
associated ".mdoc" file (one whose name consists of the stack
name plus ".mdoc"). Thus, this entry is not needed unless the
piece coordinates are contained only in a piece list file. It
is also not needed when restoring a stack if there is an info
file present.
-delete (-d) OR -DeleteOldFiles
Delete the redundant image and associated files after an opera-
tion is successfully completed instead of retaining them.
Specifically, after excluding views, the original image stack
and any associated files that are replaced are renamed with
"_allviews#" by default (where "#" is the iteration number), and
will be deleted with this option. After restoring excluded
views, the existing files are renamed with "_keptviews#" by
default; whereas with this option, both these files and the ones
for excluded views named with "_cutviews#" will be deleted.
-restore (-r) OR -RestoreFullStack
Combine retained views in the current stack file with excluded
views in the latest "_cutviews#" file to restore the full stack
present before the last iteration. If an info file is present,
the -views and -montage options should not be entered. If
-views is entered, the info file is ignored and -montage will be
needed if piece coordinates are only in a piece list file. If
multiple iterations of exclusion have been run, the program
needs to be run with this option that number of times to get
back to a stack with all of the original views.
-orig (-o) OR -OriginalStack
Restore excluded views into the original stack before X-ray
removal. By default, the current file entered with -stack will
be combined with the excluded views; with this option, the orig-
inal file "rootname_orig.ext" will be combined with the excluded
views and the combined file will be given that name.
-PID Print process ID
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
Three different strings are inserted before the extension to identify
files on a particular run, where "#" is the iteration nunber:
"_cutviews#" for views removed from a stack; "_keptviews#" for the
retained views, "_allviews#" for a file with all the views. The info
file on iteration # is named "rootname_cutviews#.info". After an oper-
ation is reversed, the info file is renamed to "root-
name_cutviews#_old.info".
AUTHOR
David Mastronarde
SEE ALSO
newstack, edmont
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 excludeviews(1)