EMTIARGPU is a front-end for the iterative alignment and reconstruction of EM tomography data. It is essentially the same as EMTIAR but uses servers outfitted with graphics cards to accelerate the reconstruction and projection calculations.
The basic recipe for generating a reconstruction with EMTIARGPU is:
Besides a log file, the iterative alignment and reconstruction generates two outputs. The first is an alignment parameter file for each iteration. The names for these files are the contents of the "OutParamBase" field with an underscore, the iteration number, and the extension of the input alignment parameter file appended. The second output is the data for the reconstructed volume. The file name for the reconstructed volume is in the "Reconstruction" field.
Overview | Resolution | Apply massnorm | Reconstruction shift | Reconstruction Z size | Recon. cycles/run | Restart recon | Number of runs | Temporary directory | Initial guess | Cross correlations | Guess resolution | Starting run number | Resolution scale | Full size | Aligned size | Section range | Reconstruction method | Blocks | Convergence factor | Add multires | Alignment method | Simplex filter | Offset | Phase weighting | Wiener coefficient | Center peak distance | 2nd peak threshold | Simplex deviations | Server | Command line
Priism | Batch processing interface | EMTIAR | EMTAR | BALIGN | reprojection | two tilt series alignment
The resolution parameter selects which resolution to process from the input tilt series. 0 is the highest (full) resolution. Normally all that you need to do to process a different resolution is set the resolution parameter. There are other parameters in the special parameters dialog that affect the handling of different resolutions (guess resolution, resolution scale, and full size), but in typical cases the user interface chooses correct defaults for those parameters.
The default behavior for the iterative alignment and reconstruction has an initialization step where the mass-normalization parameters are used to generate a mass-normalized (but not aligned) version of the input tilt series. The toggle button next to "Apply massnorm" controls whether or not to use the initialization step. If you have already applied the mass-normalization parameters to the input tilt series, turn the toggle button off; otherwise, make sure it is on.
Two controls affect the application of the mass-normalization parameters during the initialization step. The menu at the end of the "Apply massnorm" line allows you to select the image formation model. You have three choices:
The other control is the pcBase field in the special parameters dialog. For the scaled linear or logarithmic image formation models, the value in that field controls the contribution of an additive term corresponding to a sheet of uniform mass density. The documentation for appl_prm has more information about the pcBase parameter.
These three values (they are in units of pixels) shift the imaginary 3D tilt axis of the projection data from its default location; they are used to center the reconstruction volume on an object of interest. The default orientation of the 3D tilt axis has it pass through the point whose x and y coordinates are the center of the reference projection.
This value sets the size of the z dimension, in pixels, for the reconstructed volume.
EMTIARGPU uses either the SART or EM algorithms provided by gpurecon to calculate the reconstruction from the aligned data. The value in the "Recon. cycles/run" field is the number of iterations of the reconstruction algorithm to perform for each run of the EMTIARGPU steps.
If the "Restart recon" toggle button is on, the reconstructions in all iterations after the first do not start with an initial guess. If the "Restart recon" button is off, the reconstructions use the reconstruction result from the previous iteration as the initial guess. Use the "Initial guess" field to control whether or not the reconstruction during the first iteration uses an initial guess.
By default, the "Restart recon" toggle button is on.
The value in the "Number of Runs" field is the number of iterations that should be performed to refine the alignment parameters and reconstruction.
The iterative alignment and reconstruction procedure will use the directory specified in the "Temporary directory" field for storage of the temporary results: the mass-normalized tilt series from the initialization step (a floating-point data set which has the same dimensions as the input tilt series), the aligned tilt series (a floating-point data set whose size is given by the "Aligned size" and "Section range" fields), the intermediate reconstruction (a floating-point data set whose size is given by the x and y dimensions of the input tilt series and the reconstruction z size), and the reprojection result (a data set which is the same size as the input tilt series). At any given time, the temporary files present will be the result of the initialization step, if any, and, at most, either an intermediate reconstruction and aligned tilt series, or an intermediate reconstruction and reprojection result.
By default, the temporary directory is a directory named tmp in your home directory. You might change the temporary directory if you were short on space in the default directory or the default directory was on a slow disk and you have a fast disk with enough space for the temporary files.
To specify an initial guess for the reconstruction, enter the name of the file containing the initial guess into the "Initial guess" field or press the adjacent button to launch a file browser to help you select the file. The initial guess is optional, if you do not enter anything in the "Initial guess" field or use "none" as the name of the file, the reconstruction will proceed without an initial guess. If you do use an initial guess, its dimensions must match the dimensions of the reconstruction (i.e. have an x size equal to the x size of the input tilt series, a y size equal to the the y size of the input tilt series, and a z size equal to the value in the "Reconstruction Z size" field).
If you select an alignment method that includes Talign, the alignment calculations can generate images of the cross-correlation results, with one cross-correlation image per projection for the most recent iteration. If the field labeled "Cross correlations" is not empty and not set to "none", those cross-correlation images will be written to an MRC file with the name given in the field.
The guess resolution parameter allows you to select which resolution to use from the file containing the initial guess. The dimensions of the resolution you select must be compatible with the dimensions you've specified for the reconstruction.
The iterations of alignment and reconstruction will be numbered from the value in the "Starting run number" field to the value in the "Starting run number field" plus the number of runs minus one. That numbering only affects the names of the output alignment parameter files. If you had previously done n iterations and wanted to see the effect of performing m more with a record of the alignment parameters for all of the m plus n iterations, you would set EMTIARGPU so the input alignment parameter file was the output alignment parameter file from the nth iteration, the number of runs was m, the starting run number was n plus one, and the initial guess was the reconstruction generated by the previous set of iterations.
The resolution scale parameter controls the scale factor applied to the alignment parameters and to the size-related input parameters (reconstruction shift, reconstruction z size, aligned size, and characteristic lengths for the x and y shifts). In the typical case where you select a resolution level to process from the main dialog, the resolution scale factor will be set appropriately. In the case where you are running the iterative alignment and reconstruction on a downsampled tilt series but the input alignment parameters are from a higher resolution version of the 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 relative to the coordinates used for the alignment parameters, set the resolution scale parameter to four) and also adjust the values for the dimensions of the higher resolution data set.
These two values set the x and y dimensions, in pixels, for the tilt series corresponding to the alignment parameters in the input alignment parameter file. For most cases the user interface can correctly determine these values from the dimensions of the input tilt series. One case where you will have to manually change these values is if you use a downsampled tilt series as the input to the iterative alignment and reconstruction but the input alignment parameters correspond to a higher resolution version of the same tilt series. In that case, you should enter the dimensions, in pixels, of that higher resolution tilt series in the "Full size" field and also adjust the resolution scale.
These two values are, respectively, the x and y dimensions, in pixels, of the aligned projections.
These three values set which of the input projections are included in the reconstruction. The first value is the index of the first projection to use, the second value is the index of the last projection to use, and the third is the index step. Allowable values for the indices are between zero and the number of input projections minus one, inclusive.
You have two choices for the reconstruction algorithm. The choices are:
Both algorithms are influenced by the choice of the number of blocks. The sart algorithm is also influenced by the choice of the convergence factor.
The sart or em reconstruction algorithms can be run in a simultaneous mode or block-iterative mode. In the simultaneous mode, each iteration considers all the measurements at once. In the block-iterative mode, the measurements are broken into subsets. At each iteration the subsets are processed in turn; once all the measurements have been taken into account, the next iteration begins. The "Blocks" field sets the number of subsets to use: a value of one in that field selects the simultaneous mode.
The convergence factor is the scalar by which corrections computed in the sart algorithm are multiplied. The convergence factor can be any value greater than zero or less than or equal to two.
Turn on the "Add multires" toggle button to cause the iterative alignment and reconstruction to add lower resolutions to the reconstruction if the x and y dimensions of the reconstruction are large enough. Turn off the "Add multires" toggle button to generate a reconstruction with a single resolution.
Sets the method to use for alignment. You have three choices:
If the "Simplex filter" toggle button is on and you have selected an alignment method that includes the simplex optimization, a high pass filter will be applied to the data sets prior to the simplex optimization. When the "Simplex filter" toggle button is off, a high pass filter is not applied prior to the simplex optimization.
If the "Offset" toggle button is on and you have selected an alignment method that includes Talign, a shift along the tilt axis will be induced with the intent of keeping the peak corresponding to the best shift parameters (that peak would likely be near the origin if the input alignment parameters are sufficiently good) away from the origin which receives special treatment. Before the alignment parameters are written out, the program compensates them for the induced shift. When the "Offset" toggle button is off, no shift along the tilt axis is induced when using one of the methods which include Talign.
If the "Phase weighting" toggle button is on and you have selected an alignment method that includes Talign, phase weighting will be performed to enhance the cross-correlation peak at the expense of less robustness in the face of noise. When the "Phase weighting" toggle button is off, phase weighting is not used to enhance the cross-correlation peak.
When you use phase weighting of the cross-correlations, there is a term like that in a Wiener filter to keep things well behaved when the amplitude of the cross-correlation value in the frequency domain approaches zero. The term is an estimate of the high-frequency power spectral density times the value in the user interface's "Wiener coefficient" field. A higher value for the "Wiener coefficient" increases the suppression of the low amplitude components. The default value is 100.
With the alignment methods that include Talign, the alignment algorithm will try to cancel out the effect of a peak at the origin by subtracting out a radial average over the central 7 x 7 region from that region. The alignment application only performs that subtraction if the largest value in the central 7 x 7 region occurs at the center and the quadratic fit to that point and its four nearest neighbors gives a peak position, (xp, yp), where both the absolute value of xp and yp are less than a threshold value. The threshold value is, by default, 0.05 pixels, You can change the threshold by modifying the value in the "Center peak distance" field.
With the alignment methods that include Talign, the algorithm prefers peaks in the cross-correlation that are away from the origin and only takes the peak at the origin if the next highest peak (after masking out the origin) has a height less than f times the height of the peak at the origin. The default value of f is .001. In the graphical user interface, alter the value in the "2nd peak threshold" field to alter the value of f.
These six parameters set the characteristic length for each of the six alignment parameters that can be refined when aligning a section from the tilt series to a section from the reprojection. A characteristic length scale of zero for a parameter causes the simplex method to not refine that parameter; in the graphical user interface, you turn on or off the refinement of a parameter with the toggle button adjacent to the field which displays the characteristic length. The six alignment parameters are the x shift (in pixels), y shift (in pixels), rotation (in radians), isotropic magnification factor, the orientation angle for the anisotropic stretching axis (in radians), and the anisotropic stretching factor. The first four parameters have a direct effect on the output alignment parameters. The last two (the orientation of the anisotropic stretching direction and the anisotropic stretching factor) do not.
EMTIARGPU will use one or more servers to perform the reconstruction and projection calculations. As long as at least one server is available, the calculations will proceed. When multiple servers are available, the work will be divided among them. The addresses of the servers that EMTIARGPU will use can be seen by pressing the "Configure servers..." button in the main dialog. That will open another dialog which has fields labeled "Server 1" through "Server 8". Those fields contain the names of the servers to contact. The initial values in those fields are drawn from the RGEMT_SERVER_LIST environment variable. You may edit the values to change the servers contacted. An address is usually just the host name (for instance, msg.ucsf.edu) or IP number (for instance, 169.230.20.46) of the server to contact. If the server does not use the default port number, 20248, you should add a colon followed by the port number to use at the end of the address (as an example, msg.ucsf.edu:20000, would contact port 20000 on msg.ucsf.edu). The address may also contain a specification of the protocol to use immediately before the host name or IP number. Currently two protocols are understood:
EMTIARGPU simply generates a script that runs the command-line application, emtiar_gpu. The command-line syntax for emtiar_gpu is (optional parts are enclosed in brackets):
emtiar_gpu input_tilt_series input_align_param \
output_align_param_base output_recon \
[options]
The options that emtiar_gpu understands are:
-block=n
-convf=f
-cor_out=fname
-cpd=d
-cycles=n
-dev=xs:ys:rot:mag:axis:stretch
-dimxy=nx:ny
-fullsize=nx:ny
-gres=i
-imform=code
-imod=m
-istrfile=file
-iv=ivstart:ivend:ivstep
-method=m
-mult=s
-multires
-nofilter
-nooffset
-pcbase=b
-phaseweight
-reconz=nz
-res=i
-restart_recon
-rscale=i
-runs=n
-server=address
-shxzy=xshift:yshift:zshift
-skip_init
-spth=t
-start=i
-tmpdir=directory