ZEISS Knowledge Base

This module (also known as conditional or adaptive experiments) allows you to define specific rules and actions to be performed during the acquisition of an experiment. It is possible to change the course of an experiment depending on the current system status or the nature of the acquired data during acquisition. Moreover, it is possible to integrate certain tasks like data logging or starting of an external application, directly into the ZEN experiment. A typical use case is to connect the image acquisition with automated image analysis.

Feedback experiments can be set up and controlled with the Experiment Feedback Tool and the Script Editor. For an example workflow for experiment feedback, see Workflow Experiment Feedback.

Note that we do not describe experiment feedback in detail here, as you can find a detailed instruction on how to perform feedback experiments and a lot of tutorials with the latest ZEN installation, if you activate the entry OAD Samples in the ZEISS Microscopy Installer. The tutorials and documentation are then placed in a folder on your PC like C:\Oad\Experiment Feedback. Experiment Feedback uses IronPython 3.4.

Key Features

Create smart experiments and modify the acquisition on-the-fly based on online image analysis, hardware changes or external inputs (e.g. TTL signals).
The adaptive acquisition engine allows modifying running experiments according to the rules defined inside the feedback script.
The feedback script uses ZEN commands in combination with the Python programming language.
The feedback script gives access to the current system status and results from the online image analysis during runtime of an experiment.
Data Logging or starting an external application (e.g. Python, Fiji, MATLAB, etc. ), directly from within the imaging experiment is possible.

Workflow Experiment Feedback

In the figure you can see the typical workflow of an Experiment Feedback experiment and the most important steps involved. The yellow boxes Define Experiment, Define Image Analysis and Define Rules and Observables show the most important steps for setting up a feedback experiment.

Step	Description
Define Experiment	Set up and configure the actual image acquisition experiment to obtain the desired image data, e.g. time lapse, Z-stack, multichannel, tile acquisition, etc. Once the setup of the acquisition is completed, you acquire sample data which will be used in the following step to setup and test the image analysis setting.
Define Image Analysis	Sets up an image analysis setting via the Image Analysis Wizard for the use inside the feedback script if an analysis step is required. Only parameters specified in the image analysis setting can later be accessed from within the experiment feedback script. Test the image analysis setting to ensure the results of the image analysis are meaningful. For more information on the Image Analysis Wizard, see Creating a New Image Analysis Setting. For advanced analysis requirements it is also possible to use an OAD macro to create an image analysis setting (*.czias file).
Define Rules and Observables	This step defines how the script actually works. Here you define the rules in the feedback script, e.g. which parameters are observed and how the experiment should react when a certain event occurs.
Start Experiment	Start the Experiment Feedback experiment and watch the output. The general concept behind this workflow can be described as a loop, which is the actual acquisition. For every event, e.g. when a new image has been acquired, the script will be executed. The rules are checked and if required, certain tasks are carried out. Additionally, it is possible to log data into a text file and/or start an external application at any time point during the experiment.

Editing the Feedback Script

To use the Experiment Feedback tool, you need to edit the feedback script.

The main loop script run will only be triggered, when an observable that is used in the main loop script has changed. If the parameters within the loop script do not change, the script will not be executed.

These changes can be:

A new image has been acquired
The XYZ position has changed
The status of a trigger port has been altered
The settings for filter, objective, light source, etc. have changed
The incubation parameters have changed

For advanced use cases it is possible to execute the script with the command RunLoopScript in conjunction with a timer.

Select Acquisition tab > Experiment Feedback tool > Edit Feedback Script.
The Script Editor for Experiment Feedback dialog opens. For more information, see Script Editor for Experiment Feedback Dialog.
Create and edit the feedback script in the following sections: the PreLoop Script, the Loop Script and the PostLoop Script. To do so, use the commands on the Command tab. Add observables and actions to your experiment feedback script either via double-click or drag-and-drop. All observables and actions are also available via IntelliSense auto-completion starting with ZENService.
If an image analysis is part of your feedback experiment, you can select an existing image analysis you previously created. Select Command tab > Available Observables section > Analysis drop-down menu.
A list of the features that were defined in this image analysis setting, e.g. number of cells detected, is displayed. If you selected an image analysis setting and use one or more features in the feedback script, this image analysis setting is executed for each acquired image. Note that only features you have previously defined in the Image Analysis Wizard are available from within the Feedback Experiment. If you make any changes within the image analysis wizard to an existing *.czias file, you need to reload it in the feedback script editor to activate the changes in the feedback experiment.
Click OK.
The existing code is validated. You can only save and close the script editor if the code is free from syntax mistakes.

The feedback script will be stored as part of the experiment file *.czexp.

Parameter		Description
Edit Feedback Script...		Opens the Script Editor dialog. There you can create scripts for an Experiment Feedback.
Select script runtime conditions
-	Free Run	Upon the experiment start the acquisition and the feedback script are started but run from here in a completely unsynchronized manner. The online image analysis or the script run itself will not slow down the actual image acquisition.
-	Synchronized	This mode will lead to strictly determined order of events depending on the chosen level of synchronization. The online image analysis and/ or the feedback script will be started after current acquisition is finished. In contrast to the Free Run mode, a synchronized run can slow the whole acquisition down. The big advantage of the mode is, that the synchronized run ensures a predictable workflow.
Define Script Slot		Here you define the experiment feedback sequence by arranging the slots (represented by blue buttons). The blue slots run one after another the non-blue slots are run separately. The Acquisition slot represents the actual image acquisition. The Analysis slot represents the online image analysis. The Script Run* slot represents the execution of the experiment feedback loop script. Note that the loop script will be only executed when triggered by a used observable inside the loop script. The HD Writing slot represents the slot for writing the image data to your hard drive.
Allow additional loop script runs		Triggers the main loop if observables that are not part of the multidimensional experiment (e.g. frame index, time index, block index, etc.) change. Those observables could be time or temperature of the incubation. If the checkbox is not activated only experiment observables trigger the main loop script. This only applies when the acquisition is idle. This only applies when acquisition is idle.

Input Windows

The three windows on the left allow you to input scripts based on the programming language Python:

Window	Description
Pre Loop - Single Execution on Experiment Start	Import modules and define functions or variables. This part is executed only once at the beginning of the feedback experiment.
Loop Script - Repetitive Execution During Experiment Runtime	Executed every time an observable used within the loop script changes. Allows to modify the experiment on-the-fly and react on results from the online image analysis, e.g. stop the acquisition when a defined number of cells have been counted, or to take action upon external signals.
Post Loop Script - Single Execution on Experiment Stop	Define actions that are executed only once when the acquisition is finished, e.g. write the data in a logfile or play a sound when the experiment is finished.
Clear output	Clears the output messages field.
Accept	Adopts the script within the experiment without closing the window.
OK	Adopts the script and closes the window.
Cancel	Leaves the dialog without adopting the script.

For more information, see Editing the Feedback Script.

The Commands tab on the right contains all commands for observables, actions and editor tools.

Parameter		Description
Available Observables		Observables are conditions or parameters that can be determined and observed during the course of the experiment. Select observables, actions and tools by clicking on the black triangle at the right-hand edge and dragging the desired action from the list to the desired input area. The following observables are available:
-	Analysis	Analysis observables contain measurement parameters from image analyses that have been previously defined, e.g in the Image Analysis Wizard. Only those variables that are specified through the selection of the measurement program appear in the list.
-	Experiment	Experiment observables relate to the experiment currently running and display the current time point or the current Z-stack plane, for example.
-	Hardware	Hardware observables include, for example, the status of connected devices, such as trigger devices, or incubators.
-	Environment	Environment observables describe the system environment, such as the time or available memory space on the computer.
Available Actions		Actions are possible actions and reactions that can be performed during the experiment. These can vary greatly and include, for example, changing microscope hardware, changing camera parameters, generating notifications or audible alerts, calling up other programs or canceling the experiment.
-	Experiment Actions	Commands that can be used to modify a running experiment on-the-fly. It also includes modifying hardware parameters which are typically part of an acquisition experiment, like exposure times or light source intensities.
-	Hardware Actions	Hardware Actions are modifications of a running experiment concerning the incubation, XYZ positions and the Digital IO ports.
-	Extra Actions	Commands that can be used to log any kind of data into a text file or to start an external application outside ZEN at any time during a running experiment.
Editor Tools		The Editor tools include sample scripts, allow to play sounds or write debugging outputs.
-	Examples and Templates	Contains a small collection of script samples to illustrate some basic ideas of the feedback script. You can adopt the sample scripts by double-clicking. After receiving a prompt, the current content in the script window is overwritten entirely .
Validate Script		Checks your script for errors. An information is displayed if your script is valid or not.
Information
-	IO Card Port Labels	Contains the exact naming of the available IO ports for the current system.

Actions - Experiment

Depending on the present hardware they shown options might vary, e.g. it is only possible to set the laser intensity, if there is a laser engine configured.

ContinueExperiment
Complete Command	ZenService.Actions.ContinueExperiment()
Input
Output
Description	This will continue the current experiment in case it was paused.

JumpToBlock
Complete Command	ZenService.Actions.JumpToBlock(int newBlockIndex)
Input	integer newBlockIndex
Output
Description	This will jump to the specified experiment block inside a heterogeneous experiment.

JumpToContainer
Complete Command	ZenService.Actions.JumpToContainer(string containerId)
Input	string containerId
Output
Description	This will jump to the specified container of the sample carrier.

JumpToNextBlock
Complete Command	ZenService.Actions.JumpToNextBlock()
Input
Output
Description	This will jump to next acquisition block defined inside the Experiment Designer tool

JumpToNextContainer
Complete Command	ZenService.Actions.JumpToNextContainer()
Input
Output
Description	This will jump to next container inside the currently used sample carrier.

JumpToNextRegion
Complete Command	ZenService.Actions.JumpToNextRegion()
Input
Output
Description	This will jump to next defined region.

JumpToPreviousBlock
Complete Command	ZenService.Actions.JumpToPreviousBlock()
Input
Output
Description	This will jump to the previous acquisition block inside the experiment designer tool.

MoveTileRegion (1)
Complete Command	ZenService.Actions.MoveTileRegion(int regionIndex, double x, double y)
Input	integer regionIndex, double x [nm], double y [nm]
Output
Description	Updates the specified tile region inside the tile region list with the given X and Y coordinates.

MoveTileRegion (2)
Complete Command	ZenService.Actions.MoveTileRegion(int regionIndex, double x, double y, double z)
Input	integer regionIndex, double x [nm], double y [nm], double z [nm]
Output
Description	Updates the specified tile region inside the tile region list with the given X, Y and Z stage coordinates.

MoveTileRegionByOffset
Complete Command	ZenService.Actions.MoveTileRegionByOffset(int regionIndex, double offsetX, double offsetY, double offsetZ)
Input	integer regionIndex, double offsetX [nm], double offsetY [nm], double offsetZ [nm]
Output
Description	Updates the specified tile region inside the tile region list with the given offset in X, Y and Z.

PauseExperiment
Complete Command	ZenService.Actions.PauseExperiment()
Input
Output
Description	This will pause the current running experiment.

ReadLEDIntensity
Complete Command	ZenService.Actions.ReadLEDIntensity(int trackindex, double wavelength)
Input	integer trackindex, double wavelength [nm]
Output	double intensity
Description	This will read the intensity for the specified track and LED.

ReadTLHalogenLampIntensity
Complete Command	ZenService.Actions.ReadTLHalogenLampIntensity(int trackindex)
Input	integer trackindex
Output	double intensity
Description	This will read the intensity for the specified track and LED.

SetExposureTime (1)
Complete Command	ZenService.Actions.SetExposureTime(int channelindex, double exposure)
Input	integer channelindex, double exposure [ms]
Output
Description	This will set the exposure time of the camera for the specified channel.

SetExposureTime (2)
Complete Command	ZenService.Actions.SetExposureTime(int trackindex, int channelindex, double exposure)
Input	integer trackindex, integer channelindex, double exposure [ms]
Output
Description	This will set the exposure time of the camera for the specified track and channel.

SetLEDIntensity
Complete Command	ZenService.Actions.SetLEDIntensity(int trackindex, double wavelength, double intensity)
Input	integer trackindex, double wavelength [nm]
Output
Description	This will set the intensity for the specified track and channel.

SetLEDIsEnabled
Complete Command	ZenService.Actions.SetLEDIsEnabled(int trackindex, double wavelength, bool isEnabled)
Input	integer trackindex, double wavelength [nm], boolean is Enabled
Output
Description	This will enable the specified LED for the specified track. The predefined intensity value will be used.

SetMarkerString
Complete Command	ZenService.Actions.SetMarkerString(string markerText)
Input	string markerText
Output
Description	This will insert a marker at the current time point.

SetTimeSeriesInterval (1)
Complete Command	ZenService.Actions.SetTimeSeriesInterval(double interval, Time-Unit unit)
Input	double interval, TimeUnit unit (e.g. TimeUnit.ms)
Output
Description	This will set the interval of a time series to the specified value.

SetTimeSeriesInterval (2)
Complete Command	ZenService.Actions.SetTimeSeriesInterval(double interval)
Input	double interval [ms]
Output
Description	This will set the interval of a time series to the specified value in [ms].

SetTLHalogenLampIntensity
Complete Command	ZenService.Actions.SetTLHalogenLampIntensity(int trackindex, double intensity)
Input	integer trackindex, double intensity
Output
Description	This will set the intensity of the TL Halogen lamp for the specified track.

StopExperiment
Complete Command	ZenService.Actions.StopExperiment()
Input
Output
Description	This will stop the current running experiment (similar to pressing the Stop button).

UpdateZStackCenterPosition
Complete Command	ZenService.Actions.UpdateZStackCenterPosition(double center- Position)
Input	double center position [nm]
Output
Description	Updates the center position of the defined Z-stack with the specified center position.

UpdateZStackCenterPositionByOffset
Complete Command	ZenService.Actions.UpdateZStackCenterPositionByOffset(double centerPositionOffset)
Input	double center position offset [nm]
Output
Description	Moves the center position of the defined Z-stack by the specified offset.

ExecuteHardwareSetting
Complete Command	ZenService.HardwareActions.ExecuteHardwareSetting(string settingNameInExperimentSettingsPool)
Input	string settingNameInExperimentSettingsPool
Output
Description	Loads a specific experiment setting from the list of experiment settings. The settings will be overwritten within the next experiment loop, if the settings are included in the regular experiment settings.

ExecuteHardwareSettingFromFile
Complete Command	ZenService.HardwareActions.ExecuteHardwareSettingFromFile(string hardwareSettingFilePath)
Input	integer string hardwareSettingFilePath
Output
Description	Loads a specific experiment setting from a file directly. The settings will be overwritten within the next experiment loop, if the settings are included in the regular experiment settings.

PulseTriggerDigitalOut
Complete Command	ZenService.HardwareActions.PulseTriggerDigitalOut(string port-Label, double duration)
Input	string portLabel, double duration
Output
Description	Produces a TLL pulse with a specified duration at the selected trigger port.

PulseTriggerDigitalOutX (X=7-8)
Complete Command	ZenService.HardwareActions.PulseTriggerDigitalOutX(double duration)
Input	double duration
Output
Description	Produces a TLL pulse with a specified duration at trigger port X.

ReadFocusPosition
Complete Command	ZenService.HardwareActions.ReadFocusPosition(double Position- InMicrometer)
Input	double PositionInMicrometer
Output
Description	Get the current value of the Z-drive. This function was placed under the category HardwareActions, and not under Observables, since they trigger the execution of the main loop of the script automatically when changing.

ReadStagePositionX
Complete Command	ZenService.HardwareActions.ReadFocusPosition(double Position- InMicrometer)
Input	double PositionInMicrometer
Output
Description	Get the current value of the stage X-axis. This function was placed under the category HardwareActions, and not under Observables since they trigger the execution of the main loop of the script automatically when changing.

ReadStagePositionY
Complete Command	ZenService.HardwareActions.ReadFocusPosition(double Position- InMicrometer)
Input	double PositionInMicrometer
Output
Description	Get the current value of the stage Y-axis. This function was placed under the category HardwareActions, and not under Observables since they trigger the execution of the main loop of the script automatically when changing.

SetFocusPosition
Complete Command	ZenService.HardwareActions.SetFocusPosition(double Position- InMicrometer)
Input	double PositionInMicrometer
Output
Description	Sets the focus drive to the specified position. Currently the piezo drive is not accessible from the Experiment Feedback script.

SetIncubationAirHeaterIsEnabled
Complete Command	ZenService.HardwareActions.SetIncubationAirHeaterIsEnabled(bool IsEnabled)
Input	bool IsEnabled
Output
Description	Enables the AirHeater of the incubation system.

SetIncubationAirHeaterTemperature
Complete Command	ZenService.HardwareActions.SetIncubationAirHeaterTemperature(double temperature)
Input	double temperature
Output
Description	This will set the temperature of the AirHeater to the specified temperature.

SetIncubationChannelIsEnabled
Complete Command	ZenService.HardwareActions.SetIncubationChannelIsEnabled(int channel, bool isEnabled)
Input	integer channel, boolean isEnabled
Output	double intensity
Description	This will enable the specified channel.

SetIncubationChannelTemperature
Complete Command	ZenService.HardwareActions.SetIncubationChannelTemperature(int channel, double temperature)
Input	integer channel, double temperature
Output
Description	Sets the temperature of the selected channel to the specified value.

SetIncubationCO2Concentration
Complete Command	ZenService.HardwareActions.SetIncubationCO2Concentration(double concentration)
Input	double concentration
Output
Description	Sets the CO2 concentration to the specified value.

SetIncubationCO2IsEnabled
Complete Command	ZenService.HardwareActions.SetIncubationCO2IsEnabled(bool isEnabled)
Input	boolean isEnabled
Output
Description	Enables the CO2 incubation.

SetIncubationO2Concentration
Complete Command	ZenService.HardwareActions.SetIncubationO2Concentration(double concentration)
Input	double concentration
Output
Description	Sets the O2 concentration to the specified value.

SetIncubationO2IsEnabled
Complete Command	ZenService.HardwareActions.SetIncubationO2IsEnabled(bool isEnabled)
Input	boolean isEnabled
Output
Description	Enables the O2 incubation.

SetStagePosition
Complete Command	ZenService.HardwareActions.SetStagePosition(double positionXInMicrometer, double positionYInMicrometer)
Input	double positionXInMicrometer, positionYInMicrometer
Output
Description	Sets the stage XY position to the specified value.

SetStagePositionX
Complete Command	ZenService.HardwareActions.SetStagePosition(double positionXInMicrometer)
Input	double positionXInMicrometer
Output
Description	Sets the stage X position to the specified value.

SetStagePositionY
Complete Command	ZenService.HardwareActions.SetStagePosition(double positionYInMicrometer)
Input	double positionYInMicrometer
Output
Description	Sets the stage Y position to the specified value.

SetTriggerDigitalOut
Complete Command	ZenService.HardwareActions.SetTriggerDigitalOut(string port- Label, bool isSet)
Input	string portLabel, boolean isSet
Output
Description	Sets the selected TriggerDigitalOut port to the specified value.

SetTriggerDigitalOut7
Complete Command	ZenService.HardwareActions.SetTriggerDigitalOut7(bool isSet)
Input	boolean isSet
Output
Description	This will set TriggerDigitalOut7 port to the specified value.

SetTriggerDigitalOut8
Complete Command	ZenService.HardwareActions.SetTriggerDigitalOut8(bool isSet)
Input	boolean isSet
Output
Description	Sets the selected TriggerDigitalOut8 port to the specified value.

SetTriggerDigitalOutRLShutter
Complete Command	ZenService.HardwareActions.SetTriggerDigitalOutRLShutter(bool isSet)
Input	boolean isSet
Output
Description	Sets the TriggerDigitalOutRLShutter port to the specified value.

SetTriggerDigitalOutTLShutter
Complete Command	ZenService.HardwareActions.SetTriggerDigitalOutTLShutter8(bool isSet)
Input	boolean isSet
Output
Description	Sets the selected TriggerDigitalOutTKShutter port to the specified value.

Actions - Extra

AppendLogLineString (1)
Complete Command	ZenService.Xtra.System.AppendLogLineString(string logMessage)
Input	string logMessage
Output	string (contains the file path of the data log file)
Description	Creates a text file (ExperimentName_Log.txt) inside the folder save folder/temp and the file path to the log file is returned. Numbers have to be converted to strings in order two write them into the log file. Column separators have to be specified as strings as well.

AppendLogLineString (2)
Complete Command	ZenService.Xtra.System.AppendLogLineString(string logMessage, string logFileName)
Input	string logMessage, string logFileName
Output	string (contains the file path of the data log file)
Description	This is similar to the function AppendLogLineString (1) but allows to specify the file path where the text file will be saved.

ExecuteExternalProgram (1)
Complete Command	ZenService.Xtra.System.ExecuteExternalProgram(string exeFilePath)
Input	string exeFilePath
Output
Description	Starts an external application (.exe, .py, *.mp3, ...). It may be required to add the location of the application the environmental variables, usually PATH, in order for windows to find the application. It is also possible to use the absolute file path.

ExecuteExternalProgram (2)
Complete Command	ZenService.Xtra.System.ExecuteExternalProgram(string exeFilePath, string arguments)
Input	string exeFilePath, string arguments
Output
Description	This is similar to the function above but it allows to specify arguments which can be passed to the application. An example could look like this: ZenService.Xtra.ExecuteExternalProgram("fiji-win64.exe", "-macro Open_CZI_OME_complete.ijm Experiment-123.czi")

ExecuteExternalProgramBlocking (1)
Complete Command	ZenService.Xtra.System.ExecuteExternalProgram(string exeFilePath, string arguments, int timeoutInMs)
Input	string exeFilePath, string arguments, int timeoutInMs
Output	integer exitCode
Description	This advanced method will run an external program and blocks the subsequent script. When the Experiment Feedback runs in synchronous script execution it also blocks the experiment until the external application is closed. It requires a parameter called timeoutinMs, which specifies after which time period the script will continue independent from the external applications. As an output it returns a so-called ExitCode (integer), which is produced by the external application when exiting. This ExitCode has to be supported by the external application. Standard Windows programs (like Notepad, etc.) just return '0'. When using a special application or self-written applications it is possible to set a special own ExitCode.

ExecuteExternalProgramBlocking (2)
Complete Command	ZenService.Xtra.System.ExecuteExternalProgram(string exeFilePath, int timeoutInMs)
Input	string exeFilePath, int timeoutInMs
Output	integer exitCode
Description	This is the same method as above but with additional arguments for the external application. The timeout parameter is still required.

PlaySound (1)
Complete Command	ZenService.Xtra.System.PlaySound()
Input
Output
Description	This will play the system sound.

PlaySound (2)
Complete Command	ZenService.Xtra.System.PlaySound(string waveFilePath)
Input	string waveFilePath
Output
Description	Plays the specified wave sound file.

RunLoopScript
Complete Command	ZenService.Xtra.System.RunLoopScript()
Input
Output
Description	This command will trigger a run of the LoopScript. It is only meant to be used when running the Experiment Feedback script in synchronous script execution.

WriteDebugOutput
Complete Command	ZenService.Xtra.System.WriteDebugOutput(string message)
Input	string
Output
Description	Writes string messages in the Output for debugging.

Debugging Tab

Parameter		Description
General
-	Show Warning Popup	Allows to open warning popups.
-	Show Output Messages	Opens the output messages field. Here the messages defined below are displayed during script run for debugging purposes.
Output Messages
-	Show	Displays the corresponding message in white.
-	Highlight	Displays the corresponding messages with different colors.
User Defined Messages
-	Write to Output	Writes user defined messages (ZenService. Xtra.System. WriteDebugOutput (string message)).
Auto Messages
-	Observable Change	Writes a notification each time an observable changes.
-	Action Called	Writes a notification each time an action is called.
-	Action Executed	Writes a notification each time an action is executed.
-	Action Warning	Writes action warning messages.
-	Exception	Writes exception messages.
-	Script Run	Writes which part of the script (preloop, loop script, post loop script) is run.
Additional Information
-	Show Message Type	Allows to additionally display the message type.
-	Show Time Stamp	Allows to additionally display the time stamp for each message.
-	Follow Debug Message	Follows the output if activated.
Clear output		Clears the messages in the output field.

Carl-Zeiss-Strasse 22

73447 Oberkochen

Germany

Experiment Feedback

Key Features

Workflow Experiment Feedback

See also

Editing the Feedback Script

Experiment Feedback Tool

Script Editor for Experiment Feedback Dialog

See also

Input Windows

Commands Tab

Script Commands - Available Actions

Actions - Experiment

Actions - Hardware

Actions - Extra

Debugging Tab

ON THIS PAGE