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
       proportional to the recorded electrons.  If they are acquired with
       software 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.

       The noise files are listed in a simple text file, the configuration
       file specified by the -config option.  To be found easily from within
       eTomo, the latter file should be placed in a directory named
       /usr/local/ImodCalib/CTFnoise or in $IMOD_CALIB_DIR/CTFnoise if the
       environment variable IMOD_CALIB_DIR has been defined differently from
       the default.  You can then place the noise files in a subdirectory of
       CTFnoise, for example, F20.  In this case, the configuration file would
       contain a list like this:
       F20/file1.st
       F20/file2.st
       F20/file3.st

       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 -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

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

       -angleFn (-an) 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 (-inv) 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.  One
              way to assess this need is to examine the images in a stack
              aligned for reconstruction, with the tilt axis vertical.  At
              positive tilt angles, the right side of the images should be
              more underfocused than the left side; if not, then this option
              is needed.

       -offset (-o) 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 (-co) 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 (-defF) 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).  When the program
              writes a new defocus file, it puts a version number (currently
              2) at the end of the first line.  If this file already exists
              when the program starts, it will be read in and the results dis-
              played in a table in the Angle Range and Tile Selection dialog.
              The previous version will become a backup file (with ~ added to
              its name) when new results are saved to this file.  If you sup-
              ply an initial defocus file with more than line, be sure to use
              the exact angles from the tilt angle file specified with
              -angleFn; do not round to one decimal place.  Alternatively, add
              the number "2" as an extra value at the end of the first line of
              the file; this will prevent the program from thinking that the
              view numbers might be off by one.

       -aAngle (-aA) 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 (-ps) 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.  The default is 101.

       -tileSize (-t) 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.  The
              deafult is 256.

       -volt (-vo) OR -Voltage   Integer
              Microscope voltage in kV.

       -cache (-ca) 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.  A value of 0
              can be entered; it will be made slightly larger to prevent divi-
              sion by 0 in the CTF equations.

       -defTol (-defT) 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.  The default is 200.

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

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

       -expDef (-e) OR -ExpectedDefocus    Floating point
              Expected defocus at the tilt axis in nanometers, with a positive
              value 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
              frequency are selected to be fitted.

       -leftTol (-l) 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.  The default is 2000.

       -rightTol (-ri) 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.  The default is 2000.

       -range (-ra) OR -AngleRange    Two floats
              When the -autoFit option is not entered, this entry sets the
              starting and ending tilt angles for the initial analysis and is
              a required entry.  Views with a tilt angle within this range are
              used to compute the CTF curve.  When -autoFit is entered, this
              entry sets the extent over which steps will be taken in aut-
              ofitting.

       -autoFit (-au) OR -AutoFitRangeAndStep   Two floats
              Do initial autofitting over the whole tilt series with the given
              range of angles and step size between ranges.  A value of zero
              for the step will make it fit to each single image separately,
              regardless of the value for the range.  This autofitting differs
              from that invoked through the Angles dialog in several respects:
              1) All tiles will be used for fits; the "All tiles" radio button
              will be selected at the end. 2) Three fitting iterations will be
              done, with the expected defocus used the first time and the cur-
              rent defocus estimate used for the next two iterations.  3) The
              size of the range is determined by the parameter entered here,
              not by the starting and ending angles entered with the -range
              option.

       -frequency (-fr) OR -FrequencyRangeToFit      Two floats
              Starting and ending frequencies of range to fit in power spec-
              trum.  The two values will be used to set the "X1 starts" and
              "X2 ends" fields in the fitting dialog.

       -vary (-va) OR -VaryExponentInFit
              Vary exponent of CTF function when fitting a CTF-like curve

       -save (-s) OR -SaveAndExit
              Save defocus values to file and exit after autofitting.  The
              program will not ask for confirmation before removing existing
              entries in the defocus table.

       -debug (-deb) 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 (-pa) OR -Parameter     Parameter file
              Read parameter entries from this file.

       -fpOffset (-fp) OR -FocalPairDefocusOffset    Floating point
              Normally, ctfplotter processes a single stack whose name is
              given by InputStack. It can optionally process a pair of stacks
              with identical til angles and mutually aligned projections,
              taken with a constant defocus offset between them. If, for exam-
              ple, InputStack is myData.st, one could place a stack with 6 um
              underfocus in myData_1.st and a stack with 2.175 um underfocus
              in myData_2.st and specify an ExpectedDefocus of 6000 and a
              FocalPairDefocusOffset of -3825.

       -StandardInput
              Read parameter entries from standard input


AUTHORS
       Quanren Xiong
       David Mastronarde
       John Heumann

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.7.3                       ctfplotter(1)