SerialEM HowTo: Macro Explained

Chen Xu

$BrandeisEM: ~emdoc-xml/en_US.ISO8859-1/articles/SerialEM-howto:macro-explain/article.xml 1 2015-09-18 05:39:04 xuchen Exp$

The look of macro of SerialEM is very much like a shell script. It contains macro command line or lines. And running a macro is to execute macro command line by line. The macro commands themselves are high level wrap-up of functions which controls microscope and cameras. To me, the macro commands and macro are among the most attractive features in SerialEM. With these, we can controls the scope and camera in very flexible way.

I have tried to learn how to write macro to do my job, mainly for single particle applications. And I continuously learn new things, functions and power of this tool. I like to share what I have learn here. I want to show some examples of the macro I wrote over the past years. I won't be surprising at all if you come up with better macros with clever ideas than I show here. It is my hope that this document can help people new to SerialEM to understand how it works and start to write your own macros.

I list some of the macros here. And I want to explain what the macro is to do and how. I welcome any comments and feedback about these macros. This document will be frequently updated, with new or improved macros.

You can also get pdf version of this document here.

All the macros listed in this document be downloaded and loaded to SerialEM with a single text tile macro-list.txt.


Table of Contents
1 AlignToP
2 AlignToP-quick
3 ZeroIS
4 CropImageAToP
5 Z_byG
6 Z_byV
7 CalEuentricFocus
8 CalEucentricFocus_View
9 Drift
10 CycleTargetDefocus
11 LD
12 LD-Modulo
13 LD-Group
14 TiltPair
15 ZeroIS-quick
16 PrepTS
17 Parameters
18 Functions

1 AlignToP

Example 1. AlignToP


MacroName AlignToP
#  
# a macro to align to an image in buffer P, twice.
# it takes shots and even crop it when needed. At the end, 
# the ImageShift = 0.
# SEM 3-5 beta built 10/10/2014
# update @  2014-11-18 02:09:34

SuppressReports

## Low Dose
ReportLowDose 
If $reportedValue1 == 1
    ImageLowDoseSet P
    S = $reportedValue1
Elseif $reportedValue1 == 0
    ImageProperties P
    S = $reportedValue6
Endif

## get image parameters in buffer P
ImageProperties P
XP = $reportedValue1
YP = $reportedValue2
bin = $reportedValue3
E = $reportedValue4
# PixelSize = $reportedValue5
#S = $reportedValue6

# figure out from which set the image was taken
#(0=view, 1=focus, 2=trial, 3=record, 4=preview)#
If $S == 0
    shot = View
Elseif $S == 1
    shot = Focus
Elseif $S == 2 OR $S == 5
    shot = Trial
Elseif $S == 3
    shot = Record
Elseif $S == 4
    shot = Preview
Endif

## set camera parameters
SetExposure $S $E
SetCenteredSize $S $bin $XP $YP

## align
Loop 2
    $shot
    # Need crop, for Camera like Eagle or Falcon?
    ImageProperties A
    XA = $reportedValue1
    YA = $reportedValue2
    If $XA > $XP OR $YA > $YP
        echo Call CropImageAToP
        Call CropImageAToP
    Endif
    AlignTo P
    ResetImageShift 
EndLoop 

## reset camera
RestoreCameraSet


It might look complicated to you. However, the key part of this macro is actually very simple, as shown below.


## align
Loop 2
   $shot
   AlignTo P
   ResetImageShift 
EndLoop 

It is just to take a shot and align it to the image in buffer P and iterate twice. The image shift value resulted from aligning is then reset and compensated by stage shift. This brings stage to a position the image of which is similar to what in the buffer P. Due to stage movement error, we do it twice to make it more accurate. After this, beam is still straight down, no zigzag, which is good for high resolution imaging.

The rest of the code in the example is to mimic the conditions of image in buffer P: binning, size, exposure time, the camera set (V, F, T, R or L) and even whether in Low Dose mode or not. I even take into account the case that the image in P is cropped one and some camera can not take flexible area as Gatan ones. In this case, the image taken in buffer A is also cropped before being aligned to buffer P.

The goal of this macro is to use a template. Let assume we have picked a point item in a valid map. And this point is close to the center of a hole in Quantifoil or C-flat grid mesh. SerialEM's robust function Realign can bring stage to that point. This procedure leaves a small mount ImageShift in the end. If we have a single centered hole image put in buffer P, running macro in above example will "refine" the stage position to the center of current hole accurately and gets rid of the ImageShift on scope.

This macro can also be called from another macro, like the following one in next section.