Microscopy Pipeline Constructor (MyPiC)
MyPiC is a Visual Basic for Application (VBA) macro for Zeiss confocal microscopes running with the ZEN software (version black >= ZEN2010). The macro has been developed in the group of Jan Ellenberg, EMBL, Heidelberg, and replaces the AutofocusScreenMacro.
The macro allows
- Autofocus based on reflection and fluorescence multi-location time series
- Fluorescence based tracking using the center of mass of the fluorescence signal
- Multi-location time-lapse experiments
- Flexible combination of several independent Z-stack and channel settings
- Flexible combination of imaging with fluorescence correlation spectroscopy (FCS) experiments
- Usage of several different FCS settings
- Adaptive Feedback microscopy support of two triggerable imaging and FCS workflows
Adaptive feedback microscopy combines microscopy acquisition with online image analysis to perform complex experiments without user supervision.
Disclaimer: MyPiC has been tested on Zeiss LSM 780 microscopes with ZEN 2010, 2011, and 2012, and LSM880 microscopes with ZEN2.1 and ZEN2.3. We don’t guarantee that it will work on other configurations and we don’t take any responsibility for damage occuring during or after the use of MyPiC.
Definitions
Throughout this manual we will use the following definitions:
- Imaging job: Stores specific settings for imaging. The settings include laser power, Z-stack, pixel dwell time, etc. These are all the settings that can be defined in the ZEN software
- FCS job: Stores specific settings used for FCS measurements
- Task: An imaging or FCS job which can be associated with additional processing steps, e.g. tracking in XY
- Pipeline: A concatenation of tasks that will be executed one after the other. In MyPiC we have a Default pipeline that is executed at every position and two pipelines (Trigger1 and Trigger2) that can be triggered from external programs (i.e. adaptive feedback microscopy)
Installation and start
-
Copy the file MyPiC.lvb (for ZEN2010 use the file MyPiC_ZEN2010.lvb) and the directory resources to a directory that can be accessed from the computer running ZEN
-
In ZEN Open the Macro tab (Alt-F8), and click on Edit Macro
Load the macro into ZEN| Explanations of the buttons --------------|----------------------------
| 1. Load the macro. Browse to the file MyPiC.lvb
or MyPiC_ZEN2010.lvb for older ZEN versions
2. Run the macro
3. To insert the macro in your list of macros click on the tab| Provide a Menu Entry, a text, and select MyPiC.lvb as project
Troubleshooting the installation
For any issues please contact one of the developers in the Ellenberg group at EMBL, Heidelberg, and provide the version of the software, the full version of your ZEN software (Help->About), and all the log and err files. If you have a ZEN version higher than 2010 and the macro complains that it does not find Zeiss.Micro.AIM.ApplicationInterface.dll
, you may need to register it manually.
You can try this fix
• Open a console window (cmd.exe)
• Go to the ZEN path: cd ..\..\ZEN
• Register the Zeiss.Micro.AIM.ApplicationInterface.dll
C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe /tlb /codebase Zeiss.Micro.AIM.ApplicationInterface.dll
• When you uninstall ZEN make sure to un-register using
C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe/u /tlb /codebase Zeiss.Micro.AIM.ApplicationInterface.dll
Setting up an experiment with MyPiC
After MyPiC has started, the user proceeds through several steps before starting an experiment. When an experiment is repeated all settings can be reloaded from example images and configuration files (see Start acquisition, save and reload settings).
- Create jobs using JobSetter
- Add tasks to the Default Pipeline
- Set execution, saving, and processing options of a task
- Define repetitions
- Define stage positions for the Default Pipeline
- Define the saving options
- Start acquisition, save and reload settings
An example workflow using glass reflection autofocus or fluorescence based autofocus is given here
-
Simple workflows with MyPiC
- Glass based reflection and imaging
- Fluorescence intensity center of mass based tracking
The interaction with the adaptive feedback microscopy is explained in
Create jobs in the JobSetter
The JobSetter is started by clicking on the corresponding button (1) JobSetter
In the JobSetter window the user can create Imaging and FCS jobs to be used in one or several pipelines. The user specifies acquisition settings within ZEN and then uploads the settings into the VBA macro as a job. Imaging jobs can also be created by loading a set of microscopy images (czi or lsm format) previously acquired on the same microscope.
Caution Do not load settings from images acquired on a different microscope. This may not work and impair the functionality of the system.
Caution If using Tile imaging and Online image analysis set the Online image stitching threshold to 1. Otherwise the generated image will not have the size expected by the macro. This will impair the computation of new coordinates.
Create imaging jobs with the JobSetter
Remarks for the imaging settings
- Z-stack: Use the option Center instead of First\Last. This has proven to be more reliable in the macro. This option is accessed when pressing the Show all option in the Z-stack menu bar. Recenter the stack before loading into MyPiC
- Time-lapse: The macro has its own time-lapse mode. For each time point an image is acquired and saved. However, the user can still load a job that contains time series. This can be useful for specific workflows
- Multi-position: The macro allows the user to define a multi-position experiment. Multi-position defined within ZEN is allowed. However, in this case the position in the macro should be set to single position
- Definite Focus: If the microscope has Zeiss Definite focus this can be used within the macro. However note that the position of the focus stabilizer will be initiated at the current position stored in the macro
- Combine several imaging settings: To minimize the hardware time overhead it is best to optimize the different imaging settings so that the least hardware parts (e.g. MBS, pinhole) are modified between imaging jobs
Create FCS jobs with the JobSetter
For FCS jobs the loading is similar as for imaging jobs. However, you can't load the settings directly from a file into the JobSetter. If using a file, please load the file into ZEN and press Re-use
. Several different FCS settings can be stored. For this the user must use different names of the light-path for each FCS job.
Add tasks to the Default Pipeline
In a pipeline the user specifies the sequential order of imaging and FCS tasks from jobs previously loaded into the macro using the JobSetter. For a FCS task, FCS positions need to be specified via the adaptive feedback method otherwise the FCS measurement will not be acquired. The Default pipeline is the imaging workflow executed at every position and repetition.
Set execution, saving, and processing options of a task
For each imaging and FCS task several options can be specified. These determine when to execute and save a task. Furthermore, the user can set a Z-offset
with respect to the reference Z-location (see also Define stage positions for default pipeline).
For imaging tasks the user can specify further processing steps. For instance, the macro can compute a new XYZ position from the center of mass of the fluorescence image. The current reference position can then be updated with the computed new position (options TrackXY and/or TrackZ are on). This feature is useful to track bright objects in 3D. More complicated processing steps can be achieved when an external image analysis program is used (see also Adaptive feedback microscopy/Online image analysis).
The computations
Center of mass
andCenter of mass (thr)
within MyPiC do not work with images acquired with the Airy Detector. To track objects using the Airy detector acquired images refer to the Adaptive feedback microscopy/Online image analysis.
Task options
Explanations of the buttons
- Set when task will be acquired. This is every N repetitions or at the start or the end of repetitions.
- Save: Set if task should be saved.
- Z-Offset: Offset added/subtracted from the current reference Z position. This does not change the reference Z-position for subsequent tasks.
- Execute all tasks in a pipeline once (used to test a pipeline).
- Process Image/Tracking methods
- None: Do not perform any analysis.
- Center of mass (thr): Center of mass of upper 10% intensity. Optimal to compute position of glass reflection .
- Peak: XYZ coordinate of maximal intensity
- Center of mass: Center of mass for the intensity. Optimal to track sparse bright objects
- Online img. analysis: Adaptive feedback option. Wait for feedback from an external image analysis program
- Channel: Channel to be used for processing (does not apply for Online img. analysis)
- Track Z: Update reference Z position with computed value
- Track XY: Update XY position with computed value
Define repetitions
The user needs to define the time interval and number of repetitions executed at every position. Note that compared to ZEN Time Series
mode the hardware time overhead is higher (~0.5-2 sec depending on the settings), limiting the minimal time-interval. The advantage of MyPiC is to perform different types of imaging and optionally to combine the workflow with image analysis at every time-point and position. Each repetition is saved in a seperate file with the suffix TXXXX.
Define stage positions for the Default Pipeline
MyPiC allows the user to acquire images using different stage positions. Positions are specified by moving the stage and pressing the Mark (8) button in MyPiC. Positions and subpositions can also be loaded from a file.
- Wells/Positions: Specify a number of positions where imaging is performed. This could be for example wells in a multi-well sample.
- Subpositions: Subpositions are imaging positions defined with respect to wells/positions. Each well/position can have one or several subpositions.
Default positions | Example on how (sub)positions are imaged and named |
---|---|
Explanations of the buttons
- Single: performs imaging at current stage position
- Multiple: Imaging at multiple positions specified by the user using Mark (8)
- Grid: Use a regularly spaced grid + subgrid. The first marked position sets the first point of the grid
- Multiple + Subgrid: For each position specified by the user a regularly spaced subgrid is used (see 13-14)
- Load positions: Load file with ending *.pos
- Save positions to a file *.pos
- List of positions
- Mark: Add current stage position to list (7)
- Move To highlighted position
- Remove highlighted position
- Update highlighted position with current stage position
- Number of rows and columns for grid and distance between grid points
- Number of rows and columns for subgrid and distance between grid points
- Position of subgrid with respect to main grid position (red circle)
- Left: Grid position is the first subgrid position
- Right: Grid position represents the center of the subgrid
- Order of imaging
- Left: Image all subpositions of a well and then move to the next well
- Right: Image one subposition of a well and then move to the next well
- File name of *.pos file to be loaded
Define the saving options
Images and FCS measurements are saved in a main directory specified by the user. A sub-directory per position/subposition is automatically generated.
Saving directory | Explanations of the buttons |
---|---|
1. Name of main folder 2. Browse through folders 3. Prefix before name ID of file 4. Format of image file. For AIRY images save as czi only |
Airy detector For images acquired with the Airy detector the user must use the czi format.
File naming convention
Each time point and each position is saved in a separate file. The file name contains the ID for well, position, and time point. For the default pipeline this reads
DE_t_WXXXX_PYYYY_TZZZZ.* or basefilename_DE_t_WXXXX_PYYYY_TZZZZ.*
where
- t: task number
- XXXX: 4 digit well identifier
- YYYY: 4 digit well identifier
- ZZZZ: 4 digit time point identifier
Each well is saved in a separate directory named
DE_WXXXX_PYYYY
If the number of subpositions is > 1, there is a subdirectory per subposition.
DE_WXXXX
DE_WXXXX_PYYYY
Start acquisition, save and reload settings
After all the previous steps have been performed, acquisition can be started from the main menu of MyPiC. To reload an experiment without performing every single step the user requires
- example files of each imaging and/or FCS job to be loaded into MyPiC with the JobSetter and the
- file containing the task specifications for each pipeline: PipelineConstructor.ini
A file PipelineConstructor.ini is automatically generated when the start button has been pressed.
Simple workflows with MyPiC
Glass based reflection autofocus and imaging
In this workflow at each repetition the microscope acquires a XZ scan and estimates the Z position of the glass reflection line. Imaging is then performed at a certain Z offset from this estimated position.
Define an autofocus job (named e.g. AF) and an imaging job (named e.g. LR). In MyPiC set in the Default pipeline as first task AF with processing Center of Mass (thr) and Track Z. The second task is LR. Specify a Z offset value to achieve the required distance from the cover glass.
For the imaging settings try to use the same light-path for both jobs. For example use 488nm and 561nm laser to image GFP and RFP and 633nm laser to measure the glass surface reflection. For the autofocus choose a XZ line scan with several stacks. In absence of a piezo a larger slice interval and smaller Z range can be used in order to avoid a slow acquisition.
For the XZ reflection of glass scan do not use
Fast Z line
. This mode is not precise enough.
Example settings are given here:
LR imaging settings | AF glass reflection settings |
---|---|
AF scan mode | AF Z-stack |
Fluorescence intensity center of mass based tracking
This workflow can track bright objects at low resolution, followed by imaging the object of interest at high resolution. The pipeline works best for sparse objects. If several bright objects are in the same field of view, the tracking of a single object may fail.
Define a low resolution job, named LR, with a large field of view (low zoom) and fast acquisition. Define a high resolution job, named HR. Try to use similar light-path settings for the two jobs. Add to the default pipeline LR as first task with processing Center of Mass and Track Z, Track XY. Specify the channel to process. Add the HR job as second task.