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 specifed, 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 mirror image. (See align_overview.html for comparison of 'AP' operations.)

SEE ALSO

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

USAGE

.OPERATION: AP REF

<or>
AP REF X10,X11,X12,X13,X14,X15,X16

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

.ENTER 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 older 'AP MD', 'AP RD' or 'AP RN' operations.]

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

.REFERENCE IMAGES ANGLES DOCUMENT FILE: REFANGLES
[Enter the name of the angular document file (input file) containing the reference images (projections) Eulerian angles: psi, theta, phi.]

.REFERENCE-RINGS 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 reference image file series. 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.

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

.ENTER 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).]

.EXPERIMENTAL IMAGES ALIGN. DOCUMENT FILE: angles001
[Optional input file. If '*' is given then this operation is similar to old 'AP MD'. 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 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 (0=NOCHECK / 1=CHECK)?: 1
[Can mimic action of older 'AP RD' operation.]

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

.OUTPUT ALIGNMENT DOCUMENT FILE: align002
[This is the only output produced by this operation. (Appends to existing output file of same name). It contains 15 register columns:

1. Eulerian angle (psi) of nearest reference image.
When no matching projection was found within the angular range specified, this column will contain the experimental image's previous Eulerian angle (if any) or 0.0.

2. Eulerian angle (theta) of nearest reference image.
When no matching projection was found within the angular range specified, this column will contain the experimental image's previous Eulerian angle (if any) or 0.0.

3. Eulerian angle (phi) of nearest reference image.
When no matching projection was found within the angular range specified, this column will contain the experimental image's previous Eulerian angle (if any) or 0.0.

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

5. Experimental projection number.

6. Cumulative In-plane rotation angle (psi).

This is the sum of any rotation from the 'experimental images align. document file' and the current rotation. To use in 3D reconstruction programs invert the sign.

7. Cumulative X shift
Cumulative X translation of image. This is the sum of any shift from the 'experimental images align. document file' and any current shift.

8. Cumulative Y shift
Cumulative Y translation of image. This is the sum of any shift from the 'experimental images align. document file' and any current shift.

9. Number of projections searched.
The number of projections searched can vary when there is a restriction on angular search.

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 correlation coefficient from rotational search.

Can be used as a similarity measure.

Following values are seldom used by existing proceedures:

12. Current In-plane rotation angle (psi).
This is the rotation necessary to align the experimental image with the current reference projection.

13. Current X shift
This is the X shift necessary to align the experimental image with the current reference projection.

14. Current Y shift
This is the Y shift necessary to align the experimental image with the current reference projection.

15. Shift normalized CC Peak Height & Current Mirroring.
This is the normalized cross correlation peak height from the shifted image. This value can be used as a similarity measure. If mirroring was necessary to align the experimental image with the reference projection this value is given a negative sign.

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

3. The operation is computationally intensive. The code is parallel.

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

5. This operation parallelized for use with MPI.

6. Implemented by: Paul Penczek and ArDean Leith

7. Sequence of steps in alignment using 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 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, DSGR_PM, DSGR_P, DSFS_P, AP_END, NORMAS, ALRQS, ALPRBS, CROSRNG_MS, CROSRNG_E, FRNGS, PRB1D, FFTR_D, FFTC_D, APPLYW

CALLER

UTIL4