# 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`. | ## 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"`. | ## 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. | ## 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`. | ## 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. | ## useq.HardwareAutofocus Bases: `Action` `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 \| 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. | ## 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. |