useq ¶

Implementation agnostic schema for multi-dimensional microscopy experiments.

Submodules

Name	Description
`pycromanager`	Convert useq objects to the event dicts used by Pycro-Manager.
`v2`	New MDASequence API (preview).

Classes

Name	Description
`AbsolutePosition`	An absolute position in 3D space.
`AcquireImage`	`useq.Action` to acquire an image.
`Action`	Base class for a `useq.MDAEvent` action.
`AutoFocusPlan`	Base class for hardware autofocus plans.
`AxesBasedAF`	Autofocus plan that performs autofocus when any of the specified axes change.
`Axis`	Recognized useq-schema axis keys.
`CameraROI`	Camera region of interest.
`Channel`	Define an acquisition channel.
`CustomAction`	`useq.Action` to perform a custom action.
`EventChannel`	Channel in a MDA event.
`GridFromEdges`	Yield absolute stage positions to cover a bounded area.
`GridFromPolygon`	Grid plan based on a polygon boundary.
`GridRowsColumns`	Grid plan based on number of rows and columns.
`GridWidthHeight`	Grid plan based on total width and height.
`HardwareAutofocus`	`useq.Action` to perform a hardware autofocus.
`MDAEvent`	Define a single event in a `MDASequence`.
`MDASequence`	A sequence of MDA (Multi-Dimensional Acquisition) events.
`MultiPhaseTimePlan`	Time sequence composed of multiple phases.
`OrderMode`	Order in which grid positions will be iterated.
`PropertyTuple`	Three-tuple capturing a device, property, and value.
`RandomPoints`	Yield random points in a specified geometric shape.
`RelativePosition`	A relative position in 3D space.
`SLMImage`	SLM Image in a MDA event.
`Shape`	Shape of the bounding box for random points.
`TDurationLoops`	Define temporal sequence using duration and number of loops.
`TIntervalDuration`	Define temporal sequence using interval and duration.
`TIntervalLoops`	Define temporal sequence using interval and number of loops.
`TraversalOrder`	Order in which random points are visited.
`WellPlate`	A multi-well plate definition.
`WellPlatePlan`	A plan for acquiring images from a multi-well plate.
`ZAboveBelow`	Define Z as asymmetric range above and below some reference position.
`ZAbsolutePositions`	Define Z as a list of absolute positions.
`ZRangeAround`	Define Z as a symmetric range around some reference position.
`ZRelativePositions`	Define Z as a list of positions relative to some reference.
`ZTopBottom`	Define Z using absolute top & bottom positions.

Functions

Name	Description
`register_well_plates`	Register well-plate definitions to allow lookup by key.
`registered_well_plate_keys`	Return a set of all registered well-plate keys.

Attributes

Name	Description
`AnyAutofocusPlan`
`AnyTimePlan`
`AnyZPlan`
`GridRelative`
`MultiPointPlan`
`Position`
`RelativeMultiPointPlan`

Classes¶

Axis ¶

Bases: StrEnum

Recognized useq-schema axis keys.

Attributes:

Name	Type	Description
`TIME`	`Literal['t']`	Time axis.
`POSITION`	`Literal['p']`	XY Stage Position axis.
`GRID`	`Literal['g']`	Grid axis (usually an additional row/column iteration around a position).
`CHANNEL`	`Literal['c']`	Channel axis.
`Z`	`Literal['z']`	Z axis.

Referenced by:

API Reference useq-schema useq v2 Re-exports

Used by:

API Reference useq-schema useq v2 Classes

TIME ¶

TIME = 't'

Used by:

API Reference useq-schema useq v2 Classes TimePlan axis_key

POSITION ¶

POSITION = 'p'

Returned by:

API Reference useq-schema useq v2 Classes StagePositions axis_key

Used by:

API Reference useq-schema useq v2 Classes StagePositions axis_key

GRID ¶

GRID = 'g'

Returned by:

API Reference useq-schema useq v2 Classes RandomPoints axis_key

Used by:

API Reference useq-schema useq v2 Classes RandomPoints axis_key

CHANNEL ¶

CHANNEL = 'c'

Returned by:

API Reference useq-schema useq v2 Classes ChannelsPlan axis_key

Used by:

API Reference useq-schema useq v2 Classes ChannelsPlan axis_key

Z ¶

Z = 'z'

Returned by:

API Reference useq-schema useq v2 Classes ZPlan axis_key

Used by:

API Reference useq-schema useq v2 Classes ZPlan axis_key

CameraROI ¶

Bases: UseqModel

Camera region of interest.

May be initialized with a (offset_x, offset_y, width, height) tuple.

Attributes:

Name	Type	Description
`offset_x`	`int`	X offset of the ROI in pixels. Must be >= 0.
`offset_y`	`int`	Y offset of the ROI in pixels. Must be >= 0.
`width`	`int`	Width of the ROI in pixels. Must be >= 0.
`height`	`int`	Height of the ROI in pixels. Must be >= 0.

offset_x ¶

offset_x: NonNegativeInt

offset_y ¶

offset_y: NonNegativeInt

width ¶

width: NonNegativeInt

height ¶

height: NonNegativeInt

SLMImage ¶

Bases: UseqModel

SLM Image in a MDA event.

This object can be cast to a numpy.array using np.asarray or np.array.

Attributes:

Name	Type	Description
`data`	`Any`	Image data. Anything that can be cast to a numpy array. For pydantic simplicity, we mark this as Any, but in practice it should be numpy.typing.ArrayLike (which is anything that can be cast to a numpy array using `np.asarray`).
`device`	`str \| None`	Optional name of the SLM device to use. If not provided, the "default" SLM device should be used. (It is left to the backend to determine what device that is). By default, `None`.
`exposure`	`float \| None`	Exposure time for the SLM specifically (if different from the detector), in milliseconds. If not provided, the exposure on the owning MDAEvent should be used. By default, `None`.

Referenced by:

API Reference useq-schema useq v2 Re-exports

data ¶

data: Any = Field(..., repr=False)

device ¶

device: str | None = None

exposure ¶

exposure: float | None = Field(default=None, gt=0.0)

AbsolutePosition ¶

Bases: PositionBase, FrozenModel

An absolute position in 3D space.

Attributes:

Name	Type	Description
`x`	`float \| None`	X position in microns.
`y`	`float \| None`	Y position in microns.
`z`	`float \| None`	Z position in microns.
`name`	`str \| None`	Optional name for the position.
`sequence`	`MDASequence \| None`	Optional MDASequence relative this position.
`properties`	`list[PropertyTuple] \| None`
`plate_row`	`int \| None`	Optional 0-based row index for well plate positions.
`plate_col`	`int \| None`	Optional 0-based column index for well plate positions.
`grid_row`	`int \| None`	Optional row index, when used in a grid.
`grid_col`	`int \| None`	Optional column index, when used in a grid.

Used by:

API Reference useq-schema Axes Position

is_relative `property` ¶

is_relative: bool

RelativePosition ¶

Bases: PositionBase

A relative position in 3D space.

Relative positions also support fov_width and fov_height attributes, and can be used to define a single field of view for a "multi-point" plan.

Attributes:

Name	Type	Description
`fov_width`	`float \| None`
`fov_height`	`float \| None`
`x`	`float`	X position in microns.
`y`	`float`	Y position in microns.
`z`	`float`	Z position in microns.
`name`	`str \| None`	Optional name for the position.
`sequence`	`MDASequence \| None`	Optional MDASequence relative this position.
`properties`	`list[PropertyTuple] \| None`
`plate_row`	`int \| None`	Optional 0-based row index for well plate positions.
`plate_col`	`int \| None`	Optional 0-based column index for well plate positions.
`grid_row`	`int \| None`	Optional row index, when used in a grid.
`grid_col`	`int \| None`	Optional column index, when used in a grid.

Referenced by:

API Reference pymmcore-widgets pymmcore_widgets useq_widgets Classes PointsPlanWidget

Returned by:

API Reference pymmcore-widgets pymmcore_widgets useq_widgets points_plans Classes RandomPointWidget start_at

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets useq_widgets points_plans Classes RelativePointPlanSelector setValue
- useq-schema useq Attributes RelativeMultiPointPlan

x ¶

x: float = 0

y ¶

y: float = 0

z ¶

z: float = 0

num_positions ¶

num_positions() -> int

Attributes¶

MultiPointPlan ¶

MultiPointPlan = AbsoluteMultiPointPlan | RelativeMultiPointPlan

Returned by:

API Reference useq-schema Sequence MDASequence grid_plan

RelativeMultiPointPlan ¶

RelativeMultiPointPlan = (
    GridRowsColumns | GridWidthHeight | RandomPoints | RelativePosition
)

Returned by:

API Reference pymmcore-widgets pymmcore_widgets useq_widgets
- points_plans Classes RelativePointPlanSelector value
- Classes PointsPlanWidget value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets useq_widgets
  - points_plans Classes RelativePointPlanSelector setValue
  - Classes PointsPlanWidget setValue
- useq-schema useq Attributes MultiPointPlan

AnyAutofocusPlan ¶

AnyAutofocusPlan = AxesBasedAF

Referenced by:

API Reference useq-schema useq v2 Re-exports

Returned by:

API Reference useq-schema
- useq v2 Classes MDASequence autofocus_plan
- Sequence MDASequence autofocus_plan

Used by:

API Reference useq-schema useq v2 Classes MDASequence

AnyTimePlan ¶

AnyTimePlan = MultiPhaseTimePlan | SinglePhaseTimePlan

Referenced by:

Returned by:

API Reference useq-schema Sequence MDASequence time_plan

AnyZPlan ¶

AnyZPlan = (
    ZTopBottom
    | ZAboveBelow
    | ZRangeAround
    | ZAbsolutePositions
    | ZRelativePositions
)

Referenced by:

Returned by:

API Reference useq-schema Sequence MDASequence z_plan

GridRelative ¶

GridRelative = GridRowsColumns

useq ¶

Classes¶

Axis ¶

TIME ¶

POSITION ¶

GRID ¶

CHANNEL ¶

Z ¶

CameraROI ¶

offset_x ¶

offset_y ¶

width ¶

height ¶

SLMImage ¶

data ¶

device ¶

exposure ¶

AbsolutePosition ¶

is_relative property ¶

RelativePosition ¶

x ¶

y ¶

z ¶

num_positions ¶

Attributes¶

MultiPointPlan ¶

RelativeMultiPointPlan ¶

AnyAutofocusPlan ¶

AnyTimePlan ¶

AnyZPlan ¶

GridRelative ¶

is_relative `property` ¶