This document describes various ways in which you can run the synchronization code for yourself.

Run Python code to demonstrate the operation of the long-term synchronization updates

We have provided a Jupyter Notebook that demonstrates how the long-term updating of brightfield reference heartbeats is accomplished.

The notebook requires the associated data folder ‘f3b_looping’, available from the same repository as this file and the notebook itself. This data folder includes 149 multipage ‘.tif’ files showing the reference heartbeat collected every third stack during a hybrid optical gating timelapse experiment. If you wish to run the notebook with your own data you will need to collect these multipage ‘.tif’ files from the live GUI (see below).

This data folder also includes two ‘.txt’ data files. One data file with the determined period, timestamp, drift and target frame for each reference set as determined with prospective optical gating only (this has been collected from the outputs of the live GUI and is described in the notebook). If you wish to run the notebook with your own data you will need to collate this data from the ‘period.txt’ files output from the live GUI.

The other data file contains manually identified target frames for each reference set from four different scorers. Full stack brightfield and fluorescence data can be requested from the authors.

Run this file as you would any other Jupyter Notebook. The official documentation for installing and running Jupyter can be found at https://jupyter-notebook.readthedocs.io/en/stable/.

Install “Spim GUI” on a mac and run it

On an apple mac computer, if you follow the instructions in “Installation/spim gui installation instructions.rtf” (“How to install Spim GUI programs from scratch”) then you will be able to launch the Spim GUI program. This will enable you to:
- Replay previously-recorded datasets
- Run “pretend” synchronization on these datasets to see how it would behave
- Observe the long-term synchronization updates in action

Detailed user instructions can be found in “Manual/Manual.pdf”, but brief ‘getting started’ instructions are as follows:

- Launch “Spim GUI” and “Spim GUI long-term sync helper”. You may get a warning about running a program from an “unidentified developer”. You may be able to circumvent this by choosing Open from the File menu rather than double-clicking on the program icon. Otherwise you will need to go to the Security panel in System Preferences and chance your settings.

- When you launch Spim GUI, if you are prompted to select a config file then select “No hardware config.plist” unless you know another one is right for you.

- Select “Emulated Camera…” from the “Cameras” menu. Identify the source directory containing a previously-recorded (brightfield) image sequence, by clicking on the popup menu and selecting “Choose…”. The directory needs to contain tiff files (single- or multi-page tiff format). They are not required to have accompanying .plist files as previously recorded in the Spim GUI, though this is of course permitted (and makes a few additional features available). The data repository associated with this paper includes example datasets that you can use here if you wish.

- A window will appear which is not yet displaying any images (the camera is paused, initially). If you wish, you can hit Step (or indeed un-check ‘Pause’) to see the start of the video sequence. Or otherwise, playback will automatically start when you use this camera for synchronization (instructions as follows).

- Select “Show synchronization controls” from the Window menu.

- Select the camera (likely to be called something like “Emulated”) from the Sync source popup menu. Camera playback will automatically start, along with synchronization analysis. See instructions in Manual.pdf for a detailed explanation of the controls in the Sync Settings window.

- Back in the camera window, click on “Sync frame viewer” to see camera frames that the code has identified as being at the correct synchronization phase in the heartbeat. Important: note that because we are just playing back a previously-recorded video, these displayed frames will not be perfectly synchronized and a small amount of variability will be seen. This is because all the code can do, in this case, is to identify the closest frame out of the available pre-recorded frames.

- In the Sync Settings window, press the Reset button to the right of the status readout that should be reading “In sync”. The code will identify a new set of reference frames (one heartbeat of video), but at the same time the index of the chosen reference frame within this new sequence will be updated to ensure that it corresponds to the same phase in the heartbeat as the one set at the start of the experiment. If you look at the frames displayed in the “Sync frame viewer”, you should not see any change in the synchronization in spite of the reset.

Again, for further information on all available features, see “Manual/Manual.pdf”

Run the synchronization system live on a microscope

All the documentation and designs are provided to enable you to run the sync system live on a microscope… in principle! In practice it is probably easier  if we collaborate with you with this process. We may even be able to loan suitable hardware (camera, timing controller, and possibly even computer) to trial the system for your microscope.

To run it live you would need to:

- Install Spim GUI (see above)

- Connect it to a suitable camera (see “hardware compatibility.rtf”)

- Connect it to a timing controller that understands the (simple) serial communications protocol used by our synchronization system. The communications protocol is specified in the document “xmos_submodule/communications protocol.rtf”

- Electrically connect the timing controller to hardware that you want to synchronize

- Configure Spim GUI to recognise your specific hardware devices (see Installation/config file format.rtf)