ctfphaseflip

ctfphaseflip(1) General Commands Manual ctfphaseflip(1)
NAME
 ctfphaseflip - correct tilt series for microscope CTF by phase flipping
SYNOPSIS
 ctfphaseflip options
DESCRIPTION
 This program will correct the CTF of an input tilt series by phase
 flipping, with an option to attenuate frequencies near the zeros of the
 CTF. The user can select a subset of projection views of the input
 tilt series to correct and can specify a defocus value for each
 selected view through a text defocus file. The output file of Ctfplot-
 ter(1) is usually used as the defocus file.
 Ctfphaseflip corrects each view strip by strip. A strip is defined as
 an image region whose defocus difference is less than a user specified
 value, the defocus tolerance. Normally, the strips are vertically ori-
 ented and defocus is assumed to be the same along a vertical line.
 Thus, the tilt series must be aligned so that the tilt axis is vertical
 before applying this correction. The original thinking was that an
 image region with defocus difference less than the tolerance could be
 considered to have constant defocus and could be corrected as one
 strip. However, the validity of the correction at the center of the
 strip probably does not depend on whether it contains material beyond
 this focus range, since only vertical lines near or at the center are
 used in the corrected image. The program may limit the width further
 to reduce computation time, or expand it to retain enough resolution
 between successive zeros in the X direction of frequency space.
 Through most of the image, each strip is corrected based on the defocus
 at the center of the strip. However, the strips at the left and right
 edges of the image may be corrected repeatedly, at different defocus
 values, in order to extend the correction close enough to the edges of
 the image. In fact, it is possible with the -maxWidth option to make
 the program correct only whole images, using the defocus value appro-
 priate for successive positions across the image.
 Two entries can make the program correct along diagonals instead of
 vertical strips: a tilt around the X-axis (more specifically, the one
 orthogonal to the tilt axis), and a rotation of the tilt axis from ver-
 tical. The latter would be entered if unaligned images are being cor-
 rected. If only a tilt axis rotation is entered, the diagonal strips
 are at that angle. If an X axis tilt is entered, the diagonals are at
 an angle that depends on the angle of tilt around the tilt axis. In
 either case, full images will be corrected to obtain the diagonal
 strips at different defocus.
 Ctfphaseflip can be run in a parallel mode similiar to the Tilt pro-
 gram by setting the -TotalViews option. The script Splitcorrection
 can be used to prepare command files for running the program in paral-
 lel. It can also be run on the GPU of an NVIDIA card.
 A sample command file for running the program with "subm" can be found
 in the IMOD/com directory (ctfcorrection.com).
 Originally, the program limited strip widths to 256, but the power
 spectra of low tilt images often showed rings of very low values right
 around the zeros of the CTF. As of IMOD 4.8.17, the strip width is
 limited dynamically in a way that should minimize this effect. Making
 the strips wider eliminates or reduces this effect, provided that the
 shift in the position of the first zero across the width of the strip
 is big enough. At very low tilt, the maximum allowed width is
 increased to a value that would make the first zero shift by 0.6 pixel
 in the Fourier transform. At higher tilts, the criterion shift is
 reduced by (1 - tan(tiltAngle)). Near zero tilt, the strip width is
 simply half of the image size in X. (However, if tilt is exactly zero,
 the program does only a single correction of the whole image.) The
 spacing between adjacent strips is also adjusted to be larger for wider
 strips, to keep the computational time down (see the -iWidth option
 below).
OPTIONS
 Ctfphaseflip 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 that will be corrected. It must be aligned so that
 the tilt axis is vertical.
 -output (-o) OR -OutputFileName File name
 Name of output file for the corrected views
 -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. If no file is
 entered, angles will be assumed to be 0. If all views have tilt
 angles of 0, the program will do a single correction of the full
 image for each view instead of doing strips.
 -invert (-inv) OR -InvertTiltAngles
 Invert the sign of the tilt angles in the tilt angle file. In
 general, this option is needed if Ctfplotter was also run
 with its -invert option. See the section on Inverting Tilt
 Angles in the Ctfplotter man page for details.
 -axis (-ax) OR -AxisAngle Floating point
 Angle that the tilt axis is rotated from vertical (counterclock-
 wise positive), for correcting unaligned images in their origi-
 nal orientation.
 -xtilt (-xt) OR -XAxisTilt Floating point
 Angle (counterclockwise positive) that the specimen is tilted
 around the axis in the plane perpendicular to the tilt axis,
 which is along the X axis in aligned images. This angle should
 correspond to the X axis tilt found in the positioning step in
 Etomo. With an X axis tilt, the program will process full
 images instead of strips, interpolating or copying corrected
 pixels along diagonals of constant focus. This option can be
 entered with an axis rotation angle for correcting unaligned
 images, but in that case the angle entered here must be for a
 tilt around a corresponding rotated axis, not around the X axis
 in the images.
 -defFn (-defF) OR -DefocusFile File name
 File with list of tilt angle ranges and defocus values in
 nanometers, such as was output by Ctfplotter. The full spec-
 ification of the defocus file is given below. Each line should
 have a starting and ending view number (numbered from 1), a
 starting and ending tilt angle, and a defocus value. Defocus is
 in nanometers, with positive values for underfocus. The program
 will assign that defocus value to the midpoint of the range of
 views. For a view at a given tilt angle, it will find the defo-
 cus either by interpolating between two surrounding midpoint
 angles, if there are such angles, or by taking the nearest defo-
 cus value, if the angle is beyond the range of the available
 midpoint angles. To correct a tilt series with a single value
 of defocus, supply a file with a single line containing "20 20
 0. 0. defocus_value". If you prepare a defocus file with more
 than one line, be sure to use the exact angles from the tilt
 angle file specified with the -angleFn option; 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. If you use the -invert option, you must do one of
 two things: 1) either invert all the tilt angles in this file,
 2) or start the file with a line indicating that it is a version
 3 file in which the angles need to be inverted (start the line
 with the flag 16 for inversion, plus whatever other flags are
 needed; see below).
 -zoff (-zo) OR -OffsetInZ Floating point
 Adjust defocus values for the given displacement in Z, in pix-
 els. The default CTF correction is correct only for image data
 in the middle of the specimen. With this entry, each defocus
 value will be adjusted to be correct for positions higher or
 lower in Z. When viewing a tomogram in its original X/Z slices,
 a Y value below the center corresponds to a positive Z displace-
 ment. The sign of this entry is thus the same as the sign of Z
 in a SHIFT entry to Tilt to bring this position to the middle
 of the tomogram. However, the SHIFT entry is in unbinned pixels
 whereas the entry to this option is in actual pixels of a tomo-
 gram (i.e., binned pixels if the aligned stack is binned).
 -xform (-xf) OR -TransformFile File name
 File with the linear transformations that were used to align the
 images. Using this option has two consequences: 1) Astigmatism
 angles found by analyzing the raw stack will be properly rotated
 to the right angles for the aligned stack. If this option is
 not entered, astigmatism must be found on the aligned stack. 2)
 The program will use the shifts in X to adjust the middle posi-
 tion that is considered to be at the nominal defocus value for
 each image.
 -defTol (-defT) OR -DefocusTol Integer
 Defocus tolerance in nanometers, which is one factor that gov-
 erns the width of the strips. The actual strip width is based on
 the width of this region and several other factors: a fixed min-
 imum width of 128, a minimum width required to achieve suffi-
 cient resolution in the Fourier transform, governed by the -zero
 option, and the dynamic adjustment of maximum width described
 above. This width also determines the width of the strips on
 either edge of the image where a correction at just one defocus
 is used.
 -maxWidth (-m) OR -MaximumStripWidth Integer
 Maximum width of strips in pixels. This entry disables the
 dynamic adjustment of maximum width described above and applies
 a fixed maximum at all tilt angles. As a special case, a width
 at least as wide as the full image size in X will make the pro-
 gram do each correction on full images instead of strips.
 -iWidth (-iW) OR -InterpolationWidth Integer
 The distance in pixels between the center lines of two consecu-
 tive strips. A pixel inside the region between those two center
 lines resides in both strips. As the two strips are corrected
 separately, that pixel will have 2 corrected values. The final
 value for that pixel is a linear interpolation of the 2 cor-
 rected values. If a value of 1 is entered, there is no such
 interpolation. For a value greater than one, the entered value
 will be used whenever the strip width computed from the defocus
 tolerance is less than 256 (i.e., at high tilt), and the value
 will be scaled proportional to the strip width for widths above
 256. This scaling keeps the computational time down and is rea-
 sonable because the defocus difference between adjacent wide
 strips at wider intervals is still less than that between the
 narrower strips at high tilt. However, strips at constant spac-
 ing can still be obtained by entering the negative of the
 desired spacing, which disables the scaling of the spacing.
 -zero (-ze) OR -MinimumZeroSpacing Floating point
 The minimum spacing between successive zeros at 0.4/pixel, in
 pixels of frequency space. If necessary, the strip width will
 be increased above the value required by the defocus tolerance
 to maintain this much resolution in the Fourier transform at
 high frequency. If a maximum width is entered with -maxWidth,
 however, strips will not be wider than that maximum. A higher
 number decreases the fraction and the width of frequency pixels
 that straddle a zero. The default is 8.
 -pixelSize (-pi) OR -PixelSize Floating point
 Image pixel size in nanometers
 -expanded (-e) OR -ExpandedByFactor Floating point
 Value of ExpandByFactor used in Newstack when making aligned
 stack, which will be used to scale the pixel size.
 -volt (-vo) OR -Voltage Integer
 Microscope voltage in kV
 -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.
 -ampContrast (-am) OR -AmplitudeContrast Floating point
 The fraction of amplitude contrast. For Cryo-EM, it should be
 between 0.07 and 0.14. The value should be the same as was used
 when detecting the defocus.
 -degPhase (-deg) OR -PhaseShiftInDegrees Floating point
 A fixed value for the phase shift imposed by a phase plate, in
 degrees. It can be entered with either positive or negative
 sign; the absolute value of the entered value will be subtracted
 when computing phase within the program. This entered value
 will be overridden by the presence of any view-specific phase
 shift values in the defocus file.
 -phase (-ph) OR -PhasePlateShift Floating point
 A fixed value for the phase shift imposed by a phase plate, in
 radians. See the -degPhase option, which should be used
 instead. The two may not both be entered.
 -cuton (-cu) OR -CutOnFrequency Floating point
 A fixed value for cut-on frequency that attenuates phase at low
 frequency, in reciprocal nanometers. With a cut-on frequency,
 the phase is modeled as rising exponentially from zero at zero
 frequency to its true value at high frequency. The ratio of the
 first zero to the cut-on frequency is the rate constant of the
 exponential decay to the true value. Whenever the cut-on fre-
 quency is non-zero, the phase shift value used for a view, from
 either the defocus file or the -phase entry, will be treated as
 the phase at a fixed frequency of 0.3/nm rather than the shift
 at infinite frequency. See the Guide to Ctfplotter for more
 details about cut-on.
 -scale (-sc) OR -ScaleByCtfPower Floating point
 Scale frequency components by calculated CTF to the given power,
 in order to attenuate frequencies near the zeros of the CTF.
 The scaling does not occur below 0.9 times the frequency of the
 first zero, and it is introduced gradually between that point
 and the first zero to avoid a sharp transition in scaling.
 Lower powers give a narrower range of frequencies over which the
 strongest attenuation occurs around each zero; values of 0.25 to
 1 may be useful. This is not a Wiener filter; it will only
 attenuate signals and not boost any.
 -gpu (-g) OR -UseGPU Integer
 Use the GPU (graphical processing unit) for computations if pos-
 sible; enter 0 to use the best GPU on the system, or the number
 of a specific GPU (numbered from 1). If the GPU is not avail-
 able, the program will use the CPU or take the action specified
 by the -action option if that is entered. The program will
 respond in the same way if a failure occurs in the initial GPU
 access for each slice, where memory allocation is done, but for
 any GPU errors after that, it will exit with an error message.
 -action (-ac) OR -ActionIfGPUFails Two integers
 The action to take when the GPU cannot be used after being
 requested: 0 to take no action, 1 to issue a warning prefixed
 with MESSAGE:, and 2 to exit with an error. Enter 2 numbers:
 the first for the action when the GPU is requested by the UseGPU
 option; the second for the action when the GPU is requested only
 by the environment variable IMOD_USE_GPU, or by the variable
 IMOD_USE_GPU2. The default is 0,0.
 -views (-vi) OR -StartingEndingViews Two integers
 The starting view and the ending view to correct in this run of
 the program, numbered from 1. This is an optional field. The
 default is to correct all views in the input stack.
 -totalViews (-t) OR -TotalViews Two integers
 The starting view and the ending view that need to be corrected
 in all parallel runs of the program. This field is only needed
 when doing parallel runs with direct writing to a single output
 file. The program is run initially with a StartingEndingViews
 entry of -1,-1 to set up the output file. Then it is run with
 actual starting and ending views for each parallel run, and each
 run writes to the existing output file.
 -boundary (-b) OR -BoundaryInfoFile File name
 Name of file with information about boundaries between chunks
 and files in which to write lines at the boundaries, when multi-
 ple runs are writing in parallel to an output file.
 -skipFlag (-sk) OR -SkipCorrectedFlag Integer
 1 to not set flag that CTF was corrected, 2 to ignore flag if
 set, 3 for both
 -debug (-deb) OR -DebugOutput Integer
 Value to control debug output: 1 for timing, 2 for column
 detail, 0 for neither; add 10 to suppress initial list of angles
 and defocus values.
 -param (-pa) OR -Parameter Parameter file
 Read parameter entries from this file.
 -help (-h) OR -usage
 Print help output
 -StandardInput
 Read parameter entries from standard input
 Defocus File Format
 The defocus file consists of a series of lines, each containing at
 least 5 numbers: starting and ending view numbers for the range of
 views fit to (numbered from 1), starting and ending tilt angles for the
 range of angles fit to, and the defocus value in nanometers (underfocus
 positive). The first line of the file can have a version number at the
 end. For versions 1 and 2, the first line must have fitting data as
 well. The typical file currently written by Ctfplotter thus starts
 with lines like
 61 61 -58.94 -58.94 4376 2
 60 60 -56.94 -56.94 4599
 A version 3 file can have columns for astigmatism values, or the phase
 shift from a phase plate, including an optional cut-on frequency, or
 both. Past version 2, the first line is a header line without data.
 Thus a version 3 file should start with
 flags 0 0. 0. 0 3
 where "flags" is the sum of:
 1 if the file has astigmatism values
 2 if the astigmatism axis angle is in radians, not degrees
 4 if the file has phase shifts
 8 if the phase shifts are in radians, not degrees
 16 if tilt angles need to be inverted to match what the
 program expects (what Ctfplotter would produce)
 with the -invert option
 32 if the file has cut-on frequencies attenuating the phase
 at low frequencies
 The other values on the header line could be used in the future but
 should be 0. If there are astigmatism values, the convention is for
 the higher defocus value to be in the standard column for defocus, fol-
 lowed by the lower defocus value, then by the angle (counterclockwise
 positive) of the axis with the higher defocus (the short axis of the
 ellipse in an FFT). However, either defocus value can be in the first
 column as long as the axis angle is that of the first defocus value.
 If the lower defocus is first, both Ctfphaseflip and Ctfplotter will
 swap the two values and subtract 90 from the axis angle, so that astig-
 matism will always appear as a positive value.
 Either the astigmatism angles must be correct for the aligned stack, or
 the angles must be correct for the raw stack and the -xform option must
 be entered with the file of transforms used to produce the aligned
 stack from the raw one, so that the program can rotate these angles
 appropriately. A file with just astigmatism values could start with:
 1 0 0. 0. 0 3
 61 61 -58.94 -58.94 4652 4376 -43.2
 If there are phase shifts, they go in a column at the end of the line.
 They can be positive or negative; only the absolute value will be used
 and equations using these shifts subtract the absolute value of the
 number. A file with just phase shifts in radians could start with:
 12 0 0. 0. 0 3
 61 61 -58.94 -57.94 4376 1.47
 while a file with both astigmatism and phase shifts could start with:
 13 0 0. 0. 0 3
 61 61 -58.94 -57.94 4652 4376 -43.2 1.47
 If an expected phase shift is entered to Ctfplotter (either through
 the user interface or with the -phase option) and phase is not searched
 for, it will put out a defocus file with a phase shift that is the same
 on every line.
 A cut-on frequency in reciprocal nanometers may be included in the file
 only if it includes phase shifts. This value goes on the end of each
 line after the phase shift. Whenever a file contains cut-on frequen-
 cies, the phase values read in from the file are interpreted differ-
 ently: they are treated as being the phase at a particular frequency,
 0.3/nm. The model applied is
 phase(freq) = phaseAtInfinity * (1. - exp(-freq / cuton))
 where
 phaseAtInfinity = phaseInFile / (1. - exp(-0.3 / cuton))
 The reason for this convention is that cut-on frequency is difficult to
 find accurately, and the implied phase at infinity will vary consider-
 ably because of the random variations in cut-on frequency. The phase
 at this higher frequency will be much more stable and allows a better
 assessment of how accurately phase has been found.
 As for phase, if a cut-on frequency is entered to Ctfplotter through
 either the user interface or the -cuton option, then it will put out a
 defocus file with the same cut-on frequency on each line. A file with
 astigmatism, phase in degrees, and cut-on frequency could start with:
 37 0 0.0 0.0 0.0 3
 1 1 -50.00 -50.00 3665 3472 -62.10 118.54 0.1686
AUTHORS
 Quanren Xiong and David Mastronarde
SEE ALSO
 ctfplotter
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 Ctf-
 phaseflip reads in the 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.
IMOD 5.2.0 ctfphaseflip(1)