Frealign: Getting Started
After installation, a number of new Frealign commands should be available. A list of active commands can be obtained by typing
frealign_help
To begin processing data, select a working directory where all the needed files are kept. Change the current directory to this working directory. Frealign requires at least one file containing for each particle the micrograph number and three values describing defocus and astigmatism. For example, a dataset containing 10,000 particles requires a file with 10,000 lines of
1 17000.0 17500.0 30.0 1 17000.0 17500.0 30.0 . . . 100 23500.0 22000.0 55.0
An example file with 100 lines can be found here. IMPORTANT: The numbers on each line must be separated by blanks, not commas. In the example, the micrographs were numbered consecutively from 1 to 100. Other numbering schemes can also be used but it is important that particles from the same micrograph receive the same micrograph number. The defocus values are given in Angstrom and degrees and describe the underfocus (positive value) as written out by the programs CTFFIND3 and CTFTILT.
Alternatively, a full Frealign parameter file can be supplied, containing the following columns:
C PSI THETA PHI SHX SHY MAG FILM DF1 DF2 ANGAST OCC LogP SIGMA SCORE CHANGE
An example file with 100 line can be found here. Values for the Euler angles can be obtained a number of approaches, including brute-force search with a reference or conversion of alignment parameters determined with other software. The magnification (MAG) has to be set to the correct magnification on the detector (often different from the nominal magnification displayed by the microscope). The occupancy (OCC) should be set to 100.0, LogP to 0, SIGMA to 0.5 and SCORE to 0.0. One line is required for each particle. Some scripts to convert parameters determined with different software are provided on the Frealign web page.
If alignment parameters are to be determined by Frealign using a brute-force search, a 3D reference map will also have to be supplied and put into the working directory. Currently, MRC/CCP4, Spider and IMAGIC formats are supported. However, MRC/CCP4 is preferred as it has been tested most extensively.
Frealign uses the following naming scheme for alignment parameter files and 3D maps: File names consist of a seed that should identify the particle (for example 70S for the 70S ribosome), followed by "_M_rN" where M and N are integers that signify the refinement cycle number and reference. Typically, when initializing a Frealign run, only one reference is used (no classification) and the refinement starts with cycle 2. Therefore M and N are both set to 1. The parameter files are expected to have the extension ".par" while MRC/CCP4 files have the ending ".mrc", Spider ".spi" and IMAGIC ".hed" and ".img".
Furthermore, a stack of with the particle images is needed. The number of images must match the number of lines in the parameter file, and the file extension must match the extension of the 3D map files. For Spider files, only stacks with single headers (no multi-image stacks) can be used. The particle images should have normalized densities (for example, by setting the average density of each particle to 0 and the variance to 1). IMPORTANT: No CTF correction must be applied to the stack, and the density of the protein must be dark against a brighter background. The stack does not need to reside in the working directory.
Finally, a control parameter file has to be set up that contains the run parameters for Frealign. This file is called "mparameters" and a template can be retrieved by typing from within the working directory
frealign_template
or
frealign_helical_template
if processing segments of helical filaments. An example is appended below. The template file needs to be edited and updated with correct values for the microscope parameters used during data collection. The seed name for the alignment parameter files and 3D maps must also be entered, as well as the path to the particle stack (excluding the extension). The mparameters file contains different sections to help the user identify required parameters and additional parameters that are only necessary for advanced tuning of the refinement (Expert parameters).
mparameters template file:
Control parameter file to run Frealign ====================================== This file must me kept in the project working directory from which the refinement scripts are launched. Note: Please make sure that project and scratch directories (if specified) are accessible by all sub-processes that are run on cluster nodes. # Computer-specific setting cluster_type none ! Set to "sge", "lsf", "slurm", "stampede", "pbs" or "condor" when running on a cluster, otherwise set to "none". nprocessor_ref 16 ! Number of CPUs to use during refinement. nprocessor_rec 16 ! Number of CPUs to use during reconstruction. mem_per_cpu 2048 ! Memory available per CPU (in MB). # Refinement-specific parameters MODE 1 ! 1, 2, 3 or 4. Refinement mode, normally 1. Set to 2 for additional search. start_process 2 ! First cycle to execute. Output files from previous cycle (n-1) required. end_process 2 ! Last cycle to execute. res_high_refinement 6.0 ! High-resolution limit for particle alignment. res_high_class 8.0 ! High-resolution limit to calculate class membership (OCC). nclasses 1 ! Number of classes to use. DANG 200.0 ! Mode 3, 4 and 5: Angular step for orientational search. ITMAX 200 ! Mode 2 and 4: Number of repetitions of grid search with random starting angles. # Dataset-specific parameters data_input particle ! Root name for parameter and map files. raw_images /path/partice_stack image_contrast N ! N or P. Set to N if particles are dark on bright background, otherwise set to P. outer_radius 170.0 ! Outer radius of spherical particle mask in Angstrom. inner_radius 0.0 ! Inner radius of spherical particle mask in Angstrom. mol_mass 2500.0 ! Molecular mass in kDa of particle or helical segment. Symmetry C1 ! Symmetry of particle. pix_size 1.237 ! Pixel size of particle in Angstrom. dstep 5.0 ! Pixel size of detector in micrometer. Aberration 2.0 ! Sherical aberration coefficient in millimeter. Voltage 300.0 ! Beam accelleration voltage in kilovolt. Amp_contrast 0.07 ! Amplitude contrast. # Expert parameters (for expert users) XSTD 0.0 ! Tighter masking of 3D map (XSTD > 0) or particles (XSTD 0). PBC 2.0 ! Discriminate particles with different scores during reconstruction. Small values (5 - 10) discriminate more than large values (50 - 100). parameter_mask "1 1 1 1 1" ! Five flags of 0 or 1 (e.g. 1 1 1 1 1). Determines which parameters are refined (PSI, THETA, PHI, SHX, SHY). refineangleinc 4 ! When larger than 1: Alternate between refinement of OCC and OCC + angles. refineshiftinc 4 ! When larger than 1: Alternate between refinement of OCC and OCC + angles + shifts. res_reconstruction 0.0 ! High-resolution limit of reconstruction. Normally set to Nyquist limit. res_low_refinement 0.0 ! Low-resolution limit for particle alignment. Set to particle dimention or larger. thresh_reconst 0.0 ! Particles with scores below this value will not be included in the reconstruction. thresh_refine 50.0 ! Mode 4: Score threshold above which search will not be performed. nbootstrap 1000 ! Number of bootstrap volumes to calculate real-space variance map. FMAG F ! T or F. Set to T to refine particle magnification. Not recommended in most cases. FDEF F ! T or F. Set to T to refine defocus per micrograph. Not recommended in most cases. FASTIG F ! T or F. Set to T to refine astigmatism. Not recommended in most cases. FPART F ! T or F. Set to T to refine defocus for each particle. Not recommended in most cases. FFILT T ! T or F. Set to T to apply optimal filter to reconstruction. Recommended in most cases. FMATCH F ! T or F. Set to T to output matching projections. Only needed for diagnostics. FBEAUT F ! T or F. Set to T to apply symmetry also in real space. Not needed in most cases. FBOOST F ! T or F. Set to T to allow potential overfitting during refinement. Not recommended in most cases. RBfactor 0.0 ! B-factor sharpening (when 0) applied during refinement. Not recommended in most cases. beam_tilt_x 0.0 ! Beam tilt in mrad along X-axis. beam_tilt_y 0.0 ! Beam tilt in mrad along y-axis. mp_cpus 1 ! Number of CPUs to use for each reconstruction job. restart_after_crash F ! T or F. Set to T to restart job if it crashes. delete_scratch T ! Delete intermediate files in scratch directory. qsub_string_ref "" ! String to add to cluster jobs submitted for refinement (only for SGE, SLURM and PBS clusters). qsub_string_rec "" ! String to add to cluster jobs submitted for reconstruction (only for SGE, SLURM and PBS clusters). first_particle last_particle frealign_bin_dir scratch_dir # Masking parameters (for expert users) mask_file mask_edge 5 ! Width of cosine edge in pixels to add around mask. Set to 0 to leave mask unchanged. mask_outside_weight 0.0 ! Factor to downweight density outside of mask (normally 0.0 - 1.0). mask_filt_res 0.0 ! Filter radius (in A) to low-pass filter density outside density. Set to 0.0 to skip filtering. mask_filt_edge 5 ! Width of cosine edge in reciprocal pixels to add to filter function.
