DySTrack on the Zeiss LSM880 (ZEN Black)#

tl;dr

If you’ve done this many times before and just need a quick reminder:

  1. Create target dir (on drive with enough free space)

  2. Start DySTrack manager

    conda activate dystrack
python <path-to-config-file.py> <path-to-target-dir> [optional arguments]

  3. Configure prescan and main scan settings and save job files

  4. In MyPiC: import job files, configure image analysis and time course, set positions, set target dir

  5. Double-check that everything is ready, then launch

  6. Ensure everything is running correctly

Before you start#

  • Ensure you have permission to use DySTrack on this microscope

    Risk of damage

    Modern microscopes are expensive machines, and automating them comes with an inherent risk of damage. Do not run DySTrack without permission from the microscope’s administrator, and always ask for help if you are unsure about something.

  • Confirm that DySTrack has been installed and tested

    Otherwise, see Installation.

  • Confirm that a suitable image analysis pipeline for your experiment is available

    See Available DySTrack pipelines for an overview of existing pipelines that come with the DySTrack repo. For information on how to develop your own custom pipeline (advanced), we recommend reviewing the Anatomy of DySTrack pipelines and Developing DySTrack pipelines sections.

Part 1: Start the DySTrack manager#

Important config details

Since MyPiC is used to run DySTrack in ZEN Black, DySTrack must be configured to send coordinates via the Windows registry by adding tra_method : "MyPiC" to manager_kwargs in the relevant config file (see step 3).

Furthermore, MyPiC saves prescans with the prefix DE_1 and images will be in .czi format, so ensure that file_start : "DE_1" and file_end : ".czi" are set in the config file.

Tip

This works the same for all microscopes, regardless of manufacturer (aside from config details noted above).

  1. Make a new target directory for your experiment

    The DySTrack manager will monitor this directory, and experiment data will be saved there. Ensure the hard disk has sufficient free space and allows for sufficiently fast file writing for your use case.

  2. Open a Minifoge prompt

    Depending on how python was installed, you may instead need to open an “Anaconda Prompt” or a standard Windows command prompt.

  3. Activate the environment in which DySTrack has been installed

    Usually it is called dystrack, so run:

    conda activate dystrack

  4. Find/create the configuration file for your experiment

    • Config files are found in DySTrack\run

    • They specify the image analysis pipeline to use

    • They can specify further parameters for the pipeline and the manager

    • To create a new config file, best copy an old one and modify it

    • Ensure that file_start and file_end (and where applicable tra_method) are set correctly

    If you are a non-expert user, the configuration file for your type of experiment should be configured for/with you by a more experienced user and should not require further changes at runtime.

    Additional information is found in the provided config files themselves.

  5. Start the DySTrack manager session in your command prompt:

    python <path-to-config-file.py> <path-to-target-dir> [optional arguments]

    Tip

    Instead of typing the entire file paths into the console, you can drag and drop the config file and the target directory into the console, which will automatically write out the full path.

    If everything is configured correctly, you should see the following message:

    DYSTRACK MANAGER SESSION STARTED!
Monitoring target dir(s) for new files...
Press <Esc> to terminate.

    In addition, you should see a file called dystrack_coords.txt appear in your target directory. The DySTrack manager will write detected coordinates to this file.

Part 2: Configure acquisition settings#

The microscope and sample must be ready for this part.

  1. Configure the main scan settings and save an example stack (job file)

    The main scan produces the actual data of interest for the experiment.

    It is usually a high-resolution, high-quality configuration using high pixel densities, multiple channels, and either AiryScan (usually in FAST/4y mode) or confocal with averaging optimized for SNR. Z-stacks must be a range around the center. Use high/optimal z-resolution for the main scan.

    Save an example stack in a separate folder for job settings, not in the experiment folder.

    Tip

    You do not need to acquire an entire stack as an example; if you start the acquisition and immediately stop it, the resulting empty image can still be saved and contains all the information needed for loading as a job file.

    Side note: Main scan image data for a 3D time course can be quite large (esp. with AiryScan). Double-check that there is enough free disk space, i.e. roughly the size of a main scan stack times the number of samples (if multi-positioning) times the number of time points (plus some spare space for prescans and as a precaution to avoid slow-down of file writing).

  2. Configure the prescan settings and save as an example stack (job file)

    Important

    Unlike for the main scan, do not use AiryScan for the prescan.

    The prescan is used for DySTrack to find coordinates.

    To create a suitable prescan configuration, start with the main scan (unless it is AiryScan) and trade off resolution and SNR for speed to the greatest extent allowed by the image analysis pipeline. Remove any averaging, substantially reduce pixel density, use only a single channel, and trade off laser power for gain.

    Z-stacks must again be a range around the center. Use a (very) low z-resolution for the prescan and include 15-30% spare space outside your sample at the top and bottom (how much is needed depends on the sample and analysis pipeline).

    Save an example stack in a separate folder for job settings, not in the experiment folder.

Part 3: Configure MyPiC#

  1. Open the MyPiC pipeline constructor macro

    Opening MyPiC in ZEN Black

    If this option is not available, MyPiC must first be installed. Speak to an expert user and/or see Installation.

  2. Import the prescan and main scan job files into JobSetter

    Import job files in MyPIC

    (In this example, the main scan is named JOB_cldnb.)

  3. Add prescan and main scan jobs to the pipeline

    Add prescan and main scan jobs to pipeline

    Ensure they are in the correct order (prescan first).

  4. Configure the time course and image analysis parameters

    Important

    Ensure the prescan job is selected when configuring these settings.

    Set timings and image analysis on prescan job

    • Method: Select Online img. analysis

    • Tick Track XY and Track Z (if needed)

    • Tick Interval (not delay) and set how long you want the interval duration and number of repetitions

      Example: Every 10 mins for 12 hours → 10 min interval, 72 repetitions

      Calculate sufficient time for prescan, image analysis (usually quick), and main scan (usually the bottleneck). Multiply by the number of positions when using multi-positioning and add a bit of buffer time.

  5. If using multi-positioning, set your positions

    • Go to Default Positions

    • Select Multiple

    • Mark positions (double-check in live mode that it is centered in z)

    Tip

    Mark all positions with the eyepiece and adjust in live mode.

  6. Select destination folder

    In Saving, select the target directory. This is the same folder that is being monitored by the DySTrack manager.

    Tick .czi as format.

  7. Pause for a moment to mentally review whether everything is ready

  8. Start the experiment

Troubleshooting

If MyPiC fails at any point during setup:

  • Try making new job files (reloading old ones can sometimes cause issues)

  • Then try a MyPiC restart

  • Then try a full system restart

Part 4: Look after your experiment#

Monitor the microscope for the first few time points to ensure everything is working as intended.

A prescan should be rapidly acquired and saved in the target directory. The DySTrack command line should then report detection of the prescan, execution of the image analysis pipeline, and then pushing of new coordinates, which in turn should trigger the main scan and then the next position / time point.

Tip

It’s useful to configure remote access to the microscope PC to periodically check in on the experiment.

After the experiment:

  • The DySTrack manager can be stopped by pressing Esc in the command line

  • The microscope software and hardware should be shut down as usual

  • The main scan images/stacks for each position and time point are saved as separate files

  • Some advice on how to postprocess DySTrack data can be found here.

  • Be sure to (process and) move data to a different storage location asap to avoid filling up the scope PC’s disk drives