Event¶

An MDAEvent describes one thing for the microscope to do (usually: acquire an image), and the hardware state to do it in. Fields that are left as None mean "use the current setting". Iterating over an MDASequence yields events, but you can also create them yourself.

useq.MDAEvent ¶

Bases: UseqModel

Define a single event in a MDASequence.

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

Attributes:

Name	Type	Description
`index`	`ReadOnlyDict`	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`	`list[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[str, Any]`	Optional metadata to be associated with this event. This is the place for any user-defined data (for example, parameters that a custom acquisition engine needs).
`action`	`HardwareAutofocus \| AcquireImage \| CustomAction`	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`.

Referenced by:

API Reference
- pymmcore-plus pymmcore_plus CMMCorePlus
  - Acquisition engine & events run_mda
  - Hardware sequencing canSequenceEvents
- useq-schema
Getting Started
- Which Package Do I Need? What each package does
- Your First Acquisition Describing the experiment
User Guide
- Advanced Topics Pycro-Manager-Style API
- Running Acquisitions
  - Custom Acquisition Engines
  - The Acquisition Engine
    - Running a very simple sequence
    - The MDAEvent object
- useq-schema
  - Building Sequences
  - Core schema
    - MDAEvent
    - MDASequence

Returned by:

API Reference
- pymmcore-plus pymmcore_plus
  - core
    - Classes SequencedEvent events
    - Functions iter_sequenced_events
  - mda
    - handlers Classes TensorStoreHandler frame_metadatas
    - Classes
      - MDAEngine event_iterator
      - PMDAEngine event_iterator
- useq-schema

Subclassed by:

API Reference
- pymmcore-plus pymmcore_plus core Classes SequencedEvent
- useq-schema useq v2 Classes

Used by:

API Reference

Yielded by:

API Reference useq-schema Sequence
- MDASequence iter_events
- How sequences are iterated iter_sequence

useq.EventChannel ¶

Bases: UseqModel

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"`.

Referenced by:

API Reference useq-schema useq v2 Re-exports
User Guide Running Acquisitions The Acquisition Engine The MDAEvent object

useq.PropertyTuple ¶

Bases: NamedTuple

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.
`property_value`	`Any`	Value for the property.

Referenced by:

API Reference useq-schema
- useq v2 Re-exports
- Event MDAEvent

Event Actions¶

useq.Action ¶

Bases: FrozenModel

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`.

Referenced by:

API Reference
- pymmcore-plus pymmcore_plus core Classes SequencedEvent
- useq-schema
  - useq v2 Re-exports
  - Event

Subclassed by:

API Reference useq-schema Event

useq.AcquireImage ¶

Bases: Action

useq.Action to acquire an image.

Attributes:

Name	Type	Description
`type`	`Literal['acquire_image']`	This action can be used to acquire an image.

Referenced by:

API Reference useq-schema
- useq v2 Re-exports
- Event
  - Action
  - MDAEvent

useq.HardwareAutofocus ¶

Bases: Action

useq.Action to perform a hardware autofocus.

useq.CustomAction ¶

Bases: Action

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`	A name for the custom action (not to be confused with the `type` attribute, which must always be `"custom"`).
`data`	`dict`	Custom data associated with the action.

Referenced by:

API Reference useq-schema useq v2 Re-exports

Name	Type	Description
`type`	`Literal['hardware_autofocus']`	This action can be used to trigger hardware autofocus.
`autofocus_device_name`	`str \| None`	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 \| None`	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.