excludeviews(1)                                                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 is not entered, the first non-option argument will
              be taken as the image stack name.

       -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                                 4.9.5                     excludeviews(1)