feat: add Position plate_row/plate_col and configurable name_pattern to grid plans

src/useq/_grid.py

@@ -61,10 +61,19 @@ class _GridPlan(_MultiPointPlan[PositionT]):
         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.
+    name_pattern : str
+        Format pattern for grid position names. Supported variables are
+        `{row}`, `{col}`, and `{idx}`. By default, `"{idx:04d}"`.
     """
 
     overlap: tuple[float, float] = Field(default=(0.0, 0.0), frozen=True)
     mode: OrderMode = Field(default=OrderMode.row_wise_snake, frozen=True)
+    name_pattern: str = Field(
+        default="{idx:04d}",
+        frozen=True,
+        description="Format pattern for grid position names. "
+        "Supported variables: {row}, {col}, {idx}.",
+    )
 
     @field_validator("overlap", mode="before")
     @classmethod
@@ -137,7 +146,7 @@ def iter_grid_positions(
                 y=y0 - r * dy,
                 grid_row=r,
                 grid_col=c,
-                name=f"{str(idx).zfill(4)}",
+                name=self.name_pattern.format(row=r, col=c, idx=idx),
             )
 
     def __iter__(self) -> Iterator[PositionT]:  # type: ignore [override]
@@ -518,7 +527,11 @@ def iter_grid_positions(
             pos = []
         for idx, (x, y, r, c) in enumerate(pos):
             yield AbsolutePosition(
-                x=x, y=y, grid_row=r, grid_col=c, name=f"{str(idx).zfill(4)}"
+                x=x,
+                y=y,
+                grid_row=r,
+                grid_col=c,
+                name=self.name_pattern.format(row=r, col=c, idx=idx),
             )
 
     def _cached_tiles(

src/useq/_iter_sequence.py

@@ -174,7 +174,10 @@ def _iter_sequence(
         # determine x, y, z positions
         event_kwargs.update(_xyzpos(position, channel, sequence.z_plan, grid, z_pos))
         if position and position.name:
-            event_kwargs["pos_name"] = position.name
+            pos_name = position.name
+            if grid and grid.name and getattr(position, "plate_row", None) is not None:
+                pos_name = f"{pos_name}_{grid.name}"
+            event_kwargs["pos_name"] = pos_name
         # include position properties only when p-index changes
         p_idx = index.get(Axis.POSITION, -1)
         if position and position.properties and p_idx != _last_p_idx:

src/useq/_plate.py

@@ -24,7 +24,7 @@
 from useq._enums import Shape
 from useq._grid import RandomPoints, RelativeMultiPointPlan
 from useq._plate_registry import _PLATE_REGISTRY
-from useq._position import Position, PositionBase, RelativePosition
+from useq._position import Position, PositionBase, RelativePosition, _index_to_row_name
 
 if TYPE_CHECKING:
     from pydantic_core import core_schema
@@ -418,15 +418,6 @@ def plot(self, show_axis: bool = True) -> None:
         plot_plate(self, show_axis=show_axis)
 
 
-def _index_to_row_name(index: int) -> str:
-    """Convert a zero-based column index to row name (A, B, ..., Z, AA, AB, ...)."""
-    name = ""
-    while index >= 0:
-        name = chr(index % 26 + 65) + name
-        index = index // 26 - 1
-    return name
-
-
 def _find_pattern(seq: Sequence[int]) -> tuple[list[int] | None, int | None]:
     n = len(seq)
 

src/useq/_position.py

@@ -16,6 +16,15 @@
     from useq import MDASequence
 
 
+def _index_to_row_name(index: int) -> str:
+    """Convert a zero-based row index to name (A, B, ..., Z, AA, AB, ...)."""
+    name = ""
+    while index >= 0:
+        name = chr(index % 26 + 65) + name
+        index = index // 26 - 1
+    return name
+
+
 class PositionBase(MutableModel):
     """Define a position in 3D space.
 
@@ -32,13 +41,23 @@ class PositionBase(MutableModel):
     z : float | None
         Z position in microns.
     name : str | None
-        Optional name for the position.
+        Optional name for the position. When `plate_row` and `plate_col` are
+        both int, the name is derived from them (e.g., "A1") and providing a
+        mismatched name raises ValueError. When either is a str (custom
+        naming), the name defaults to ``f"{plate_row}{plate_col}"`` but can
+        be freely overridden.
     sequence : MDASequence | None
         Optional MDASequence relative this position.
-    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.
+    plate_row : int | str | None
+        Row for well plate positions. Can be a 0-based index (e.g., 0 → "A",
+        1 → "B") or a string name (e.g., "A", "B") used as-is. In YAML,
+        unquoted letters are parsed as strings (``plate_row: A`` works).
+    plate_col : int | str | None
+        Column for well plate positions. Can be a 0-based index (e.g., 0 → "1",
+        1 → "2") or a string name (e.g., "1", "2") used as-is. In YAML,
+        unquoted numbers are parsed as int, so use quotes for string columns
+        (``plate_col: "1"`` for column name "1", vs ``plate_col: 1`` for
+        0-based index 1 → column name "2").
     grid_row : int | None
         Optional row index, when used in a grid.
     grid_col : int | None
@@ -51,8 +70,8 @@ class PositionBase(MutableModel):
     name: str | None = None
     sequence: Optional["MDASequence"] = None
     properties: list[PropertyTuple] | None = None
-    plate_row: int | None = None
-    plate_col: int | None = None
+    plate_row: int | str | None = None
+    plate_col: int | str | None = None
     grid_row: int | None = None
     grid_col: int | None = None
 
@@ -108,6 +127,34 @@ def __round__(self, ndigits: "SupportsIndex | None" = None) -> "Self":
         # not sure why these Self types are not working
         return type(self).model_construct(**kwargs)  # type: ignore [return-value]
 
+    @model_validator(mode="after")
+    def _name_from_plate(self) -> "Self":
+        """Set or validate name from plate_row/plate_col.
+
+        When both plate_row and plate_col are int (standard well-plate indices),
+        the name is derived as e.g. "A1" and an explicit mismatch raises
+        ValueError. When either is a str (custom naming), the name is only
+        auto-generated if not provided; explicit names are accepted as-is.
+        """
+        if self.plate_row is not None and self.plate_col is not None:
+            if isinstance(self.plate_row, int) and isinstance(self.plate_col, int):
+                well_name = f"{_index_to_row_name(self.plate_row)}{self.plate_col + 1}"
+                if self.name is not None and self.name != well_name:
+                    raise ValueError(
+                        f"Position name {self.name!r} does not match "
+                        f"plate_row={self.plate_row}, plate_col="
+                        f"{self.plate_col} (expected {well_name!r}). "
+                        f"Remove the name to auto-generate it from "
+                        f"plate coordinates."
+                    )
+                object.__setattr__(self, "name", well_name)
+            elif self.name is None:
+                # String plate coords: auto-generate only if no name provided
+                row_str = str(self.plate_row)
+                col_str = str(self.plate_col)
+                object.__setattr__(self, "name", f"{row_str}{col_str}")
+        return self
+
     @model_validator(mode="before")
     @classmethod
     def _cast(cls, value: Any) -> Any:

tests/fixtures/mda.json

@@ -47,6 +47,7 @@
     "fov_height": null,
     "fov_width": null,
     "mode": "row_wise_snake",
+    "name_pattern": "{idx:04d}",
     "overlap": [
       0.0,
       0.0
@@ -94,6 +95,7 @@
           "fov_height": null,
           "fov_width": null,
           "mode": "row_wise_snake",
+          "name_pattern": "{idx:04d}",
           "overlap": [
             0.0,
             0.0

tests/fixtures/mda.yaml

@@ -25,17 +25,11 @@ metadata:
 stage_positions:
 - x: 10.0
   y: 20.0
+  z: null
 - name: test_name
   sequence:
-    axis_order:
-    - t
-    - p
-    - g
-    - c
-    - z
     grid_plan:
       columns: 3
-      mode: row_wise_snake
       rows: 2
     z_plan:
       above: 10.0