xmipp_reconstruct_art (v3.0)
Usage
Generate 3D reconstructions from projections using the ART algorithm (even with SIRT).
A history file with the information of the reconstruction process is created. You can
also give symmetry elements to specify different points of view reusing the projections
you have. The reconstruction is performed using some basis (blobs or voxels) in
different grids (BCC (by default), FCC or CC).
Parameters
I/O Parameters

i <md_file>
 Metadata file with input projections

oroot, o <rootname>
 Output rootname. If not supplied, input name is taken without extension. The created files are as follows:
outputname.vol
3D reconstruction in voxels
outputname.basis
3D reconstruction in basis if the save_basis
option is enabled). The grid parameters are also stored in the same file
outputname.hist
History and information about the 3D reconstruction process

ctf <ctf_file=>
 Metadata file with CTFs

unmatched
 apply unmatched forward/backward projectors

start <basisvolume_file=>
 Start from this basis volume. The reconstruction is performed in the same grid as the one in which the basis volume was stored (any FCC or CC or grid size value are useless)

max_tilt <alpha=10.e+6>
 Skip projections with absolute tilt angle greater than alpha. It means that if alpha=40, then only images with tilt angle within the ranges 0±40 and 180±40 will be processed. (Projection tilt angles are forced to be in the range 0360)

ref_trans_after <n=1>
 Refine the translation alignment after n projections. (Integer type)

ref_trans_step <v=1>
 Maximum displacement in translation alignment. (Double type)

sparse <eps=1>
 Sparsity threshold

diffusion <eps=1>
 Diffusion weight

surface <surf_mask_file=>
 Mask for the surface constraint. It says where the volume is known to be 0

POCS_freq <f=1>
 Impose POCS conditions every f projections

known_volume <value=1>
 The volume is cut down to this mass, ie, the highest [value] voxels are kept while the rest are set to 0

POCS_positivity
 Force ther resulting volume to be positive

goldmask <value=1.e+6>
 Pixels below this value are considered to come frome gold beads and are not used for reconstruction

shiftedTomograms
 Remove external zerovalued border pixels created by alignment of tomograms

dont_apply_shifts
 Do not apply shifts as stored in the 2Dimage headers

variability
 Perform variability analysis

refine
 Refine input projection before backprojecting

noisy_reconstruction
 Perform a companion noisy reconstruction. If given, the algorithm will perform two reconstructions. One with the input data, and another one with pure noise images applying exactly the same procedure as to the signal projections. This reconstruction is further used by the SSNR program in order to calculate the VSSNR or the SSNR itself. The created files are as follows:
[fn_root]_noise.vol
Reconstruction of the pure noise
[fn_root]_noise_proj.sel
Selection file with the pure noise images
[fn_root]_signal_proj.sel
Selection file with the signal images (a reordered version of the input (i) selfile)
[fn_root]_noise_proj.stk
Pure noise images used for the reconstruction

ray_length <r=1>
 Length of the ray in basis units that will be projected onto the image plane
Symmetry parameters

sym <sym_file=>
 Use a symmetry file. It should give symmetry elements, ie, rotational axis, symmetry planes or whatever such that new points of view can be obtained

sym_each <n=0>
 Force the reconstruction to be symmetric each n projections

force_sym <n=0>
 Force the reconstruction to be symmetric n times at each projection

no_group
 Do not generate symmetry subgroup

no_symproj
 Do not use symmetrized projections
Iteration parameters

l <...>
 Relaxation factor, by default 0.01 (recommended range 0.0  0.1). A list of lambda values is also accepted as "l lambda0 lambda1 ..."

n <noit=1>
 Number of iterations

stop_at <it_stop=0>
 Total number of iterated projections before algorithm stops. For instance, if there are 100 images, with two iterations and we want to stop at the half of the second iteration, then you must set it to 150

equation_mode <mode=ARTK>
 Equation to project onto the hyperplane
where <mode> can be:
 ARTK Block ART
 CAV Component Averaging
 CAVK Block Component Averaging
 CAVARTK Component Averaging Variant of Block ART

sort_last <N=2>
 By default the algorithm sorts projections in the most orthogonally possible way. The most orthogonal way is defined as choosing the projection which maximizes the dot product with the N previous inserted projections. Use 1 to sort with all previous projections
 or
random_sort
 Instead of orthogonal sort, projections are presented randomly to the algorithm
 or
no_sort
 No sort must be applied

WLS
 Perform weighted least squares ART

k <...>
 Relaxation factor for WLS residual, by default 0.5. A list of kappa values is also accepted as "k kappa0 kappa1 ..."
Basis Parameters

basis <basis_type=blobs>
 Basis function to use for the reconstruction
where <basis_type> can be:
 blobs <radius=2> <Bessel_order=2> <alpha_param=10.4> Default blob parameters and grid relative size adjusted to use small blobs
 voxels
 splines
 or
big_blobs
 blob parameters and grid relative size adjusted to use big blobs
 or
visual_blobs
 blobs optimal for direct visualization
Grid parameters

g <gridsz=1.41>
 Relative size of the measuring unit in the grid lattice. By default, a unit in the grid system equals 1.41 units in the Universal System. This value is optimized for a BCC structure
if gridsz = 1 => gridsz=2^(1/2)
2 => gridsz=2^(1/3)

grid_type <type=BCC>
 Shape of the grid structure
where <type> can be:
 BCC Body Centered Cubic
 FCC Face Centered Cubic
 SC Simple Cubic

R <interest_sphere=1>
 Radius of the interest sphere. If provided, ART runs twice faster since only the sphere with this radius (in pixel units) is reconstructed

ext <proj_ext=0>
 Projection extension. In order to avoid the box effect (those voxels near the volume borders are brighter than the rest), you can extent your projections resulting in a slower reconstruction but more accurate. Recommended values to avoid the box effect go from 5 to 10

output_size <Xsize=0> <Ysize=0> <Zsize=0>
 Output volume size in Pixels. Reconstruction size is taken from the projection size. However, the output size can be different, if the output volume is bigger, then the volume is zero padded.

sampling_rate <Ts=1>
 Pixel size (Angstrom), affects to r, g, R and ref_trans_step
Parallel parameters

thr <N=1>
 Number of threads to use. NOTE: Not available when using MPI.

parallel_mode <mode=ART>
 Parallel mode
where <mode> can be:
 ART Default
 SIRT Simultaneous Iterative Reconstruction Technique
 pSIRT Parallel (MPI) Simultaneous Iterative Reconstruction Technique
 pfSIRT Parallel (MPI) False Simultaneous Iterative Reconstruction Technique (Faster convergence than pSIRT)
 pSART Parallel (MPI) Simultaneous ART
 pAVSP Parallel (MPI) Average Strings
 pBiCAV Parallel (MPI) Block Iterative CAV
 pCAV Parallel (MPI) CAV

block_size <n=1>
 Number of projections to each block (SART and BiCAV)
Debugging options

print_system_matrix
 Print the matrix of the system Ax=b. The format is:
Equation system (Ax=b) 
pixel=<p> > <b> = <a1> <a2> ...
I.e., for the pixel p (pixels are numbered lexicographically) with experimental value b, the equation ax=b is set. a is the corresponding row of matrix A. The coefficient a_i is equal to the contribution of the basis i to pixel p. x is the number of basis

show_iv <n=10>
 Show volumes/images as the reconstruction goes. The volume is update every n projections

show_error
 Show error for each projection

show_stats
 Give some statistical information during the process, they might be useful to see how the process is going. The mean squared error for each projection is shown by default

save_at_each_step
 Save intermediate projections. This option allows deep debugging as it save all projections and volumes involved in the reconstruction process. After each step you are asked to press a key, so that you could inspect carefully the results. The names for these files are: PPPtheo, PPPread, PPPcorr, PPPdiff PPPbasis.basis, PPPvol.vol PPPvolPOCS1, PPPvolPOCS2, PPPvolPOCS3

save_intermediate <n=0>
 Save intermediate volumes (every projections). If not provided, volumes are stored at each iteration and this parameter must be used at the end of the command to prevent errors. The names for these volumes are:
[filename root]it[it_no].vol Ex: art0001it0.vol
[filename root]it]it_no].basis If the save_basis option is enabled

save_basis
 Save also the 3D reconstruction in basis each time that you have to save the reconstructed volume

manual_order
 You are prompted to give the number of the following projection to be presented to the algorithm

only_sym
 Skip all those projections generated by symmetry (symmetries different from 1)
Examples and notes
 Basis volume definition: The basis volume is defined internally such that it should cover the space cube corresponding to
(Xdim/2,Xdim/2,Xdim/2)
to (X dim /2,Xdim/2,Xdim/2)
where Xdim is the X dimension of the projections.
 Voxel volume definition: The final reconstructed volume is defined in such a way that it covers the whole basis volume. For these two definitions and the fact that the basis has got some radius (normally 2) the final reconstructions are a little wider than the original projections (usually
2*radius+1
)
 Crystal reconstructions: Crystal projections must be the deformed projections of the deformed volume. I mean, the lattice vectors of the volume to reconstruct need not to lie on a grid point inside the BCC, FCC or CC grid. If we ant to force that they lie on a grid point we have to deform the volume. When he have this deformed volume and we project it, the two 3D lattice vectors project to two different 2D lattice vectors, that in principle there is no relationship between them. We must force this two 2D lattice vectors to align with
a=(Xdim,0)
and b=(0,Ydim)
by deforming the projection. This is the second deformation. This complex projections are either generated from phantoms using the program Project or from lists of Fourier spots coming out from MRC as APH files by applying the program Spots2RealSpace2D.
 Surface constraints: These constraints force the volume to be 0 at known places. This has got the beneficial consequence that mass tends to be compacted where it should be.
 Grids: This program defines three grids for working with data. The typical simple cubic grid, the facecentered grid (fcc) and the bodycentered cubic grid (bcc). We define these grids as follows:
Simple Cubic Grid  
Facecentered cubic grid  
Bodycentered cubic grid  
where is the set of integers and is a positive real number called sampling distance. See Gabor H., Geometry of Digital Spaces, Birkhauser, 1998, Massachussets
Spots2RealSpace2D.
In the case of the simple cubic grid the voxels are cubes of volume ³ . The voxels associated to the bcc grid are truncated octahedra, polyhedra of 8 hexagonal faces and 6 square faces, of volume 4 ³ .Finally, the voxels associated to the fcc grid are rhombic dodacehedra, polyhedra of 12 identical rhombic faces, of volume 2 ³. However, in practice the above definitions are implemented using a combination of simple cubic grids. Clearly, a simple cubic grid defines the complex simple cubic grid and thus the relative size used in the implementation is exactly the ³. For defining the bcc grid two simple cubic grids are used, it can be seen from the definition for the bcc above that the valid positions for even values of z
, x
and y
have to be also even, in the case of odd values of z
, x
and y
have to be odd. Consequently, the relative size used in the BCC grid is equivalent to 2 above. For defining the fcc grid four simple cubic grids are used, it can be seen from the definition for the fcc above that the valid positions for even values of z
, the sum of x
and y
has to be even; in the case of odd values of z
the sum of x
and y
has to be odd. Consequently, the relative size used in the FCC grid is equivalent to 2 above.
Basic reconstructing commands:
reconstruct_art i projections.sel o artrec
Create the equivalent noisy reconstruction:
reconstruct_art i projections.sel o artrec noisy_reconstruction
Reconstruct using SIRT parallelization algorithm for five iterations:
reconstruct_art i projections.sel o artrec n 5 parallel_mode SIRT
Save the basis information at each iteration:
reconstruct_art i projections.sel o artrec n 3 save_basis
User's comments
%COMMENT{type="tableappend"}%