AP REF - Alignment - multi-reference, rotation & shift ||*

PURPOSE

Compares a set of experimental images with a set of reference images. For each experimental image, it finds the in-plane Euler rotation which aligns the experimental image with the most-similar reference image. Then, if translation search is specified, it finds the X & Y shifts which align the reference image with the rotated experimental image. Can restrict angular range of projections. Can restrict checking of a mirror image. (See align_overview.html for comparison of 'AP' operations.)   Example.

SEE ALSO

VO EA	[Vector Operation - Create Doc File Containing Evenly Spaced Angles]
VO MD	[Vector Operation - angular Document file from 'AP MD' output]
AP I	[Alignment - Initialize Rings File ||]
AP SH	[Alignment - multi-reference, exhaustive rotation & shift ||*]

USAGE

.OPERATION: AP REF

   <or>
AP REF [spi],[theta][phi],[np],[exp],[cpsi],[x],[y],[nproj],[ang],[cc],...
   <or>
AP REFD [spi],[theta][phi],[np],[exp],[cpsi],[x],[y],[nproj],[ang],[cc],...

.TEMPLATE FOR REFERENCE IMAGES: REF***
[Give the template name of the existing file series of 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 (ZERO FOR NONE): 5
[For translational alignment enter limit on translational shift. A response of '0' will give same alignment as obsolete 'AP MD', 'AP RD' or 'AP RN' operations.]

.FIRST, LAST RING, & RING SKIP: 5, 30, 1
[Only data at radii in the range 5-30 will be analyzed. If skip=0 or 1, then every radial ring between 5 and 30 will be taken; for skip=2, every second ring, etc.]

.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.

.OPTIONAL REFERENCE-RINGS INPUT FILE: REF001
[Give name of reference-rings file. If the file exists, SPIDER will read the reference-rings data from this file and will not read the actual reference image files. If this file does not exist, SPIDER will create/store the reference-rings data in incore memory. If SPIDER is unable to allocate sufficient memory for the reference-rings data then a reference-rings file will be created and used during this alignment run. More than one SPIDER run can use the same reference-rings file.
Note that old responses 'W', 'Y', & 'N' are now obsolete.

.TEMPLATE FOR IMAGE SERIES TO BE ALIGNED: data001@****
[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 image 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 obsolete 'AP MD'. If you desire to restrict the range of angular search for projections then this doc 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 such info.]

.RANGE OF PROJECTION ANGLE SEARCH & ANGLE CHANGE THRESHOLD: 20.0, 5.0
[Experimental images will be compared with only these reference images whose normal is within the specified degree range. If a '0.0' range is input then there is NO restriction on which of the projections are compared. The angle change threshold is an optional input which is used solely to record how many angular projections differ by more than the specified threshold from their previous orientation.]

.CHECK MIRRORED POSITIONS?, SHIFT AND ROTATE INPUT? (Y/N): Y,N
[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 answer is an optional request to rotate and shift input images according to parameters in the experimental images alignment doc. file before determining alignment. (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'.]

If register variables were specified on the operation line then no output document file is created. Instead the registers receive the output that normally would be put into the document file. This is useful when only a single image is being aligned. If you really want both register and document file output you can over-ride this with operation: 'AP REFD'.

.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

1. Reference projections of the 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.

2. 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.
   

3. The operation switches automatically between in-core and on-disk versions depending on the memory available. The reference rings file name is created/required in either case but it may not be created if there is adequate incore memory is available.

4. The operation is computationally intensive and parallelized for use with either OpenMP or MPI.

5. The alignment parameters from the output doc. file can be used as input to further 'AP SH' or 'AP REF' runs during a refinement.

6. Implemented by: Paul Penczek and ArDean Leith

7. 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.

8. Sequence of steps in alignment used inside this operation:
   Load gallery of reference images created by projection of the reference volume.
   Load sample image.
   Perform a cross correlation in Fourier space on reference and sample data.
   Find location of highest peak from cross correlation and map it to a X & Y shift for the sample image.
   Shift the sample image.
   Extract radial rings from a window of the reference image, converting image to a polar representation.
   Take Fourier transform of the ring data and weight the data corresponding to length and radius.
   Extract radial rings from shifted sample image, converting 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 on reference and shifted sample data.
   Find location of highest peak from cross correlation and map it to a rotation angle for the sample image. You now have sample shift and rotation.
   Repeat with single pixel and some sub-pixel image shifts.
   Find location of highest peak from cross correlation and map it to a rotation angle for the sample image. You now have sample shift and rotation.
   Repeat for all sample images.
   

SUBROUTINES

APMASTER, APRINGS, APREF_PM, APREF_P, AP_END, APSHIFT, CROSRNG_2, NORMAS, ALRQS, FRNGS, PRB1D, FMRS, CCRS, PKSR3, APCC

CALLER

UTIL4