Skip to content

Event#

MDAEvent #

Define a single event in a MDASequence.

Usually, this object will be generator by iterating over a MDASequence (see useq.MDASequence.iter_events).

Attributes:

Name Type Description
index dict[str, int]

Index of this event in the sequence. This is a mapping of axis name to index. For example: {'t': 4, 'c': 0, 'z': 5},
channel Channel | None

Channel to use for this event. If None, implies use current channel. By default, None. Channel is a simple pydantic object with two attributes: config and group. config is the name of the configuration to use for this channel, (e.g. "488nm", "DAPI", "FITC"). group is the name of the group to which this channel belongs. By default, "Channel".
exposure float | None

Exposure time in milliseconds. If not provided, implies use current exposure time. By default, None.
min_start_time float | None

Minimum start time of this event, in seconds. If provided, the engine will pause until this time has elapsed before starting this event. Times are relative to the start of the sequence, or the last event with reset_event_timer set to True.
pos_name str | None

The name assigned to the position. By default, None.
x_pos float | None

X position in microns. If not provided, implies use current position. By default, None.
y_pos float | None

Y position in microns. If not provided, implies use current position. By default, None.
z_pos float | None

Z position in microns. If not provided, implies use current position. By default, None.
slm_image SLMImage | None

Image data to display on an SLM device. SLMImage is a simple pydantic object with two attributes: data and device. data is the image data (anything that can be cast to a numpy array), device is the name of the SLM device to use. If not provided, the "default" SLM device should be used. By default, None.
sequence MDASequence | None

A reference to the useq.MDASequence this event belongs to. This is a read-only attribute. By default, None.
properties Sequence[PropertyTuple] | None

List of useq.PropertyTuple to set before starting this event. Where each item in the list is a 3-member named tuple of (device_name, property_name, property_value). This is inspired by micro-manager's Device Adapter API, but could be used to set arbitrary properties in any backend that supports the concept of devices that have properties with values. By default, None.
roi CameraROI | None

Camera region of interest. Accepts a CameraROI object or a bare tuple of (offset_x, offset_y, width, height) which will be automatically converted. By default, None.
metadata dict

Optional metadata to be associated with this event.
action Action

The action to perform for this event. By default, useq.AcquireImage. Example of another action is useq.HardwareAutofocus which could be used to perform a hardware autofocus. For backwards compatibility, an action of None implies AcquireImage. You may use CustomAction to indicate any custom action, with the data attribute containing any data required to perform the custom action.
keep_shutter_open bool

If True, the illumination shutter should be left open after the event has been executed, otherwise it should be closed. By default, False." This is useful when the sequence of events being executed use the same illumination scheme (such as a z-stack in a single channel), and closing and opening the shutter between events would be slow.
reset_event_timer bool

If True, the engine should reset the event timer to the time of this event, and future min_start_time values will be relative to this event. By default, False.

Channel #

Channel in a MDA event.

Attributes:

Name Type Description
config str

Name of the configuration to use for this channel, (e.g. "488nm", "DAPI", "FITC").
group str

Optional name of the group to which this channel belongs. By default, "Channel".

PropertyTuple #

Three-tuple capturing a device, property, and value.

Attributes:

Name Type Description
device_name str

Name of a device.
property_name str

Name of a property recognized by the device.
value Any

Value for the property.

Event Actions#

Action #

Base class for a useq.MDAEvent action.

An Action specifies what task should be performed during a useq.MDAEvent. An Action can be for example used to acquire an image (useq.AcquireImage) or to perform a hardware autofocus (useq.HardwareAutofocus). An action of None implies AcquireImage.

You may use CustomAction to indicate any custom action, with the data attribute containing any data required to perform the custom action.

Attributes:

Name Type Description
type str

Type of the action that should be performed at the useq.MDAEvent.

AcquireImage #

useq.Action to acquire an image.

Attributes:

Name Type Description
type Literal['acquire_image']

This action can be used to acquire an image.

HardwareAutofocus #

useq.Action to perform a hardware autofocus.

See also useq.AutoFocusPlan.

Attributes:

Name Type Description
type Literal['hardware_autofocus']

This action can be used to trigger hardware autofocus.
autofocus_device_name (str, optional)

The name of the autofocus offset motor device (if applicable). If None, acquisition engines may attempt to set the offset however they see fit (such as using a current or default autofocus device.)
autofocus_motor_offset (float, optional)

Before autofocus is performed, the autofocus motor should be moved to this offset, if applicable. (Not all autofocus devices have an offset motor.) If None, the autofocus motor should not be moved.
max_retries int

The number of retries if autofocus fails. By default, 3.

CustomAction #

useq.Action to perform a custom action.

This is a generic user action that can be used to represent anything that is not covered by the other action types, such as a microfluidic event, or a photostimulation, etc...

The data attribute is a dictionary that can contain any data that is needed to perform the custom action. It must be serializable to JSON by pydantic.

Attributes:

Name Type Description
type Literal['custom']

This action can be used to perform a custom action.
name (str, optional)

A name for the custom action (not to be confused with the type attribute, which must always be "custom").
data (dict, optional)

Custom data associated with the action.