SPIDER: AP SH (Alignment - multi-reference, exhaustive rotation & shift ||*)

AP SH - Alignment - multi-reference, exhaustive rotation & shift ||*

(01/05/12)

PURPOSE: Determines optimal shifts and rotations to align a series of experimental images with a series of reference images. For each experimental image, it finds the in-plane Euler rotation angle, and X, Y translational shifts which align the image with the most-similar reference image. Exhaustively checks all requested rotations and shifts. Can restrict angular range of projections and inplane rotation range. Can restrict checking of mirror image.
(See align_overview.html for comparison of 'AP' operations.) Example.

SEE ALSO

AP SHC	[Alignment - multi-reference, fast exhaustive rotation & shift \|\|]
VO EA	[Vector Operation - Create Doc File Containing Evenly Spaced Angles]
VO MD	[Vector Operation - angular Document file from 'AP MD' output]
AP REF	[Alignment - multi-reference, rotation & shift \|\|*]
OR SH	[Orientation Search - 2D, rotation & shift, uses polar coords. \|\|]
PJ 3Q	[Project - 3D volume using Eulerian angles, trilinear interpolation \|\|]
RT SF	[Rotate and Shift - image, Fourier based spline interpolation \|\|]

USAGE

.OPERATION: AP SH

.TEMPLATE FOR REFERENCE IMAGES: REF***
[Give the template for the name of the existing file series of 2D reference images (typically projections).]

.FILE NUMBERS OR SELECTION DOC. FILE NAME: SELECTREF
[Enter numbers of reference files. The file numbers can also be read from a selection document file where file numbers are contained in the first register (not the keys).]

.TRANSLATION SEARCH RANGE IN X, IN Y (OPTIONAL), STEP SIZE': 6,2
[The search for translation parameters will be restricted to +/- search range, performed every "step size" pixel.
Restrictions:
1. Search range + last ring <= NX/2-2
2. Search range has to be divisible by step size.]
Speed will depend on square of the number of positions searched. Use of 'step size' greater than one can speed up alignment determination with little effect on final reconstruction resolution. The input for Y shift is optional, if only two inputs are present the second one is interpreted as the step size. ]

.FIRST, LAST RING, RING STEP, & RAY STEP: 5,15,1,1
[The search for rotational alignment will be restricted to pixels with radii in the specified range (here: 5-15), performed every 'ring step' radius and on every 'ray step' radial ray.
Restrictions on 'ray' search, every: 1,2,4,8,16 'th radial ray can be included in search.
Use of 'ring step' and 'ray step' greater than one can speed up alignment determination on large images with minimal effect on final reconstruction resolution.]

.OPTIONAL REFERENCE IMAGES ANGLES DOCUMENT FILE: Refangles
[Optional input file. Enter name of the doc file containing Eulerian angles (psi, theta, phi) for the reference images. Enter '*' if you do not have any reference angles doc file.

.TEMPLATE FOR IMAGE SERIES TO BE ALIGNED: DAT***
[Give the template name of the existing file series of experimental images. These images will be checked for alignment versus the reference images.]

.FILE NUMBERS OR SELECTION DOC. FILE NAME: 1-2100
[Enter numbers of experimental files. The file numbers can also be read from a selection document file where file numbers are contained in the first register (not the keys).]

.OPTIONAL EXPERIMENTAL IMAGES ALIGNMENT DOCUMENT FILE: angles001
[Optional input file. If '*' is given then this operation is similar to old 'AP MQ'. If you desire to restrict the range of angular search for projections then this file is necessary. It must contain the current Eulerian angles of experimental images (projections: psi, theta, phi) and optionally the current inplane rotation, shifts and other alignment parameters. The output files from 'AP SH' and 'AP REF' contain this info.]

.RANGE OF PROJECTION ANGLE SEARCH & ANGLE CHANGE THRESHOLD: 20.0, 14.0
[Experimental images will be compared with only those reference images whose normal is within specified range (in degrees). If a 0.0 is entered, then there is NO restriction on which of the projections are compared. The "angle change threshold" is only used to report what percentage of the rotational changes exceed this specified threshold. This value can later be used to halt the iterations. The value is placed in a comment key at the end of the operations output file. It is not used for any other purpose.]

.CHECK MIRRORED POSITIONS?, SHIFT/ROTATE INPUT? (Y/N): Y, Y
[Optional check of the mirrored reference image. By using this check and only providing reference images from one hemisphere of projection directions, speed can be doubled. See note: 1 below.
The second prompt requests that the input files first be rotated/shifted by the alignment parameters from the experimental images alignment document file before use. This is equivalent to running the 'RT SQ' operation before using 'AP SH'. If this is 'Y' there is no need for 'dala' files. (For backward compatibility the legacy '0/1' response is still accepted for CHECK MIRRORED POSITIONS and second response defaults to 'N'.)]

.OUTPUT ALIGNMENT DOCUMENT FILE: align_doc_01
[Document file containing optimal alignment parameters for each experimental image. Will append to an existing output file of same name. This document file contains 15 register columns:

Register
col. Register contents

1, 2, & 3 Eulerian angles: psi, theta, & phi of projection direction for nearest reference image.
When no matching projection was found within the angular range specified, these columns will contain the experimental image's previous Eulerian angle (if any) or zero.

4 Number of the most similar reference projection.
When no matching projection was found within the angular range specified, this column will contain zero.

5 Experimental image number.

6 Cumulative In-plane rotation angle.
To use in 3D reconstruction programs invert the sign. This is the sum of any rotation from the 'experimental images alignment document file' and the current in-plane rotation.

7 & 8 Cumulative X & Y shifts.
This is the sum of any shift from the 'experimental images align. document file' and any current shift.
These shifts have been adjusted to compensate for any rotation, so that they are appropriate for use with SPIDER operations such as 'RT SQ'. Thus the current shifts may be greater than the shift range that you requested above.

9 Number of reference projections searched.
This number can vary when an angular restriction on search is used.

10 Angular change for projection.
Angular difference between previous and current projection. This will be -1.0 if the previous projection angles were not specified.

11 Not-normalized alignment correlation coefficient.
Used as a similarity measure. (Normalization gives a significant time penalty and there are reports that normalization decreases value of the statistic in distinguishing best fit.)
Following values are rarely used:

12 Current In-plane rotation angle.
Rotation necessary to align the experimental image with the current reference projection.

13 & 14 Current X & Y shifts shifts to align the experimental image with the selected reference projection.
These shifts have been adjusted to compensate for any rotation, so that they are appropriate for use with SPIDER operations such as 'RT SQ'. Thus the current shifts may be greater than the shift range that you requested above.

15 Current Mirroring.
If value is negative, mirroring was necessary to align the experimental image with the reference projection. For 'AP REF' if this value is non-zero then it is the absolute value of the normalized cross-correlation for the match.

NOTES

In 3D space the projection with the direction: (psi, theta, phi) has its mirrored (around Y-axis) counterpart in the direction: (-psi, 180+theta, phi)
To save time, the operation can take this into account if you speciify 'check mirrored positions'. In this case each experimental projection is compared with the reference projection and its mirrored version at the same time. Thus, only half of the total number of reference projections are required; namely, only those with 0 < theta < 90.
If the best match was with the mirrored reference projection, then the value stored in the 15th register of the document file is negative and the projection direction reported in the 1st register column is the proper projection direction for the image.
The reference projections of an existing structure can be created using 'VO EA' and 'PJ 3Q' operations. 'VO EA' creates an angular document file with quasi-evenly spaced projection directions and 'PJ 3Q' creates projections of the volume according to this doc file.
Alignment parameters (angle and translation included in columns 6-8 of the output document file) can be used with operation 'RT SQ' to align images.
Alignment parameters can be used as input to further 'AP SH' or 'AP REF' operations during refinement.
This operation parallelized for use with MPI.
Setting a angular search limit of 180 degrees with checking of mirrored positions does not give same results as an unlimited search, since the limited search only looks at the nearer projection. This is not a bug.
This operation never was written to provide comprehensive sub-pixel resolution. Normally only about 50% of the shifts are refined to provide sub-pixel estimates.
Sequence of steps in the alignment carried out by this operation:
Load gallery of reference images created by projection of the reference volume.
Extract radial rings from a window of each reference image, converting image to a polar representation.
Take fourier transform of the ring data and weight the data corresponding to length and radius.
Load a sample image.
Extract radial rings from a window of sample image, coverting image to a polar representation.
Take Fourier transform of the ring data and weight the data corresponding to length and radius.
Perform a cross correlation in Fourier space of the reference and sample data.
Find location of highest peak from cross correlation and map it to a rotation angle for the sample image.
Repeat for all requested X & Y shifts of the sample image. You now have sample shift and rotation.
Repeat for next sample image.

SUBROUTINES: APMASTER, APSH_PS, APSH_SS, APRINGS, NORMASC, NORMAS, CROSRNG_MS, FRNGS, AP_END, AP_STAT, RINGWE, APPLYWS, PARABLD, AP_GETANGAS, AP_GETDATA

CALLER: UTIL4

Register col.	Register contents
1, 2, & 3	Eulerian angles: psi, theta, & phi of projection direction for nearest reference image. When no matching projection was found within the angular range specified, these columns will contain the experimental image's previous Eulerian angle (if any) or zero.
4	Number of the most similar reference projection. When no matching projection was found within the angular range specified, this column will contain zero.
5	Experimental image number.
6	Cumulative In-plane rotation angle. To use in 3D reconstruction programs invert the sign. This is the sum of any rotation from the 'experimental images alignment document file' and the current in-plane rotation.
7 & 8	Cumulative X & Y shifts. This is the sum of any shift from the 'experimental images align. document file' and any current shift. These shifts have been adjusted to compensate for any rotation, so that they are appropriate for use with SPIDER operations such as 'RT SQ'. Thus the current shifts may be greater than the shift range that you requested above.
9	Number of reference projections searched. This number can vary when an angular restriction on search is used.
10	Angular change for projection. Angular difference between previous and current projection. This will be -1.0 if the previous projection angles were not specified.
11	Not-normalized alignment correlation coefficient. Used as a similarity measure. (Normalization gives a significant time penalty and there are reports that normalization decreases value of the statistic in distinguishing best fit.)
	Following values are rarely used:
12	Current In-plane rotation angle. Rotation necessary to align the experimental image with the current reference projection.
13 & 14	Current X & Y shifts shifts to align the experimental image with the selected reference projection. These shifts have been adjusted to compensate for any rotation, so that they are appropriate for use with SPIDER operations such as 'RT SQ'. Thus the current shifts may be greater than the shift range that you requested above.
15	Current Mirroring. If value is negative, mirroring was necessary to align the experimental image with the reference projection. For 'AP REF' if this value is non-zero then it is the absolute value of the normalized cross-correlation for the match.