alifraba

alifraba (align frames in background) 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).

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).

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.

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)

The simplest command is

alifraba_launch <input directory> <output directory> 

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/<user>/<session name>/rawdata

and it is recommended to save the averages in

/dataddd/averages/polara/<user>/<session name>/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.

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).

Below is a full list of the program options

Options:
-h, --help            show this help message and exit
-s <frames list>, --select-frames=<frames list>
                      List of frames to include in average (default all)
-m <max drift>, --max-drift=<max drift>
                      Maximum drift (angstroms) accepted in a single frame
                      to be included in average (0=no exclude - default:
                      20.)
--flip=<flip direction>
                      Flip the frames along one or both axes, before gain
                      correction (none,x,y,xy - default: y)
--gain-file=<gain reference file>
                      Use the given file to normalize images (default:
                      automatically determined)
-t <temporary directory>, --temp-dir=<temporary directory>
                      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 <radiation dose>, --dose=<radiation dose>
                      Radiation damage compensation - dose (e/Angstroms^2)
                      received by a single frame (default: none)
-v <voltage>, --voltage=<voltage>
                      Radiation damage compensation - microscope voltage
                      (kV, default: none)
-p <pixel size>, --pixel=<pixel size>
                      Radiation damage compensation - pixel size (Angstroms)
                      of frames (default: none)