align_2d_pi

Overview

align_2d_pi is a command-line application to align two tilt series to one another. The two tilt series must have the same image dimensions and number of sections. align_2d_pi writes alignment results to standard output; it can also record those results as a .bprmMn format alignment parameter file. align_2d_pi_parallel is a parallel version of align_2d_pi. It accepts the same command-line arguments and options as align_2d_pi and also accepts the options described in Parallel.html to control parallel execution.

The command line syntax for align_2d_pi is (optional parts are shown in brackets):

    align_2d_pi reference target \
        [-iprmfile=ipname] \
        [-oprmfile=opname] \
        [-ofile=stkname] \
        [-cor_out=xcname] \
        [-axis=angle] [-overwrite_axis] \
        [-imod=m] \
        [-dev=x:y:rot:mag:axis:stretch] \
        [-nofilter] [-nooffset] \
        [-phaseweight] [-mult=s] \
        [-cpd=d] [-spth=t] \
        [-shxyz=xs:ys:zs] \
        [-iref=i] \
        [-iv=start:end] \
        [-res=i] [-resref=i] \
        [-fullsize=nx:ny] \
        [-rscale=i]

The two required arguments and other options are

reference

Is the name of the MRC file containing one of the tilt series. This tilt series is used as the reference: the calculated alignment parameters can be applied to the other tilt series to bring it into alignment with the reference.

target

Is the name of the MRC file containing the other tilt series.

-iprmfile=ipname

Causes align_2d_pi to read the file named ipname for the initial guess at the alignment parameters. The file must be in the .bprmMn format or older .bprm format.

-oprmfile=opname

Causes align_2d_pi to write the alignment parameters to a .bprmMn format file named opname. If you use the -iprmfile option, align_2d_pi will carry over parameters it does not modify from the input parameter file; otherwise, align_2d_pi will fill in default values for the unmodified parameters.

-ofile=stkname

Specifies the name of the file to write with the reference tilt series after it has been apodized and transformed to the target tilt series' coordinates. This file is only generated if the method used includes FFT-based cross-correlation.

-cor_out=xcname

Specifies the name of the MRC file to write with the images of the cross-correlation peaks. This file is only generated if the method used includes FFT-based cross correlation.

-axis=angle

Specifying this option causes align_2d_pi to use angle as the orientation angle, in degrees, for the tilt axis. This is the angle the tilt axis makes with the vertical image axis; a positive value implies that a clockwise rotation will make the tilt axis parallel to the vertical image axis. If you also specify an input parameter file, you will need to use the -overwrite_axis option if you want the value you specified with -axis to take precedence over the values in the input parameter file.

-overwrite_axis

If you specify this option, the tilt axis orientation you set with -axis takes precedence over the tilt axis orientation values from an input parameter file.

-imod=m

Sets the method to use for alignment. m may be one of the values listed below.

0

Use a FFT-based cross-correlation to determine the translations followed by a simplex optimization of all parameters.

1

Use a FFT-based cross-correlation to determine the translations. The other parameters are not modified. This is the default.

2

Use a simplex optimization of all parameters.

-dev=x:y:rot:mag:axis:stretch

Sets the characteristic length for each of the six alignment parameters (x shift in pixels, y shift in pixels, rotation in radians, isotropic magnification factor, orientation angle for the anisotropic stretching axis in radians, and anisotropic stretching factor). The first four parameters have a direct effect on the parameters in a .bprmMn file; the last two do not. A characteristic length of zero for a parameter prevents align_2d_pi from adjusting that parameter during the alignment. By default, align_2d_pi uses a characteristic length of one pixel for the x and y shift, a characteristic length of zero radians for the rotation and orientation of the asymmetric stretching axis, and a characteristic length of zero for the magnification and asymmetric stretching factor.

-nofilter

If specified, a highpass filter is not applied when you use simplex optimization; otherwise, a highpass filter is applied when you use simplex optimization.

-nooffset

If specified, no offset along the tilt axis is applied when using an FFT-based cross-correlation; otherwise an offset is applied along the tilt axis and then compensated for prior to writing out the alignment parameters.

-phaseweight

If specified, phase weighting is done in the FFT-based cross-correlation; otherwise, phase weighting is not done.

-mult=s

Sets the scale factor, s, for the noise component when performing phase weighting of the FFT-based cross-correlation function. The default value for the scale factor is one hundred.

-cpd=d

To reduce the effect of a central peak, the algorithm using FFT-based cross-correlations will subtract off a radial average from the central 7 x 7 if the brightest point in the central 7 x 7 occurs at the center and a quadratic fit to the center and its four nearest neighbors gives a peak position, (xp, yp), where the absolute values of xp and yp are less than d. The default value of d is 0.05 pixels.

-spth=t

For the FFT-based cross-correlations, peaks away from the origin are preferred. A peak at the origin is only accepted if the next highest peak (after masking out the origin) has a height less than t times the height of the peak at the origin. The default value for t is .001.

-shxzy=xs:ys:zs

Compensates the initial and final alignment parameters for tilt axis shifts of xs pixels in x, ys pixels in y, and zs pixels in z. For example, when the reference tilt series is generated with the combination of appl_prm, reconstruction, and then reprojection of the reconstruction, you would typically specify the same -shxyz option to both appl_prm and to align_2d_pi. Doing so avoids including the shift for the region interest in the alignment parameters.

-iref=i

Sets the zero-based index for the projection to use as the reference when compensating for shifts specified with the -shxyz option. By default, align_2d_pi will use the projection whose tilt angle is closest to zero as the reference.

-iv=start:end

Limits the sections align_2d_pi will align: it will only process those sections whose zero-based index is greater than or equal to start and less than or equal to end. If you specified the -oprmfile option, the generated parameter file will only contain data for the aligned sections, and the numbering of the sections (i.e. the first column) in that file will be from start plus one to end plus one.

-res=i

Specifies that the alignment should use the ith resolution data set (0 is the highest resolution) from the target tilt series. i must be a non-negative integer less than the number of resolutions in the target tilt series. By default, the alignment will use the highest resolution data set.

-resref=i

Is similar to -res, but applies to the reference tilt series.

-fullsize=nx:ny

Specifies the x and y dimensions (in pixels) of the full resolution target tilt series. If not specified, these values default to the dimensions of the highest resolution present in the target tilt series. In the case where you are running the alignment on a downsampled file but the input and output alignment parameters are to be for the full resolution data set, you should adjust the full size parameters to be the dimensions of the full resolution data set.

-rscale=i

Specifies that a scale factor of 1.0/i be applied to the shifts specified by -shxyz, the shift characteristic lengths specified by -dev, and the input alignment parameters. If you do not specify this option, i is taken to be two raised to the jth power where j is the resolution selected with -res. In the case where you are running the alignment on a downsampled file but the input and output alignment parameters are to be for the full resolution data set, you should set the resolution scale to be the same as the downsampling factor (if the data is scaled down by a factor of four set the resolution scale parameter to four).

Related Priism Topics

Priism | single tilt series alignment | iterative alignment + reconstruction | applying alignment parameters