Frame File Options Dialog

This dialog has two sections.  The upper section presents choices about the files produced when the SerialEM plugin to DigitalMicrograph saves subframes for a Dose Fractionation exposure.  Nearly everything in this section appears only for Gatan cameras (mostly just for K2/K3).  The lower section, which appears for all cameras that can save frames, allows you to control the name of these files.  Except for Direct Electron cameras with an older server version, you can also put subsets of the files into different folders automatically.  These are global settings that apply to all camera parameter sets in which frames are saved.

Save counting frames in EER file instead of MRC file   (Falcon 4 only)

Select this option to have counting mode frames saved in EER format, namely with a frame saved for every camera readout and every electron event recorded as a count in a compressed TIFF file.

Save metadata (.mdoc) file for each frame stack

Select this option to have a metadata file in the autodoc format, with extension '.mdoc', saved along with each set of frames.  The file will be named with '.mdoc' appended to a frame stack name or to the name of the folder containing single-frame files.  This file will have the same format as the file opened with Open .mdoc for Frames in the file menu, namely the one section in the file will be named 'Frameset'.  For a  K2/K3, it will also have the gain reference and defect file names if frames are taken without normalization.  The gain reference name will also appear for a Falcon 4 saving in EER format.  Additional entries can be added to the file with the script commands 'StartNextFrameStackMdoc' and 'AddToNextFrameStackMdoc', but these commands must be given before acquisition.


Other Gatan Camera Options

File type

The choices here are files in MRC format, TIFF files with LZW compression, and TIFF files with ZIP compression.  Both compressions are loss-less and can be read by programs in IMOD that read TIFF files.  LZW is more effective, and much faster, than ZIP compression for unnormalized K2/K3 images.  ZIP compresses normalized images more, but may be considerably slower. Compression is parallelized, so ZIP compression may still take a reasonable amount of time. If you are saving normalized or K2/K3 linear mode images, you should assess both the compression factor and the acquisition time with the typical images for a project when deciding which form to use on a routine basis.  The best way to assess acquisition time is to turn on Debug Mode in the Camera menu.  With this on, the SerialEM log will show the total elapsed time for acquiring each image.  Also, when frame-saving is complete, the Results window in DM will show a line reporting the time required to process and save all of the frames.  Compression occurs as part of saving, so the saving time is the one that will change with these different options.

Use extension .mrcs

When MRC output format is selected, this option can be used to make the names of the frame stacks end in '.mrcs' instead of '.mrc'.  Some other software requires the '.mrcs' extension to process frame stacks.

Save one frame per file

Select this option to have each saved subframe written as a separate file instead of having all subframes for an acquisition written to one image stack.  They will be written in a uniquely named folder.

Save frames without rotation/flip to standard orientation

This options controls whether the plugin saves frames in the raw orientation as read from the camera rather than rotating and flipping them, if necessary, into the standard orientation at which images are viewed in SerialEM.  Image flipping alone does not take significant time, but rotation does.  Originally, it took 0.05 seconds for K2 counting mode frames and 0.25 seconds for super-resolution frames, but multi-threading in SerialEM 3.7 has reduced the latter to ~0.1 sec.  If you do not care about preserving orientation in the saved frames, you can select this option to reduce frame processing time.  However, handedness will be changed if a flipping operation is being skipped.  This option is enabled only if the current camera has a nonzero RotationAndFlip property.

If you are saving non-gain-normalized frames from a K2/K3 camera, the defect list stored with the frames will be adjusted for the change in orientation.  These defect lists always have a RotationFlip entry showing the orientation to which they apply, and the title in the image file shows the operation applied to the frames after 'r/f' with this option off. 

With this option on, the title in the file header for frames saved from a K2/K3 camera shows 'r/f 0 need' and the operation that still needs to be applied to the aligned sums to have them match the orientation of images in SerialEM.  Alignframes in IMOD 4.12.18 or higher will recognize this 'need' entry and can use it to perform the needed operation on the aligned sums.  If you have selected options to 'Align in IMOD', the Alignframes command file (.pcm file) will now contain the entry 'RotationAndFlip -2', which will result in properly reoriented output from IMOD 4.12.18 and cause no problems with earlier IMOD versions.


Other K2/K3 Camera Options

Save unnormalized frames even if Gain Normalized is selected

Select this option to have frames saved without gain normalization even when you have selected gain-normalized processing in the camera setup dialog.  With this set, you can leave the processing for Record images as gain-normalized as you turn the saving of frames on and off.  You will always get normalized images in SerialEM, and the frames will always be unprocessed.

Reduce normalized super-resolution frames by 2 with antialiasing

Select this option to save super-resolution frames on K2, or counting frames on K3, with the same number of pixels as the camera chip has, after reducing by 2 with antialiasing.  This is the same antialias filtering that is used to reduce the summed super-resolution image to binning 1 or higher for return to SerialEM.  Such images have better high-frequency content than the same size counting mode images from the K2 camera because the high-frequency information being thrown away by sampling at the native pixel size is filtered out rather than aliased into lower frequencies.  This option can thus be used to get some of the benefits of super-resolution data without having images 4 times larger.  For the K2 camera, it will take an additional 3-4 seconds to take super-resolution instead of counting images, plus ~0.1 second/frame to reduce the frames.  For the K3 camera, only the time per frame applies.

For a K3 camera, this option is disabled if the option to take frames binned by 2 is on in the Camera Setup dialog.

Save normalized data as 16-bit with 100 times scaling of sum (K2 only)

This option should not be used; just make sure that you have not selected 'Divide 16-bit by 2' and the precision will be as good as with a K3.  Select this option to have gain-normalized Dose Fractionation frames taken in counting or super-resolution mode saved with 100 times the scaling that is usually applied to a summed image returned to SerialEM.  This extra scaling will eliminate the very small loss in camera efficiency (estimated to be only 0.05%) that occurs when the mean counts are very low.  For counting mode, be aware that counts above about ~16 electrons will be truncated with this extra scaling, for typical K2 camera linear gains.  Such counts are almost certainly hot pixels unless the mean of the image is over 2-3 electrons/pixel, but this extra scaling has no benefit at that exposure level anyway.  For super-resolution mode, there is no truncation, but be aware that the files will be twice the size since the larger counts are stored in 2-byte integers instead of bytes.  This option was added before simulations revealed that the efficiency loss from the regular conversion of scaled normalized values to integers was so small (see 'Signal loss from saving normalized frames as integers' in Direct Electron Detectors, Especially the Gatan K2 and K3).  The option is not available for K3 cameras.

Pack unnormalized data as 4-bit (Super-Res) or 4/8-bit (Counting)    (K2)
Pack unnormalized data as 4-bit    (K3)

This option determines whether Dose Fractionation frames taken without software gain normalization are saved in the form in which they are received by the plugin to DigitalMicrograph (for K2, 16-bit integer for counting mode and byte for super-resolution mode; for K3, bytes) or in a packed form.  When this option is selected and not the one described next, K2 counting mode images are truncated into bytes (maximum 255), and K2 super-resolution or K3 unbinned counting mode images are stored with pairs of 4-bit integers (maximum 15) in each byte.  (The left pixel in a pair is in the low 4 bits and the right pixel is in the high 4 bits of a packed byte.) The data will be raw counts, rather than the scaled values that are saved otherwise (see Direct Electron Detectors, Especially the Gatan K2 and K3.)  Raw super-resolution images are intrinsically only 4-bit, so there will be no truncation when saving them as 4-bit.  Packed 4-bit data can be unpacked with the 'unpack' or 'normalize' command to the 'clip' program in IMOD and, in IMOD 4.8.41 or higher, all programs can read these 4-bit data directly.  Note that when writing compressed TIFF files, the packing of data is mostly redundant to the compression and may save little additional space, but it should be faster with packed 4-bit data because fewer bytes need to be compressed.

Pack unnormalized Counting mode data as 4-bit, not 8-bit   (K2)
Pack unnormalized binned by 2 data as 4-bit, not 8-bit   (K3)

This option allows counting mode data on a K2, or binned by 2 data on a K3, that is taken without gain normalization to be further truncated at 15 and packed into 4-bit integers, instead of into bytes.  This option is enabled and relevant only when the first packing option is selected.  If the mean of a frame is only a few electrons per pixel, then counts above 15 are probably spurious and can be safely truncated.  Otherwise, this option is not appropriate, so be sure that the mean of your frames is low enough before using it for data collection.  This option is not available for K3 cameras.

Use non-standard mode 101 for 4-bit MRC files

With this option on, MRC files with 4-bit data will be marked as mode 101 instead of mode 0, and the X dimension will be the number of pixels in X instead of half of that.  This is a new, non-standard mode supported by some software from UCSF and by IMOD as of version 4.8.41.  Be sure that you will be using software that can read these files before saving data in this mode.


Options for Controlling Folder and File Names

By default, frames from one exposure are stacked into a file that is named with the date and time and placed in the directory specified when the Set Folder button is pressed in the Camera Setup dialog.  This section of the dialog allows you to control the names given to these files by selecting one or more components for the names.  In addition, for the K2/K3 and Falcon cameras, you can select several of these components to use for naming of folders that are created under the specified main directory to hold subsets of the files.  However, for a Falcon 3 camera when the SerialEM property 'SubdirsOkInFalcon3Save' is not set, or Falcon 2 under the new scripting interface, the folder options here are not available if you have specified the name of a folder in the Camera Setup dialog.  For the K2/K3, if you select to save one frame per file in the first section of this dialog, then all the statements here about the name of the "file" refer to the name of the directory created to hold the single-frame images.

Two common uses of these capabilities would be:

  1. Tilt series acquisition: Select the file name of the current file as a component of the folder name, and frames for each series will be stored in a separate folder.
  2. Image acquisition for single-particle reconstruction: Select the label of the Navigator item as a component of the file name, and you will be able to link the frames with a specific location in your map.  If you are storing summed images from SerialEM and have the Navigator open a new file periodically (e.g., for each grid square), you could also select the file name as a folder component and have frames stored in a separate folder for each summed image file.

Base name

The base name can be any text that you want (as long as it contains characters that are legal in filenames).  It can be used in the name of a folder if you check the box in the left ('Folder') column, and/or in the name of the files if you check the box in the right ('File') column.  If the text box is empty, nothing is added.

File name of current open file (minus extension)

The root name of the current open file in SerialEM (i.e., name without extension) can be used in the name of a folder and/or in the name of the files, depending on which box you check.  If there is no open file, nothing is added.

Label of Navigator item

If the Navigator is open, the label of the current item or of the item being acquired can be included in the name of the folder and/or the name of the files, depending on which box you check.  If the Navigator is not open, nothing is added.  If Only when Acquiring at Items is checked, the label will be added only when the Acquire at Items procedure is running.

Sequential number

If this box is checked, a number will be added to the file name, starting with the number set in the text box and incremented for each successive file saved to the same location.  Use the spin button on the right to set whether the numbers should have 3, 4, or 5 digits.  Numbers will have leading zeros so that all numbers have at least the selected number of digits.  The number will be reset to the starting number when the folder name changes or when the parts of the filename (if any) in front of the number change.  It will also be reset if you change the starting number to be higher than the last used number. The last used number and other information are saved in the settings file, so if you exit from SerialEM and restart with the same settings file, it will be able to resume saving with the next number in sequence. The hour-minute-second component of the name is optional if a sequential number is included.  However, it is possible to generate duplicate names when using sequential numbers, so it is recommended that the time component be retained. 

Tilt angle

If this box is checked, the tilt angle will be added to the file name.

Month and day

If this box is checked, the date will be added to the file name.  This box and the next two are not shown for Direct Electron cameras because the filename before the suffix being controlled here already has a date and a unique number.

Hour, minute, second

If this box is checked, a final time stamp will be added to the file name.  Unchecking this box will turn on the sequential number selection.

Numeric date (including year) and time at start of name

This option overrides the separate date and time options and produces a name starting with the year, month as a number, day, and time in the format YYYY-MM-DD_HH.MM.SS.

Multiple Record hole number and position in hole

If this option is checked and multiple Records are being done, a hole identifier and the position in the hole (0 for central shot, numbered from 1 for peripheral positions) will be added to the file name, separated by '-'.  When doing a regular rectangular pattern, the hole identifier will have the form 'XnYm' where 'n' and 'm' are relative to the center of the pattern and can be positive or negative.  On an axis with an even number of holes, the number is never zero and skips from -1 to +1.  For example, a 3x2 pattern will have identifiers X-1Y-1, X+0Y-1, X+1Y-1, X-1Y+1, X+0Y+1, X+1Y+1.  When doing a custom pattern, the identifier is simply a number starting at 1.  When doing a hexagonal pattern, the hole identifier will have the form 'RnHm' where 'n' is the ring number and 'm' is the position in the ring, numbered counterclockwise from a starting point at an angle that is the same for all rings.  To minimize the shift from last hole of one ring to the first hole done in the next, the program will step outward from that last hole instead of starting the next ring at the same angle.  For example, the order of holes at the end of ring 1 will be ... R1H6, R2H11, R2H12, R2H1...