feat: add well-plate model

.pre-commit-config.yaml

@@ -26,3 +26,4 @@ repos:
         additional_dependencies:
           - types-PyYAML
           - pydantic >=2
+          - numpy >=2

src/useq/__init__.py

@@ -14,6 +14,12 @@
 from useq._hardware_autofocus import AnyAutofocusPlan, AutoFocusPlan, AxesBasedAF
 from useq._mda_event import MDAEvent, PropertyTuple
 from useq._mda_sequence import MDASequence
+from useq._plate import (
+    WellPlate,
+    WellPlatePlan,
+    known_well_plate_keys,
+    register_well_plates,
+)
 from useq._position import Position
 from useq._time import (
     AnyTimePlan,
@@ -34,6 +40,7 @@
 __all__ = [
     "AcquireImage",
     "Action",
+    "register_well_plates",
     "AnyAutofocusPlan",
     "AnyGridPlan",
     "AnyTimePlan",
@@ -46,6 +53,7 @@
     "GridRowsColumns",
     "GridWidthHeight",
     "HardwareAutofocus",
+    "known_well_plate_keys",
     "MDAEvent",
     "MDASequence",
     "MultiPhaseTimePlan",
@@ -55,6 +63,8 @@
     "TDurationLoops",
     "TIntervalDuration",
     "TIntervalLoops",
+    "WellPlatePlan",
+    "WellPlate",
     "ZAboveBelow",
     "ZAbsolutePositions",
     "ZRangeAround",

src/useq/_base_model.py

@@ -49,8 +49,6 @@ def replace(self: _T, **kwargs: Any) -> _T:
         state = self.model_dump(exclude={"uid"})
         return type(self)(**{**state, **kwargs})
 
-
-class UseqModel(FrozenModel):
     def __repr_args__(self) -> "ReprArgs":
         """Only show fields that are not None or equal to their default value."""
         return [
@@ -65,6 +63,8 @@ def __repr_args__(self) -> "ReprArgs":
             )
         ]
 
+
+class UseqModel(FrozenModel):
     @classmethod
     def from_file(cls: Type[_Y], path: Union[str, Path]) -> _Y:
         """Return an instance of this class from a file.  Supports JSON and YAML."""

src/useq/_grid.py

@@ -477,9 +477,9 @@ class RandomPoints(_PointsPlan):
     """
 
     num_points: int
-    max_width: float
-    max_height: float
-    shape: Shape
+    max_width: float = np.inf
+    max_height: float = np.inf
+    shape: Shape = Shape.ELLIPSE
     random_seed: Optional[int] = None
     allow_overlap: bool = True
 

src/useq/_mda_sequence.py

@@ -10,6 +10,7 @@
     Optional,
     Sequence,
     Tuple,
+    Union,
 )
 from uuid import UUID, uuid4
 from warnings import warn
@@ -22,6 +23,7 @@
 from useq._grid import AnyGridPlan, GridPosition  # noqa: TCH001
 from useq._hardware_autofocus import AnyAutofocusPlan, AxesBasedAF
 from useq._iter_sequence import iter_sequence
+from useq._plate import WellPlatePlan  # noqa: TCH001
 from useq._position import Position
 from useq._time import AnyTimePlan  # noqa: TCH001
 from useq._utils import AXES, Axis, TimeEstimate, estimate_sequence_duration
@@ -179,7 +181,9 @@ class MDASequence(UseqModel):
 
     metadata: Dict[str, Any] = Field(default_factory=dict)
     axis_order: Tuple[str, ...] = AXES
-    stage_positions: Tuple[Position, ...] = Field(default_factory=tuple)
+    stage_positions: Union[WellPlatePlan, Tuple[Position, ...]] = Field(
+        default_factory=tuple
+    )
     grid_plan: Optional[AnyGridPlan] = None
     channels: Tuple[Channel, ...] = Field(default_factory=tuple)
     time_plan: Optional[AnyTimePlan] = None