PFT2

(Polar-Fourier-transform, orientation-determination program, II)

Overview
Command-line input
Parameter-file input
PFT2 modes
Users of older or other versions

Overview

PFT2 is launched from the command line with a number of optional arguments and any number of STAR parameter files. If you type only "pft2", the following user information will be printed:

Usage: pft2 [options] par1.star [par2.star par3.star . . .]
-----------------------------------------------------------
Find and refine particle image orientations, origins, and scale 
factors via comparisons with a model.
 
Actions:
-allccs             Output all CCs in addition to Figure-of-merit (default no), modes 1-3 only
                      -to output R-factorABs, choose an fom option that uses them
-bin 2              Data compression by factor of n (integer only), default=1 (no compression)
-ctf flip           CTF correction: 0=none (default), 1=full, 2=flip, 3=amp only.
-handedness         Relative-handedness checking (180 deg. added to in-plane rotation), default off.
                      -modes 1-3,10 only
-mag 1.03,0.002,9   Refine scale factor (relative magnification, modes 1-4,9 only):  center, step, number,
                      search is center +- step*(number-1)/2
                      center = fractional midpoint (enter <=0 to use *.star values or 1.0 [if no STAR values])
                      step   = fractional step size
                      number = search window size (integer)
-mode refine        Execution mode: 1=sphere_search (default), 2=global, 3=refine, 4=origin, 5=brute,
                    6=omega, 7=theta, 8=phi, 9=mag (must use option "mag" also), 10=hand, 11=symmetry
-noorigin           Skip origin refinement in modes 1, 2, 3, and 5
-phaseampl 3        No. of orientations per particle tested with phase and amplitude data (default 1).
                      -modes 1-3,11, orientations ranked with amplitude test, top n tested with this option
 
Parameters:
-anglestep 1.0      Angle step size, in degrees (default = 1.0)
-fom 3              Figure-of-merit: 0=R-factor, Fourier space (R-factorAB)#
                                     1=Fourier-space, polar CC (old pftcc)
                                     2=real-space, polar CC (old prjcc)
                            DEFAULT  3=real-space, Cartesian CC (old cmpcc)#
                      4= (  {1}  + {2} ) / 2       7= ( {1} + {2} +   {3}   ) / 3
                      5= (  {1}  + {3} ) / 2       8= ( {2} + {3} + (1-{0}) ) / 3
                      6= (  {2}  + {3} ) / 2      13= ( {1} + {2} + (1-{0}) ) / 3
                     10= ((1-{0})+ {1} ) / 2      14= ( {1} + {3} + (1-{0}) ) / 3
                     11= ((1-{0})+ {2} ) / 2       9= ( {1} + {2} + {3} + (1-{0}) ) / 4
                     12= ((1-{0})+ {3} ) / 2#     25= {1} * {2} * {3} * (1-{0})
                     15={1}*{2}   16={1}*{3}  17={1}*(1-{0})   18={2}*{3}   19={2}*(1-{0})
                     20={3}*(1-{0})#       21={1}*{2}*{3}        22={1}*{2}*(1-{0})
                     23={1}*{3}*(1-{0})   24={2}*{3}*(1-{0})
                      [# fom options available for brute, theta, phi, mag, and hand modes]
-inprjpft name.img  Input projections & PFTs, as name_prjs.img & name_pfts.img
-jcut 0             Minimum Bessel order used (default 1).
-map name.img,...   Three-dimensional model(s), separate multiple file names by commas
-radii 11,78,1      Radial limits in pixels (inner, outer, step), default 0,max,1
-resolution 90,9.5  Resolution limits in angstroms (low, high), default 1000,25
-select 2           Select particles to process with select number (default all).
-symmetry I90       Symmetry designation, Schoenflies or H-M notation (default I90)
                      -use "T" for tetrahedral, "23" will signify 23-fold cyclic symmetry
 
Output:
-output file.star   Output STAR format file.
-outprjpft name.img Output projections & PFTs, as name_prjs.img & name_pfts.img, then exit (except mode 11)
-split 3            Put each data block into a separate file, insert n digits before extension
-time               Reports timing on total program run (default off).
-verbose 1          Verbosity level: 0 = no output printed to screen (default)
                                     1 = orientations, origins, CCs, etc.
                                     2 = 1 + CCs as function of radius & resolution as EMPFT.* (*=RADS,RES1,RES2)
                                     3 = 2 + CCs for each possible view for each particle
 
Advanced Options:
-keepselection      Keep the same selection values as in the input data set (default is to change)
-m1partparam        For mode=1, use particles specified in parameter file (default all in image file)
-nopftresmin        Eliminates min. resolution in PFTCC calc. (initial test for modes 1-3,11)
-noprjccres         Eliminates use of resolution limits in PRJCC calc. (2nd test for modes 1-3,11)
-novec              Disables PPC-AltiVec/Intel-SSE routines
-threads 1          Forces specific thread-count for projecting (default is number of CPU's)
 
 
pft2, version 2.0.0 2006-11-17  Compiled Nov 17 2006 11:07:35

Bsoft version 1.4.0-20060906 (32 bit)

Note that the pft2 version number, date, and compilation date and time are printed along with the version of Bsoft to which the program is linked.

Command-Line Input

Following the program name ("pft2"), options may be listed, followed by parameter files. For example, "pft2 -mode 2 -resolution 100,21.0 -output output02.star input01.star"

Command-line option	Definition (see also "Usage"in the "Overview" section above)	STAR-file equivalent (see also "Parameter-file input" below)
allccs	All correlation coefficients and the R-factorAB (if you choose an fom option that uses them) will be calculated and output to the output parameter file, restricted to modes 1-3.	none
anglestep	Angle step size (in degrees)	_pft.angle_step_size
bin	integral compression factor	_bin_factor
ctf	CTF correction applied within PFT2	none
fom	User may select which correlation coefficients and R-factorAB is included in the calculation of the figure-of-merit (used to select particles with good orientations and origins), see "Usage" statement	none
handedness	Check of the relative handedness (180 deg. added to in-plane rotation angle of model projection, and this view is tested to see if it compares better to the input image)	none
inprjpft	Do not compute projections and PFTs, instead input projections and PFTs (as name_prjs.img and name_pfts.img)	none
jcut	Minimum Bessel order	_pft.bessel_min
keepselection	Output the selection values from the input data set instead of replacing them.	none
m1partparam	If mode 1 is used, use the particles specified in the input parameter file. Do not use all the particles found in the image file(s) (default).	none
mag	Refine scale factor (relative magnification)	_pft.magnification_center _pft.magnification_step _pft.magnification_number
map	Input three-dimensional model(s), multiple maps may be entered	one model: _pft.file.model_image 3d_model.pif multiple models: loop_ _pft.file.model_image ref_model_1.pif ref_model_2.pif ref_model_3.pif
mode	The execution mode determines the type and extent of orientation, origin, and scale searches	none
noorigin	No origin refinement, restricted to modes sphere_search (1), global (2), refine (3), and brute (5)	none
nopftresmin	Do not use the low-resolution cut-off for PFTCC calculation	none
noprjccres	Do not use resolution limits for the PRJCC calculation	none
novec	Disables vector processing for PPC or Intel machines	none
outprjpft	PFT2 will compute projections and PFTs and write them to files	none
output	This is a STAR format output file which can be read in again by PFT2 or by another program (such as EM3DR2)	none
phaseampl	Sets the number of orientations per particle that are tested with amplitude and phase information	none
radii	Radial limits and interval between limits (pixels)	_pft.radius_min _pft.radius_max _pft.radius_step
resolution	Resolution limits (angstroms)	_pft.resolution_low _pft.resolution_high
select	With this option, the selection column in the STAR file can be used to determine which particles will be processed	none
split	A flag to indicate that the output STAR format files should be split so that each file contains only one data block (a data block typically contains the information for a micrograph)	none
symmetry	Definition of point-group symmetry	_symmetry
threads	Enforce a specific number of threads for multi-threading portions of code	none
time	Turns the timing flag on	none
verbose	With verbosity=0, basic output is input to the screen including important parameters. Higher numbers mean more output. Verbosity=1 means that CCs vs. radius and resolution are output. Verbosity=2 gives verbosity=1 plus ranking of views vs. the PFT correlation coefficient (to the screen).	none

Parameter-File Input

Example: pft2_example.star

One or more parameter files must be set up with the required data blocks and references to other files, such as the file name containing the picked particle images for each micrograph (tag "_micrograph_particle.file_name").

For each micrograph there must be a data block:

data_ _micrograph.field_id specimen_name_field1 _micrograph.id 4983 _micrograph_particle.file_name 4983_particles.pif _micrograph.pixel_size 5.526 _micrograph.units angstrom _micrograph.voltage 1.2000e+05 _micrograph.ctf.amp_contrast 0.0700 _micrograph.ctf.defocus_average 10305.1 _micrograph.ctf.defocus_deviation 455.37 _micrograph.ctf.astigmatism_angle 11.842 _micrograph.ctf.baseline "0.1208 + 5.69*exp(-47.34*$s2) + 6.32*exp(-197.7*$s2)" _micrograph.ctf.envelope 4.478*exp(-772.3*$s2) _micrograph.ctf.Cs 2.0000e+07 _micrograph.ctf.amplitude_shift 0 _micrograph.ctf.amplitude_scale 1 _micrograph.ctf.s_shift 0 _micrograph.ctf.sigma 1 _micrograph.ctf.exp_amp_shift 0 _micrograph.ctf.exp_amplitude 1 _micrograph.ctf.exp_decay 1 _micrograph.magnification 0.0000 _micrograph.sampling 0.0000 _micrograph.tilt_axis 0.0000 _micrograph.tilt_angle 0.0000 _micrograph.rotation_angle 0.0000 _micrograph.x_shift 0.0000 _micrograph.y_shift 0.0000 _micrograph.x_scale 0.0000 _micrograph.y_scale 0.0000 _micrograph.box_radius 97.0000

The data blocks as given above are sufficient in "sphere_search" mode, where previous orientation parameters determined by PFT2 or other programs are simply ignored. The CTF parameters are only required when CTF correction is turned on. When the other modes are used, the following loop is also required within the micrograph data block (this loop block is also written to the output parameter file(s) of a PFT2 run, ready to be read in for the next run):

loop_ _particle.id _particle.theta _particle.phi _particle.omega _particle.x_origin _particle.y_origin _particle.magnification _particle.fom _particle.select 1 73.000 3.137 -0.70 74.065 74.848 1.0000 0.3896 1 2 81.000 7.087 -84.38 73.123 72.280 1.0000 0.3673 1 3 80.000 6.093 61.17 82.947 69.396 1.0000 0.3038 0

The output from PFT2 may be used as input in bpartsel (a Bsoft program) to select particles via the figure-of-merit or other criteria.

The "_particle.select" term is very important in selecting particles for reconstructions and further processing.

There may be one data block in the beginning of the file or in a separate file with the parameters for PFT2 (however, you are encouraged to enter these parameters on the command line, see above):

data_ _bin_factor 2 _symmetry 532 _length_unit angstrom _pft.angle_step_size 1.0 _pft.radius_min 50 _pft.radius_max 112 _pft.radius_step 1 _pft.resolution_low 200 _pft.resolution_high 30 _pft.magnification_center 1.003 _pft.magnification_step 0.002 _pft.magnification_number 15 _pft.file.model_image 3d_model.pif

Alternatively, multiple models can be entered as
loop_ _pft.file.model_image ref_model_1.pif ref_model_2.pif ref_model_3.pif

See Bsoft manual for more information on the STAR format. An example of a multiple micrograph STAR file (includes particle orientations and origins) is available here.

The Modes of PFT2

The strategy of PFT2 (originating with the original EMPFT) is to separate the determination of different orientation parameters to improve the efficiency of the algorithm. Projections from different orientations of a reference map are computed and compared with the raw images to find the best match and so determine the raw particle orientations. The {x,y} origin of an image is found by cross-correlation with a projection. The in-plane rotation angle, omega, is derived from a cartesian to polar transformation of both model projection and raw particle image (the polar Fourier transform or PFT), followed by 1D cross-correlation of the annuli. The remaining two Euler angles, theta and phi, are determined from correlation coefficients, either from the correlation of the PFTs, or from 2D correlation of the projections.

This provides a particularly useful representation of projection images of spherical objects and allows rapid and sensitive determination of each particle orientation. Program efficiency arises because the particle parameter determination is segregated into a few, discrete stages rather than trying to perform all computations in a single, brute force step.

Generating projection and PFT files
In a typical run, PFT2 generates projections and polar Fourier transform (PFT) images from the reference map within the bounds of an asymmetric unit. These images are then used in finding the orientations of the raw particle images. One can also just generate these files from a reference map and write them to disk. A typical command line for doing this is:

pft2 -map 3dmodel.map -outprjpft model.pif -symmetry C5

The output multi-image files containing the projections and PFTs from this command line will be model_prjs.pif and model_pfts.pif, respectively.

The PFT image is calculated by converting a projection (model projections here but similarly for raw particle images) from cartesian {x,y} to polar {r,a} format by subdividing it into a series of concentric annuli (each usually exactly one pixel wide). Each annulus is sampled a number of times, with the interpolation performed at a fine enough interval to prevent loss of data resolution at the highest particle radius. Hence, annuli at the lowest radii in the particle image are oversampled. Each annulus is then separately Fourier transformed in 1D to give the polar Fourier transform (PFT) of the image.

1) Sphere_search mode
The first step in finding particle orientations with PFT2 is to estimate the {x,y} origin for each particle image by cross-correlating each image with a circular average of the sum of all model projections. This is then followed by comparison of the PFT of the raw image with all of the projection PFT's and selecting the best based on the PFT correlation coefficient. New {x,y} origins are calculated using cross-correlation with the selected projection, appropriately rotated by angle omega. This mode is only appropriate for spherically shaped objects such as icosahedral viruses. Therefore, it is recommended that you only use it for the initial iteration if initial origins are not available.

2) Global mode
This mode is similar to the search mode, except that the input origins from the parameter file are used to generate the particle image PFT's. As in search mode. projections are generated for the entire asymmetric unit and all particle images are compared with all projections. The intent is here to find the correct orientations to within a degree or two before attempting to refine it.

3) Refine mode
The orientations from the input parameter file for each particle are used to define a search grid around the input theta and phi, with 7 steps in the theta direction and 7 steps in the phi direction. The orientation parameters should be determined to a nominal accuracy of 0.1 to 0.5 degrees.

4) Origin mode
This mode is intended for refinement of origins without changing orientation parameters. Currently, relative magnification can also be refined or determined if desired.

5) Brute mode
This mode circumvents the PFT dogma of segregating the orientation search into efficient, discrete tests. It searches every omega angle at every phi,theta angle. It determines the origin and scale (if desired) for each orientation, too. This mode could be used to determine initial origins for non-spherical particles and to find orientations, etc. for particles stuck in local minima. Note that it will take much longer to complete than other modes.

6) Omega mode
Only the in-plane (omega or psi) angles can be changed in this mode. The omega angle is determined by the same method used to determine omega in global, refine, and sphere_search modes. The only figure-of-merit returned is the correlation coefficient between polar versions of the model projection and input image. Both resolution and radial limits can be imposed. Phi, theta angles and x,y origins are required input (via a STAR file).

7) Theta mode
Only the theta angle for each particle is refined in this mode. All possible theta angles are tested. Both resolution and radial limits can be imposed. Input orientations and x,y origins are required input (via a STAR file).

8) Phi mode
Only the phi angle for each particle is refined in this mode. All possible phi angles are tested. Both resolution and radial limits can be imposed. Input orientations and x,y origins are required input (via a STAR file).

9) Mag mode
Only the relative scale (magnification) is determined in this mode. Both resolution and radial limits can be imposed. Input orientations and x,y origins are required input (via a STAR file).

10) Hand mode
The relative handedness (omega and omega+180 deg.) is tested. Input orientations and x,y origins are required input (via a STAR file).

11) Symmetry mode
Test symmetry-related views for each particle. Symmetry-related views are generated from input orientation. Input origins also needed. No origin refinement is done.

Note that option "-noorigin" may be invoked for modes 1, 2, 3, and 5 to prevent origin refinement. (Mode 1 will still have initial origins estimated, however.)

IMPORTANT NOTE TO THOSE WHO HAVE USED OLDER OR OTHER VERSIONS OF THESE PROGRAMS (EMPFT, EM3DR, etc.)

4 Jan 2008
Questions, problems, or bugs? Contact David_Belnap@byu.edu

Back to main PFT2/EM3DR2 page