Sequence#

`MDASequence` #

A sequence of MDA (Multi-Dimensional Acquisition) events.

This is the core object in the useq library, and is used define a sequence of events to be run on a microscope. It object may be constructed manually, or from file (e.g. json or yaml).

The object itself acts as an iterator for useq.MDAEvent objects:

Attributes:

Name	Type	Description
`metadata`	`dict`	A dictionary of user metadata to be stored with the sequence.
`axis_order`	`str`	The order of the axes in the sequence. Must be a permutation of `"tpgcz"`. The default is `"tpgcz"`.
`stage_positions`	`tuple[Position, ...]`	The stage positions to visit. (each with `x`, `y`, `z`, `name`, and `sequence`, all of which are optional).
`grid_plan`	`GridFromEdges \| GridRelative \| None`	The grid plan to follow. One of `GridFromEdges`, `GridRelative` or `None`.
`channels`	`tuple[Channel, ...]`	The channels to acquire. see `Channel`.
`time_plan`	`MultiPhaseTimePlan \| TIntervalDuration \| TIntervalLoops \| TDurationLoops \| None`	The time plan to follow. One of `TIntervalDuration`, `TIntervalLoops`, `TDurationLoops`, `MultiPhaseTimePlan`, or `None`
`z_plan`	`ZTopBottom \| ZRangeAround \| ZAboveBelow \| ZRelativePositions \| ZAbsolutePositions \| None`	The z plan to follow. One of `ZTopBottom`, `ZRangeAround`, `ZAboveBelow`, `ZRelativePositions`, `ZAbsolutePositions`, or `None`.
`uid`	`UUID`	A read-only unique identifier (uuid version 4) for the sequence. This will be generated, do not set.
`autofocus_plan`	`AxesBasedAF \| None`	The hardware autofocus plan to follow. One of `AxesBasedAF` or `None`.
`keep_shutter_open_across`	`tuple[str, ...]`	A tuple of axes `str` across which the illumination shutter should be kept open. Resulting events will have `keep_shutter_open` set to `True` if and only if ALL axes whose indices are changing are in this tuple. For example, if `keep_shutter_open_across=('z',)`, then the shutter would be kept open between events axes {'t': 0, 'z: 0} and {'t': 0, 'z': 1}, but not between {'t': 0, 'z': 0} and {'t': 1, 'z': 0}.

Examples:

Create a MDASequence

>>> from useq import MDASequence, Position, Channel, TIntervalDuration
>>> seq = MDASequence(
...     axis_order="tpgcz",
...     time_plan={"interval": 0.1, "loops": 2},
...     stage_positions=[(1, 1, 1)],
...     grid_plan={"rows": 2, "columns": 2},
...     z_plan={"range": 3, "step": 1},
...     channels=[{"config": "DAPI", "exposure": 1}]
... )

Print the sequence to visualize its structure

>>> print(seq)
... MDASequence(
...     stage_positions=(Position(x=1.0, y=1.0, z=1.0, name=None),),
...     grid_plan=GridRowsColumns(
...         fov_width=None,
...         fov_height=None,
...         overlap=(0.0, 0.0),
...         mode=<OrderMode.row_wise_snake: 'row_wise_snake'>,
...         rows=2,
...         columns=2,
...         relative_to=<RelativeTo.center: 'center'>
...     ),
...     channels=(
...         Channel(
...             config='DAPI',
...             group='Channel',
...             exposure=1.0,
...             do_stack=True,
...             z_offset=0.0,
...             acquire_every=1,
...             camera=None
...         ),
...     ),
...     time_plan=TIntervalLoops(
...         prioritize_duration=False,
...         interval=datetime.timedelta(microseconds=100000),
...         loops=2
...     ),
...     z_plan=ZRangeAround(go_up=True, range=3.0, step=1.0)
... )

Iterate over the events in the sequence

>>> print(list(seq))
... [
...     MDAEvent(
...         index=mappingproxy({'t': 0, 'p': 0, 'g': 0, 'c': 0, 'z': 0}),
...         channel=Channel(config='DAPI'),
...         exposure=1.0,
...         min_start_time=0.0,
...         x_pos=0.5,
...         y_pos=1.5,
...         z_pos=-0.5
...     ),
...     MDAEvent(
...         index=mappingproxy({'t': 0, 'p': 0, 'g': 0, 'c': 0, 'z': 1}),
...         channel=Channel(config='DAPI'),
...         exposure=1.0,
...         min_start_time=0.0,
...         x_pos=0.5,
...         y_pos=1.5,
...         z_pos=0.5
...     ),
...     ...
... ]

Print the sequence as yaml

>>> print(seq.yaml())

axis_order:
   - t
   - p
   - g
   - c
   - z
channels:
   - config: DAPI
     exposure: 1.0
grid_plan:
   columns: 2
   rows: 2
stage_positions:
   - x: 1.0
     y: 1.0
     z: 1.0
time_plan:
   interval: '0:00:00.100000'
   loops: 2
z_plan:
   range: 3.0
   step: 1.0

Sequence#

MDASequence #

`MDASequence` #