excludeviews

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)