Axes¶

The following objects may be used to describe iteration over specific types of dimensions: the stage positions, channels, time plans, z plans, grids and well plates of an MDASequence. (Most of them may also be given as plain dicts, see Building Sequences.)

useq.Position ¶

Position = AbsolutePosition

Referenced by:

API Reference pymmcore-widgets pymmcore_widgets
- useq_widgets Re-exports
- PositionTable API
User Guide
- Widget Gallery Sequence editors
- useq-schema Building Sequences
  - A z-stack at three positions
  - Axes and plans

Returned by:

API Reference
- pymmcore-widgets pymmcore_widgets PositionTable API value
- useq-schema Sequence MDASequence stage_positions

Subclassed by:

API Reference useq-schema Axes WellPlatePlan

Used by:

API Reference pymmcore-widgets pymmcore_widgets PositionTable API setValue

useq.Channel ¶

Bases: FrozenModel

Define an acquisition channel.

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"`.
`exposure`	`float \| None`	Exposure time in milliseconds. Must be positive. If not provided, implies use current exposure time. By default, `None`.
`do_stack`	`bool`	If `True`, instructs engine to include this channel in any Z stacks being acquired. By default, `True`.
`z_offset`	`float`	Relative Z offset from current position, in microns. By default, `0`.
`acquire_every`	`int`	Acquire every Nth frame (if acquiring a time series). By default, `1`.
`camera`	`str \| None`	Name of the camera to use for this channel. If not provided, implies use current camera. By default, `None`.

Referenced by:

API Reference
- pymmcore-widgets pymmcore_widgets
  - useq_widgets Re-exports
  - ChannelTable API
- useq-schema useq v2 Re-exports
User Guide
- Widget Gallery Sequence editors
- useq-schema Building Sequences
  - Axes and plans
  - Skipping timepoints or z-stacks

Returned by:

API Reference
- pymmcore-widgets pymmcore_widgets ChannelTable API value
- useq-schema
  - useq v2 Classes MDASequence channels
  - Sequence MDASequence
    - channels
    - iter_axis

Subclassed by:

API Reference useq-schema useq v2 Classes ChannelsPlan

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets ChannelTable API setValue
- useq-schema useq v2 Classes
  - ChannelsPlan contribute_to_mda_event
  - MDASequence

Time plans¶

Ways to describe a temporal acquisition sequence.

useq.TIntervalDuration ¶

Bases: TimePlan

Define temporal sequence using interval and duration.

Attributes:

Name	Type	Description
`interval`	`timedelta`	Time between frames. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`duration`	`timedelta`	Total duration of sequence.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `True`.

Returned by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API value

Used by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API setValue

useq.TIntervalLoops ¶

Bases: TimePlan

Define temporal sequence using interval and number of loops.

Attributes:

Name	Type	Description
`interval`	`timedelta`	Time between frames. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`loops`	`int`	Number of frames.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `False`.

Returned by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API value

Used by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API setValue

useq.TDurationLoops ¶

Bases: TimePlan

Define temporal sequence using duration and number of loops.

Attributes:

Name	Type	Description
`duration`	`timedelta`	Total duration of sequence. Scalars are interpreted as seconds. Strings are parsed according to ISO 8601.
`loops`	`int`	Number of frames.
`prioritize_duration`	`bool`	If `True`, instructs engine to prioritize duration over number of frames in case of conflict. By default, `False`.

Used by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API setValue

useq.MultiPhaseTimePlan ¶

Bases: TimePlan

Time sequence composed of multiple phases.

Attributes:

Name	Type	Description
`phases`	`Sequence[TIntervalDuration \| TIntervalLoops \| TDurationLoops]`	Sequence of time plans.
`prioritize_duration`	`bool`

Returned by:

API Reference pymmcore-widgets pymmcore_widgets TimePlanWidget API value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets TimePlanWidget API setValue
- useq-schema useq Attributes AnyTimePlan

Z plans¶

Ways to describe a z-stack acquisition sequence.

useq.ZTopBottom ¶

Bases: ZPlan

Define Z using absolute top & bottom positions.

Note that bottom will always be visited, regardless of go_up, while top will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`top`	`float`	Top position in microns (inclusive).
`bottom`	`float`	Bottom position in microns (inclusive).
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

Returned by:

API Reference pymmcore-widgets pymmcore_widgets ZPlanWidget API value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets ZPlanWidget API setValue
- useq-schema useq Attributes AnyZPlan

useq.ZAboveBelow ¶

Bases: ZPlan

Define Z as asymmetric range above and below some reference position.

Note that below will always be visited, regardless of go_up, while above will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`above`	`float`	Range above reference position in microns (inclusive).
`below`	`float`	Range below reference position in microns (inclusive).
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

Returned by:

API Reference pymmcore-widgets pymmcore_widgets ZPlanWidget API value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets ZPlanWidget API setValue
- useq-schema useq Attributes AnyZPlan

useq.ZAbsolutePositions ¶

Bases: ZPlan

Define Z as a list of absolute positions.

Attributes:

Name	Type	Description
`absolute`	`list[float]`	List of absolute z positions.
`go_up`	`bool`	If `True` (the default), visits points in the order provided, otherwise in reverse.

Used by:

API Reference useq-schema useq Attributes AnyZPlan

useq.ZRangeAround ¶

Bases: ZPlan

Define Z as a symmetric range around some reference position.

Note that -range / 2 will always be visited, regardless of go_up, while +range / 2 will always be encompassed by the range, but may not be precisely visited if the step size does not divide evenly into the range.

Attributes:

Name	Type	Description
`range`	`float`	Range in microns (inclusive). For example, a range of 4 with a step size of 1 would visit [-2, -1, 0, 1, 2].
`step`	`float`	Step size in microns.
`go_up`	`bool`	If `True`, instructs engine to start at bottom and move towards top. By default, `True`.

Returned by:

API Reference pymmcore-widgets pymmcore_widgets ZPlanWidget API value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets ZPlanWidget API setValue
- useq-schema useq Attributes AnyZPlan

useq.ZRelativePositions ¶

Bases: ZPlan

Define Z as a list of positions relative to some reference.

Typically, the "reference" will be whatever the current Z position is at the start of the sequence.

Attributes:

Name	Type	Description
`relative`	`list[float]`	List of relative z positions.
`go_up`	`bool`	If `True` (the default), visits points in the order provided, otherwise in reverse.

Used by:

API Reference useq-schema useq Attributes AnyZPlan

Grid plans¶

Ways to describe a grid acquisition sequence.

useq.GridRowsColumns ¶

Grid plan based on number of rows and columns.

Attributes:

Name	Type	Description
`rows`	`int`	Number of rows.
`columns`	`int`	Number of columns.
`relative_to`	`RelativeTo`	Point in the grid to which the coordinates are relative. If "center", the grid is centered around the origin. If "top_left", the grid is positioned such that the top left corner is at the origin.
`overlap`	`tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`float \| None`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`float \| None`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

Referenced by:

API Reference pymmcore-widgets pymmcore_widgets
- useq_widgets Classes PointsPlanWidget
- GridPlanWidget API GridPlanWidget

Returned by:

API Reference pymmcore-widgets pymmcore_widgets
- useq_widgets points_plans Classes GridRowColumnWidget value
- GridPlanWidget API value

Used by:

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

useq.GridWidthHeight ¶

Grid plan based on total width and height.

Attributes:

Name	Type	Description
`width`	`float`	Minimum total width of the grid, in microns. (may be larger based on fov_width)
`height`	`float`	Minimum total height of the grid, in microns. (may be larger based on fov_height)
`relative_to`	`RelativeTo`	Point in the grid to which the coordinates are relative. If "center", the grid is centered around the origin. If "top_left", the grid is positioned such that the top left corner is at the origin.
`overlap`	`tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`float \| None`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`float \| None`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

Referenced by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API GridPlanWidget

Returned by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API value

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets GridPlanWidget API setValue
- useq-schema useq Attributes RelativeMultiPointPlan

useq.GridFromEdges ¶

Yield absolute stage positions to cover a bounded area.

The bounded area is defined by top, left, bottom and right edges in stage coordinates. The bounds define the outer edges of the images, including the field of view and overlap.

Attributes:

Name	Type	Description
`top`	`float`	Top stage position of the bounding area
`left`	`float`	Left stage position of the bounding area
`bottom`	`float`	Bottom stage position of the bounding area
`right`	`float`	Right stage position of the bounding area
`overlap`	`tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`float \| None`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`float \| None`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

Referenced by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API GridPlanWidget

Returned by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API value

Used by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API setValue

useq.RandomPoints ¶

Yield random points in a specified geometric shape.

Attributes:

Name	Type	Description
`num_points`	`int`	Number of points to generate.
`max_width`	`float`	Maximum width of the bounding box in microns.
`max_height`	`float`	Maximum height of the bounding box in microns.
`shape`	`Shape`	Shape of the bounding box. Current options are "ellipse" and "rectangle".
`random_seed`	`int \| None`	Random numpy seed that should be used to generate the points. If None, a random seed will be used.
`allow_overlap`	`bool`	By default, True. If False and `fov_width` and `fov_height` are specified, points will not overlap and will be at least `fov_width` and `fov_height` apart.
`order`	`TraversalOrder \| None`	Order in which the points will be visited. If None, order is simply the order in which the points are generated (random). Use 'nearest_neighbor' or 'two_opt' to order the points in a more structured way.
`start_at`	`RelativePosition \| int`	Position or index of the point to start at. This is only used if `order` is 'nearest_neighbor' or 'two_opt'. If a position is provided, it will always be included in the list of points. If an index is provided, it must be less than the number of points, and corresponds to the index of the (randomly generated) points; this likely only makes sense when `random_seed` is provided.
`fov_width`	`float \| None`
`fov_height`	`float \| None`

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 value

Used by:

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

useq.GridFromPolygon ¶

Grid plan based on a polygon boundary.

This grid plan generates absolute stage positions that cover a polygon region. Additionally the convex hull, and/or a buffered polygon can be created to generate tiles over a larger area surrounding the initial polygon.

Attributes:

Name	Type	Description
`vertices`	`list[tuple[float, float]]`	List of (x, y) points that define the polygon boundary. Must have at least 3 points.
`convex_hull`	`bool \| None`	If True, the convex hull of the polygon will be used.
`offset`	`float \| None`	Expand area bounded by vertices to include all points within a `offset` of the original boundary. A positive offset produces a dilation, a negative offset an erosion.
`overlap`	`tuple[float, float]`	Overlap between grid positions in percent. If a single value is provided, it is used for both x and y. If a tuple is provided, the first value is used for x and the second for y.
`mode`	`OrderMode`	Define the ways of ordering the grid positions. Options are row_wise, column_wise, row_wise_snake, column_wise_snake and spiral. By default, row_wise_snake.
`fov_width`	`float \| None`	Width of the field of view in microns. If not provided, acquisition engines should use current width of the FOV based on the current objective and camera. Engines MAY override this even if provided.
`fov_height`	`float \| None`	Height of the field of view in microns. If not provided, acquisition engines should use current height of the FOV based on the current objective and camera. Engines MAY override this even if provided.

Used by:

API Reference pymmcore-widgets pymmcore_widgets GridPlanWidget API setValue

Grid options¶

useq.OrderMode ¶

Bases: Enum

Order in which grid positions will be iterated.

Attributes:

Name	Type	Description
`row_wise`	`Literal['row_wise']`	Iterate row by row.
`column_wise`	`Literal['column_wise']`	Iterate column by column.
`row_wise_snake`	`Literal['row_wise_snake']`	Iterate row by row, but alternate the direction of the columns.
`column_wise_snake`	`Literal['column_wise_snake']`	Iterate column by column, but alternate the direction of the rows.
`spiral`	`Literal['spiral']`	Iterate in a spiral pattern, starting from the center.

Referenced by:

API Reference useq-schema useq v2 Re-exports

Used by:

API Reference useq-schema useq v2 Classes GridFromPolygon iter_grid_positions

row_wise ¶

row_wise = 'row_wise'

column_wise ¶

column_wise = 'column_wise'

row_wise_snake ¶

row_wise_snake = 'row_wise_snake'

column_wise_snake ¶

column_wise_snake = 'column_wise_snake'

spiral ¶

spiral = 'spiral'

generate_indices ¶

generate_indices(rows: int, columns: int) -> Iterator[tuple[int, int]]

Generate indices for the given grid size.

useq.Shape ¶

Bases: Enum

Shape of the bounding box for random points.

Attributes:

Name	Type	Description
`ELLIPSE`	`Literal['ellipse']`	The bounding box is an ellipse.
`RECTANGLE`	`Literal['rectangle']`	The bounding box is a rectangle.

Referenced by:

API Reference useq-schema useq v2 Re-exports

Returned by:

API Reference useq-schema useq v2 Classes RandomPoints shape

Used by:

API Reference
- pymmcore-widgets pymmcore_widgets useq_widgets Classes PointsPlanWidget setWellShape
- useq-schema useq v2 Classes RandomPoints shape

ELLIPSE ¶

ELLIPSE = 'ellipse'

Used by:

API Reference useq-schema useq v2 Classes RandomPoints shape

RECTANGLE ¶

RECTANGLE = 'rectangle'

useq.TraversalOrder ¶

Bases: Enum

Order in which random points are visited.

Referenced by:

API Reference useq-schema useq v2 Re-exports

Returned by:

API Reference useq-schema useq v2 Classes RandomPoints order

Used by:

API Reference useq-schema useq v2 Classes RandomPoints order

NEAREST_NEIGHBOR ¶

NEAREST_NEIGHBOR = 'nearest_neighbor'

TWO_OPT ¶

TWO_OPT = 'two_opt'

Used by:

API Reference useq-schema useq v2 Classes RandomPoints order

RANDOM ¶

RANDOM = 'random'

order_points ¶

order_points(points: ndarray, start_at: int = 0) -> ndarray

Return the order of points based on the traversal order.

Well plates¶

useq.WellPlatePlan ¶

Bases: UseqModel, Sequence[Position]

A plan for acquiring images from a multi-well plate.

Attributes:

Name	Type	Description
`plate`	`WellPlate`	The well-plate definition. Minimally including rows, columns, and well spacing. If expressed as a string, it is assumed to be a key in `useq.registered_well_plate_keys`.
`a1_center_xy`	`tuple[float, float]`	The stage coordinates in µm of the center of well A1 (top-left corner).
`rotation`	`float \| None`	The rotation angle in degrees (anti-clockwise) of the plate. If None, no rotation is applied. If expressed as a string, it is assumed to be an angle with units (e.g., "5°", "4 rad", "4.5deg"). If expressed as an arraylike, it is assumed to be a 2x2 rotation matrix `[[cos, -sin], [sin, cos]]`, or a 4-tuple `(cos, -sin, sin, cos)`.
`selected_wells`	`tuple[tuple[int, ...], tuple[int, ...]] \| None`	Any <=2-dimensional index expression for selecting wells. for example: - None -> No wells are selected. - slice(0) -> (also) select no wells. - slice(None) -> Selects all wells. - 0 -> Selects the first row. - [0, 1, 2] -> Selects the first three rows. - slice(1, 5) -> selects wells from row 1 to row 4. - (2, slice(1, 4)) -> select wells in the second row and only columns 1 to 3. - ([1, 2], [3, 4]) -> select wells in (row, column): (1, 3) and (2, 4)
`well_points_plan`	`GridRowsColumns \| GridWidthHeight \| RandomPoints \| RelativePosition`	A plan for acquiring images within each well. This can be a single position (for a single image per well), a GridRowsColumns (for a grid of images), or RandomPoints (for random points within each well).

Referenced by:

API Reference
- pymmcore-widgets pymmcore_widgets
  - useq_widgets Classes WellPlateWidget
  - HCSWizard API HCSWizard
- useq-schema useq v2 Re-exports

Returned by:

API Reference
- pymmcore-widgets pymmcore_widgets
  - useq_widgets Classes WellPlateWidget value
  - HCSWizard API value
- useq-schema Sequence MDASequence stage_positions

Used by:

API Reference pymmcore-widgets pymmcore_widgets
- useq_widgets Classes WellPlateWidget setValue
- HCSWizard API setValue

useq.WellPlate ¶

Bases: FrozenModel

A multi-well plate definition.

Attributes:

Name	Type	Description
`rows`	`int`	The number of rows in the plate. Must be > 0.
`columns`	`int`	The number of columns in the plate. Must be > 0.
`well_spacing`	`tuple[float, float]`	The center-to-center distance in mm (pitch) between wells in the x and y directions. If a single value is provided, it is used for both x and y.
`well_size`	`tuple[float, float]`	The size in mm of each well in the x and y directions. If the well is squared or rectangular, this is the width and height of the well. If the well is circular, this is the diameter. If a single value is provided, it is used for both x and y.
`circular_wells`	`bool`	Whether wells are circular (True) or squared/rectangular (False).
`name`	`str`	A name for the plate.

Referenced by:

API Reference
- pymmcore-widgets pymmcore_widgets useq_widgets Classes WellPlateWidget
- useq-schema useq v2 Re-exports

Used by:

API Reference pymmcore-widgets pymmcore_widgets useq_widgets Classes WellPlateWidget setValue

useq.register_well_plates ¶

register_well_plates(
    plates: Mapping[str, PlateOrKwargs], /, **kwargs: PlateOrKwargs
) -> None

register_well_plates(
    plates: Iterable[tuple[str, PlateOrKwargs]], /, **kwargs: PlateOrKwargs
) -> None

register_well_plates(**kwargs: PlateOrKwargs) -> None

register_well_plates(
    plates: Mapping[str, PlateOrKwargs]
    | Iterable[tuple[str, PlateOrKwargs]] = (),
    /,
    **kwargs: PlateOrKwargs,
) -> None

Register well-plate definitions to allow lookup by key.

Added keys will override existing keys if they already exist.

Values may either be WellPlate instances, or dictionaries with the following keys: - rows: Required[int] - columns: Required[int] - well_spacing: Required[tuple[float, float]] - well_size: tuple[float, float] | None - circular_wells: bool - name: str

Examples:

>>> import useq
>>> useq.register_well_plates(
...     {
...         "custom-square-plate": {
...             "rows": 8, "columns": 8, "well_spacing": 9.3, "well_size": 7.1
...         },
...         "silly-plate": {"rows": 1, "columns": 1, "well_spacing": 100}
...     }
... )

Referenced by:

API Reference useq-schema useq v2 Re-exports

useq.registered_well_plate_keys ¶

registered_well_plate_keys() -> set[str]

Return a set of all registered well-plate keys.

These keys may be used as an argument to WellPlatePlan.plate to select a plate definition.

Referenced by:

API Reference useq-schema useq v2 Re-exports