ctfplotter(1)                                                    ctfplotter(1)



NAME
       ctfplotter - estimate defocus values of a tilt series

SYNOPSIS
       ctfplotter  options

DESCRIPTION
       This GUI program will plot the logarithm of a rotationally averaged
       power spectrum of an input tilt series after subtracting the noise
       floor.  The method is based on periodogram averaging; namely, averaging
       of spectra from small, overlapping areas of the images, referred to as
       tiles.  The user can interactively choose which projection views are
       included in the averaging.

       The noise floor is based on actual measurements of noise in an image
       taken with no specimen in the beam.  Thus, in order to use this pro-
       gram, you need to collect a set of such blank images, at a series of
       beam intensities, and place each image in a separate file.  These noise
       files are specific not only to the microscope but also to the CCD cam-
       era used, the operating voltage, and the binning.  The mean counts in
       these files should span the range of the mean counts in the data being
       analyzed.  The interval between intensities can be a factor of 1.5;
       interpolation is used to estimate the noise for an image whose mean
       counts do not match one of the noise files.  For example, for a camera
       that has a gain of 10 counts per electron, one might collect images at
       mean counts near 100, 150, 225, etc., up to 2210.  With a 1 nm pixel
       size, these noise files could be used with images where the dose
       recorded at the camera ranged from 0.1 to 2.2 electrons per square
       Angstrom.  If you need files for analyzing both unbinned and binned
       data, you can take one set of unbinned noise images and then bin them
       with a Newstack command like this:
          newstack -bin 2 -mult 4,0  input_file output_file

       The multiplication by 4 (the square of the binning factor) is necessary
       to make the counts be the same as they would be for binned images from
       the microscope with the same exposure.

       If there are significant numbers of X-rays in the noise images, you
       should clean them with Ccderaser, such as with:
          ccderaser -find -peak 8 -diff 6  input_file output_file

       The noise files must have positive means; i.e., their values should be
       proportion to the recorded electrons.  If they are acquired with soft-
       ware that subtracts 32768 before storing as signed integers, then you
       need to add this offset back to the data in order to use them as noise
       files.

       When you start the program, it will first load and analyze all of the
       noise files.  Then it will read in the images within the specified ini-
       tial angular range and compute power spectra from the central tiles.
       This initial computation of tile power spectra is the most time-consum-
       ing step, whereas recomputing a summed power spectrum from the spectra
       of individual tiles is quick.  The program thus stores the power spec-
       trum for each tile in a cache when it is computed.  You will have to
       wait several seconds whenever you add non-central tiles from the cur-
       rent angular range, or when you change the angular range to include
       views that have not been analyzed before.  However, once all of the
       tiles on all views have been analyzed, the program will respond quickly
       when you change angular ranges or defocus values.

       To read a general description of the plots and tool buttons, click the
       handbook icon to access the HTML help page.

       Found defocus values can be saved in a text file that can be used as
       input to the CTF correction program ctfphaseflip.

       A sample command file for running the program at the command line can
       be found in the IMOD/com directory.


   Options
       Ctfplotter 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 -):

       -input OR -InputStack     File name
              Input stack whose defocus will be estimated.

       -angleFn OR -AngleFile    File name
              File containing tilt angles for the input stack.  Each line of
              this file is the tilt angle for a view of the input stack.  The
              angles are listed in order starting from view 1.

       -invert OR -InvertTiltAngles
              Invert the sign of the tilt angles to compensate for a left-
              handed coordinate system in the microscope.  When the sign of
              the tilt angles and the value of the tilt axis rotation angle
              are such that reconstructions are generated with inverted hand-
              edness, then this option is needed to keep power spectra for
              off-center tiles from being shifted in the wrong direction.

       -offset OR -OffsetToAdd   Floating point
              The program must analyze data values where 0 corresponds to no
              electrons recorded.  Use this option to specify a value to add
              to your input stack that will make values positive and propor-
              tional to recorded electrons.  The value will not be added to
              noise files; they are required to be positive.  The program
              automatically sets this value to 32768 if it recognizes a file
              from FEI data acquisition software with a minimum below 0, or if
              the minimum and mean of a non-FEI file are sufficiently nega-
              tive.

       -config OR -ConfigFile    File name
              The configure file specifies the noise files used to estimate
              the noise floor, one file per line.  The files can be specified
              with either absolute paths or with paths relative to the loca-
              tion of the configure file itself.

       -defFn OR -DefocusFile    File name
              File to store found defocuses.  Each entry in the file will con-
              sist of the starting and ending view number of the range of
              views being fit to (numbered from 1), the starting and ending
              angle of the tilt angle range being fit to, and the defocus
              value in nanometers (underfocus positive).  If this file already
              exists when the program starts, it will be read in and the
              results displayed in a table in the Angle Range and Tile Selec-
              tion dialog.  The previous version will become a backup file
              (with ~ added to its name) when new results are saved to this
              file.

       -aAngle OR -AxisAngle     Floating point
              Specifies how much the tilt axis deviates from vertical (Y
              axis).  This angle is in degrees.  It follows the right hand
              rule and counter-clockwise is positive.

       -psRes OR -PSResolution   Integer
              The number of points over which CTF will be computed.  The
              Nyquist frequency is divided into equal intervals delineated by
              these points.

       -tileSize OR -TileSize    Integer
              The tile size each strip will be tessellated into.  The size is
              in pixels and the tiles are square.  Each view is first divided
              into strips that are considered to have constant defocus.

       -volt OR -Voltage    Integer
              Microscope voltage in kV.

       -cache OR -MaxCacheSize   Integer
              To speed up computation, ctfplotter uses a cache to hold the
              rotationally averaged power spectra of individual tiles at 20
              times the final power spectrum resolution.  This option controls
              the cache size.  The default value is 1000 megabytes, which
              should be enough for all slices in a 4Kx4K tilt series with the
              default tile size.

       -cs OR -SphericalAberration    Floating point
              Microscope spherical aberration in millimeters

       -defTol OR -DefocusTol    Integer
              Defocus tolerance in nanometers defining the center strips.  The
              center strips are taken from the central region of a view that
              has defocus difference less than this tolerance.  These kind of
              center strips from all views within AngleRange are considered to
              have a constant defocus and are used to compute the initial CTF
              after being further tessellated into tiles.

       -pixelSize OR -PixelSize       Floating point
              Image pixel size in nanometers.

       -ampContrast OR -AmplitudeContrast       Floating point
              The fraction of amplitude contrast. For Cryo-EM, it should be
              between 0.07 and 0.14.

       -expDef OR -ExpectedDefocus    Floating point
              Expected defocus at the tilt axis in nanometers, with a positive
              valie for underfocus.  The frequency of the first zero of the
              CTF curve is first computed based on this expected defocus.  The
              segments of the CTF curve of the input stack around that fre-
              quency are selected to be fitted.

       -leftTol OR -LeftDefTol   Floating point
              Defocus tolerance in nanometers for strips to the left of the
              center strip.  When non-center strips are included in the aver-
              age, strips to the left of center are included if their defocus
              difference is less than the given value.

       -rightTol OR -RightDefTol      Floating point
              Defocus tolerance in nanometers for strips to the right of the
              center strip.  When non-center strips are included in the aver-
              age, strips to the right of center are included if their defocus
              difference is less than the given value.

       -range OR -AngleRange     Two floats
              Starting and ending tilt angles for initial analysis.  Views
              with a tilt angle within this range are used to compute the CTF
              curve.

       -debug OR -DebugLevel     Integer
              Debug level, 0-3. 0: quiet.  1: user messages.  2: cache, tile
              iteration messages.  3: additional fitting messages. the default
              is 1.

       -param OR -Parameter      Parameter file
              Read parameter entries from this file.

       -StandardInput
              Read parameter entries from standard input


AUTHORS
       Quanren Xiong
       David Mastronarde

SEE ALSO
       ctfphaseflip

BUGS
       Prior to IMOD 4.0.29, Ctfplotter had a bug in which the view numbers
       written to the defocus file were numbered from 0, not 1.  When Ctfplot-
       ter reads in an existing defocus file, it will do its best to detect
       this situation and adjust all the view numbers up by 1.  If it does
       detect an inconsistency between view numbers and angular ranges, it
       will issue a warning.

       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.3.7                       ctfplotter(1)