====== alifraba ====== alifraba (__ali__gn __fra__mes in __ba__ckground) is a program to align frames acquired from a K2 camera by means of Leginon. The program relies on IMOD routines for the alignment of the frames (//tiltxcorr//, //newstack// and //avgstack//). ===== How it works ===== The program uses an iterative approach to determine the shift to apply to each frame against an average reference, which is refined at each iteration (see documentation on //tiltxcorr// for further details). The result is an average image, obtained either from all the frames or from a subselection of them, as specified by the user (the user can also give a threshold shift such that frames that would need to be corrected for larger values are not included in the average). ==== recovery mechanism ==== Once launched, the program monitors the given input directory and process each new stack of frames that it finds. If no new frames are found in 48 consecutive hours, the program will stop. If the program is stopped or crashes for any reason, it can be relaunched with the same input arguments, and it will only process the frames without an average already calculated. ===== How to launch it ===== The program is installed on the server ''borg'', where the frames are stored, but it can be launched and monitored from the computing server ''phage'', using the following commands: * **alifraba_launch** (with arguments): launch the program by specifying input and output directories * **alifraba_check** (without arguments): check if the program is running and retrieve the process id * **alifraba_kill** (with arguments): kill the program by specifying the process id(s) ===== How to use it ===== The simplest command is alifraba_launch that is you need to specify the input directory where the frames are stored, and the output directory where to save the generated averages. The common practice is to save the averages in directory that is namely consistent with the frames one. Specifically, the frames are saved by default in /dataddd/frames/polara///rawdata and it is recommended to save the averages in /dataddd/averages/polara///rawdata Without options, the program assumes that the gain reference image is located in the same frames directory, and for each frames stack it will use the closest reference according to their time stamps. ==== Dose damage compensation ==== By default the program just aligns the frames and make an average out of the selected ones. Optionally, it can also apply a dose damage compensation scheme, as proposed in ''Grant & Grigorieff, eLife 2015;4:e06980''. In this case, you need to provide the microscope voltage, the pixel size of the images, and the dose received by each frame (e/Angstroms^2). Without providing all three parameters, the dose damage compensation will not be applied ==== Options ==== Below is a full list of the program options Options: -h, --help show this help message and exit -s , --select-frames= List of frames to include in average (default all) -m , --max-drift= Maximum drift (angstroms) accepted in a single frame to be included in average (0=no exclude - default: 20.) --flip= Flip the frames along one or both axes, before gain correction (none,x,y,xy - default: y) --gain-file= Use the given file to normalize images (default: automatically determined) -t , --temp-dir= Directory where to write temporary files (default: /scratch/tmp) --force-align Align frames even if a previous solution is available (default: False) --force-average Average frames even if a previous solution is available (default: False) --skip-align Skip alignment of frames (default: False) -d , --dose= Radiation damage compensation - dose (e/Angstroms^2) received by a single frame (default: none) -v , --voltage= Radiation damage compensation - microscope voltage (kV, default: none) -p , --pixel= Radiation damage compensation - pixel size (Angstroms) of frames (default: none)