Xmipp

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 040 and 18040 will be processed. (Projection tilt angles are forced to be in the range 0-360)
--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 zero-valued border pixels created by alignment of tomograms
--dont_apply_shifts
Do not apply shifts as stored in the 2D-image 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 face-centered grid (fcc) and the body-centered cubic grid (bcc). We define these grids as follows:
    Simple Cubic Grid image004.gif
    Face-centered cubic grid image008.gif
    Body-centered cubic grid image006.gif
    where image010.gif is the set of integers and image002.gif 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 image013.gif . The voxels associated to the bcc grid are truncated octahedra, polyhedra of 8 hexagonal faces and 6 square faces, of volume 4 image013.gif .Finally, the voxels associated to the fcc grid are rhombic dodacehedra, polyhedra of 12 identical rhombic faces, of volume 2 image013.gif . 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 image013.gif . 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 image013.gif 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 image013.gif 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"}%