xmipp_ml_align2d (v3.0)


Perform (multi-reference) 2D-alignment using a maximum-likelihood (ML) target function. Our recommended way of performing ML alignment is to introduce as little bias in the intial reference(s) as possible. This can be done by calculting average images of random subsets of the (unaligned!) input experimental images, using the --nref option. Note that the estimates for the standard deviation in the noise and in the origin offsets are re-estimated every iteration, so that the initial values should not matter too much, as long as they are "reasonable". For Xmipp-normalized images, the standard deviation in the noise can be assumed to be 1. For reasonably centered particles the default value of 3 for the offsets should do the job.

The output of the program consists of the refined reference images (weighted averages over all experimental images). The experimental images are not altered at all. In terms of the ML approach, optimal transformations and references for each image do not play the same role as in the conventional cross-correlation (or least-sqaures) approach. This program can also be used for reference-free 2D-alignment using only a single reference: just supply --nref 1 . Although the calculations can be rather time-consuming (especially for many, large experimental images and a large number of references), we strongly recommend to let the calculations converge. In our experience this takes in the order of 10-100 iterations, depending on the number images, the amount of noise, etc. The default stopping criterium has yielded satisfactory results in our experience. A parallel version of this program has been implemented.

See also


-i <input_file>
Metadata or stack with input images
--nref <int=1>
Number of references to generate automatically (recommended)
--ref <reference_file=>
Image, stack or metadata with initial(s) references(s)
--oroot <rootname=ml2d>
Output rootname
Also check mirror image of each reference
Use pre-centered images to pre-calculate significant orientations. If this flag is set part of the integration over all references, rotations and translations is skipped. The program will store all (N_imgs*N_refs) origin offsets that yield the maximum probability of observing each experimental image, given each of the references. In the first iterations a complete integration over all references, rotations and translations is performed for all images. In all subsequent iterations, for all combinations of experimental images, references and rotations, the probability of observing the image given the optimal origin offsets from the previous iteration is calculated. Then, if this probability is not considered "significant", we assume that none of the other translations will be significant, and we skip the integration over the translations. A combination of experimental image, reference and rotation is considered as "significant" if the probability at the corresponding optimal origin offsets is larger than C times the maximum of all these probabilities for that experimental image and reference (by default C=1e-12) This version may run up to ten times faster than the original, complete-search approach, while practically identical results may be obtained.
--thr <N=1>
Use N parallel threads
--iem <blocks=1>
Number of blocks to be used with IEM

Additional options

--eps <float=5e-5>
Stopping criterium
--iter <int=100>
Maximum number of iterations to perform
--psi_step <float=5.>
In-plane rotation sampling interval [deg]
--noise <float=1>
Expected standard deviation for pixel noise
--offset <float=3.>
Expected standard deviation for origin offset [pix]
--frac <docfile=>
Docfile with expected model fractions (default: even distr.)
-C <double=1e-12>
Significance criterion for fast approach
Kick-start the fast algorithm from all-zero offsets
--restart <iter=1>
restart a run with all parameters as in the logfile
Do not re-estimate the standard deviation in the pixel noise
Do not re-estimate the standard deviation in the origin offsets
Do not re-estimate the model fractions
--student <df=6>
Use t-distributed instead of Gaussian model for the noise df = Degrees of freedom for the t-distribution
Refined normalization parameters for each particle
Save memory A(deprecated)
Save memory B(deprecated)

Examples and notes

A typical use of this program is:
xmipp_ml_align2d -i input/images_some.stk --ref input/seeds2.stk --oroot output/ml2d --fast --mirror

User's comments