arcadia-microscopy-tools 0.2.2__tar.gz → 0.2.3__tar.gz

{arcadia_microscopy_tools-0.2.2 → arcadia_microscopy_tools-0.2.3}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.3] - 2026-01-22
+
+### Added
+- New `microplate.py` module for managing multiwell plate layouts:
+  - `Well` class: Represents individual wells with ID normalization (e.g., "a1" → "A01"), sample tracking, and custom properties
+  - `MicroplateLayout` class: Manages complete plate layouts with features:
+    - Load layouts from CSV files with `from_csv()`
+    - Display plate layouts as formatted grid tables with `display()`
+
+### Changed
+- Refactored `masks.py` architecture for improved performance and maintainability:
+  - Refactored `MaskProcessor` class into standalone `_process_mask()` function
+  - Updated `DEFAULT_CELL_PROPERTY_NAMES` to include circularity and volume by default
+- Made cellpose and modal optional dependencies to reduce installation size:
+  - Install with `uv pip install arcadia-microscopy-tools[segmentation]` for cellpose support
+  - Install with `uv pip install arcadia-microscopy-tools[all]` for all optional dependencies
+- Moved pytest from main dependencies to dev group
+- Consolidated all dev tools into single `dev` dependency group
+
+### Fixed
+- Coordinate format inconsistency in outline extractors: both cellpose and skimage now return outlines in (y, x) format
+- `isinstance` check in `SegmentationMask` now accepts `Mapping` type instead of just `dict` to match type annotation
+- Empty outline arrays now properly shaped as (0, 2) for consistency
+
 ## [0.2.2] - 2026-01-08
 
 ### Added

{arcadia_microscopy_tools-0.2.2 → arcadia_microscopy_tools-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcadia-microscopy-tools
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python package for processing large-scale microscopy datasets generated by Arcadia's imaging suite
 License: MIT License
         
@@ -29,10 +29,9 @@ Requires-Dist: arcadia-pycolor>=0.6.5
 Requires-Dist: colour-science>=0.4.7
 Requires-Dist: liffile>=2025.12.12
 Requires-Dist: nd2>=0.10.3
-Requires-Dist: numpy>=2.4
+Requires-Dist: numpy>=2.4.1
+Requires-Dist: pandas>=2.3.3
 Requires-Dist: scikit-image>=0.25.2
-Requires-Dist: scikit-learn>=1.7.1
-Requires-Dist: torch>=2.7.1
 Provides-Extra: all
 Requires-Dist: cellpose>=4.0.6; extra == 'all'
 Requires-Dist: modal; extra == 'all'
@@ -40,6 +39,7 @@ Provides-Extra: compute
 Requires-Dist: modal; extra == 'compute'
 Provides-Extra: segmentation
 Requires-Dist: cellpose>=4.0.6; extra == 'segmentation'
+Requires-Dist: torch>=2.7.1; extra == 'segmentation'
 Description-Content-Type: text/markdown
 
 # arcadia-microscopy-tools

{arcadia_microscopy_tools-0.2.2 → arcadia_microscopy_tools-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arcadia-microscopy-tools"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python package for processing large-scale microscopy datasets generated by Arcadia's imaging suite"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -14,15 +14,15 @@ dependencies = [
     "colour-science>=0.4.7",
     "liffile>=2025.12.12",
     "nd2>=0.10.3",
-    "numpy>=2.4",
+    "numpy>=2.4.1",
+    "pandas>=2.3.3",
     "scikit-image>=0.25.2",
-    "scikit-learn>=1.7.1",
-    "torch>=2.7.1",
 ]
 
 [project.optional-dependencies]
 segmentation = [
     "cellpose>=4.0.6",
+    "torch>=2.7.1",
 ]
 compute = [
     "modal",

{arcadia_microscopy_tools-0.2.2 → arcadia_microscopy_tools-0.2.3}/src/arcadia_microscopy_tools/masks.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 import warnings
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from functools import cached_property
 from typing import Literal
@@ -9,24 +10,21 @@ import skimage as ski
 from cellpose.utils import outlines_list
 
 from .channels import Channel
-from .typing import BoolArray, Int64Array, ScalarArray
-
-OutlineExtractorMethod = Literal["cellpose", "skimage"]
+from .typing import BoolArray, FloatArray, Int64Array, ScalarArray, UInt16Array
 
 DEFAULT_CELL_PROPERTY_NAMES = [
     "label",
     "centroid",
+    "volume",
     "area",
     "area_convex",
     "perimeter",
     "eccentricity",
+    "circularity",
     "solidity",
     "axis_major_length",
     "axis_minor_length",
     "orientation",
-    "moments_hu",
-    "inertia_tensor",
-    "inertia_tensor_eigvals",
 ]
 
 DEFAULT_INTENSITY_PROPERTY_NAMES = [
@@ -36,62 +34,70 @@ DEFAULT_INTENSITY_PROPERTY_NAMES = [
     "intensity_std",
 ]
 
+OutlineExtractorMethod = Literal["cellpose", "skimage"]
 
-class CellposeOutlineExtractor:
-    """Extract cell outlines using Cellpose's outlines_list function."""
-
-    def extract_outlines(self, label_image: Int64Array) -> list[ScalarArray]:
-        """Extract outlines from label image."""
-        return outlines_list(label_image, multiprocessing=False)
 
+def _process_mask(
+    mask_image: BoolArray | Int64Array,
+    remove_edge_cells: bool,
+) -> Int64Array:
+    """Process a mask image by optionally removing edge cells and ensuring consecutive labels.
 
-class SkimageOutlineExtractor:
-    """Extract cell outlines using scikit-image's find_contours."""
+    Args:
+        mask_image: Input mask array where each cell has a unique label.
+        remove_edge_cells: Whether to remove cells touching image borders.
 
-    def extract_outlines(self, label_image: Int64Array) -> list[ScalarArray]:
-        """Extract outlines from label image."""
-        # Get unique cell IDs (excluding background)
-        unique_labels = np.unique(label_image)
-        unique_labels = unique_labels[unique_labels > 0]
+    Returns:
+        Processed label image with consecutive labels starting from 1.
+    """
+    label_image = mask_image
+    if remove_edge_cells:
+        label_image = ski.segmentation.clear_border(label_image)
 
-        outlines = []
-        for cell_id in unique_labels:
-            cell_mask = (label_image == cell_id).astype(np.uint8)
-            contours = ski.measure.find_contours(cell_mask, level=0.5)
-            if contours:
-                main_contour = max(contours, key=len)
-                outlines.append(main_contour)
-            else:
-                outlines.append(np.array([]))
-        return outlines
+    # Ensure consecutive labels
+    label_image = ski.measure.label(label_image).astype(np.int64)  # type: ignore
+    return label_image
 
 
-@dataclass
-class MaskProcessor:
-    """Process segmentation masks by removing edge cells and ensuring consecutive labels.
+def _extract_outlines_cellpose(label_image: Int64Array) -> list[FloatArray]:
+    """Extract cell outlines using Cellpose's outlines_list function.
 
     Args:
-        remove_edge_cells: Whether to remove cells touching image borders.
-    """
+        label_image: 2D integer array where each cell has a unique label.
 
-    remove_edge_cells: bool = True
+    Returns:
+        List of arrays, one per cell, containing outline coordinates in (y, x) format.
+    """
+    return outlines_list(label_image, multiprocessing=False)
 
-    def process_mask(self, mask_image: ScalarArray) -> Int64Array:
-        """Process a mask image by optionally removing edge cells and ensuring consecutive labels.
 
-        Args:
-            mask_image: Input mask array where each cell has a unique label.
+def _extract_outlines_skimage(label_image: Int64Array) -> list[FloatArray]:
+    """Extract cell outlines using scikit-image's find_contours.
 
-        Returns:
-            Processed label image with consecutive labels starting from 1.
-        """
-        _label_image = mask_image.copy()
-        if self.remove_edge_cells:
-            _label_image = ski.segmentation.clear_border(_label_image)
+    Args:
+        label_image: 2D integer array where each cell has a unique label.
 
-        # Ensure consecutive labels
-        _label_image = ski.measure.label(_label_image).astype(np.int64)  # type: ignore
-        return _label_image
+    Returns:
+        List of arrays, one per cell, containing outline coordinates in (y, x) format.
+        Empty arrays are included for cells where no contours are found.
+    """
+    # Get unique cell IDs (excluding background)
+    unique_labels = np.unique(label_image)
+    unique_labels = unique_labels[unique_labels > 0]
+
+    outlines = []
+    for cell_id in unique_labels:
+        cell_mask = (label_image == cell_id).astype(np.uint8)
+        contours = ski.measure.find_contours(cell_mask, level=0.5)
+        if contours:
+            main_contour = max(contours, key=len)
+            # Flip from (x, y) to (y, x) to match cellpose format
+            main_contour = main_contour[:, [1, 0]]
+            outlines.append(main_contour)
+        else:
+            # Include empty array to maintain alignment with cell labels
+            outlines.append(np.array([]).reshape(0, 2))
+    return outlines
 
 
 @dataclass
@@ -99,27 +105,29 @@ class SegmentationMask:
     """Container for segmentation mask data and feature extraction.
 
     Args:
-        mask_image: 2D integer array where each cell has a unique label (background=0).
-        intensity_image_dict: Optional dict mapping Channel enums to 2D intensity arrays.
-            Each intensity array must have the same shape as mask_image.
-            Channel names will be used as suffixes for intensity properties.
-            Example: {Channel.DAPI: [M x N], Channel.FITC: [M x N]}
-        remove_edge_cells: Whether to remove cells touching image borders.
+        mask_image: 2D integer or boolean array where each cell has a unique label (background=0).
+        intensity_image_dict: Optional dict mapping Channel instances to 2D intensity arrays.
+            Each intensity array must have the same shape as mask_image. Channel names will be used
+            as suffixes for intensity properties. Example:
+                {DAPI: array, FITC: array}
+        remove_edge_cells: Whether to remove cells touching image borders. Defaults to True.
         outline_extractor: Outline extraction method ("cellpose" or "skimage").
-        property_names: List of property names to compute. If None, uses default property names.
+            Defaults to "cellpose".
+        property_names: List of property names to compute. If None, uses
+            DEFAULT_CELL_PROPERTY_NAMES.
         intensity_property_names: List of intensity property names to compute.
-            If None, uses default intensity properties when intensity_image_dict is provided.
+            If None, uses DEFAULT_INTENSITY_PROPERTY_NAMES when intensity_image_dict is provided.
     """
 
-    mask_image: ScalarArray
-    intensity_image_dict: dict[Channel, ScalarArray] | None = None
+    mask_image: BoolArray | Int64Array
+    intensity_image_dict: Mapping[Channel, UInt16Array] | None = None
     remove_edge_cells: bool = True
     outline_extractor: OutlineExtractorMethod = "cellpose"
     property_names: list[str] | None = field(default=None)
     intensity_property_names: list[str] | None = field(default=None)
 
     def __post_init__(self):
-        """Validate inputs and create processors."""
+        """Validate inputs and set defaults."""
         # Validate mask_image
         if not isinstance(self.mask_image, np.ndarray):
             raise TypeError("mask_image must be a numpy array")
@@ -130,10 +138,8 @@ class SegmentationMask:
 
         # Validate intensity_image dict if provided
         if self.intensity_image_dict is not None:
-            if not isinstance(self.intensity_image_dict, dict):
-                raise TypeError(
-                    "intensity_image_dict must be a dict mapping Channel enums to 2D arrays"
-                )
+            if not isinstance(self.intensity_image_dict, Mapping):
+                raise TypeError("intensity_image_dict must be a Mapping of channels to 2D arrays")
             for channel, intensities in self.intensity_image_dict.items():
                 if not isinstance(intensities, np.ndarray):
                     raise TypeError(f"Intensity image for '{channel.name}' must be a numpy array")
@@ -155,32 +161,40 @@ class SegmentationMask:
             else:
                 self.intensity_property_names = []
 
-        # Create mask processor
-        self._mask_processor = MaskProcessor(remove_edge_cells=self.remove_edge_cells)
-
-        # Create outline extractor
-        if self.outline_extractor == "cellpose":
-            self._outline_extractor = CellposeOutlineExtractor()
-        else:  # Must be "skimage" due to Literal type
-            self._outline_extractor = SkimageOutlineExtractor()
-
     @cached_property
     def label_image(self) -> Int64Array:
-        """Get processed label image with consecutive labels."""
-        return self._mask_processor.process_mask(self.mask_image)
+        """Get processed label image with consecutive labels.
+
+        Returns:
+            2D integer array with consecutive cell labels starting from 1 (background=0).
+            Edge cells removed if remove_edge_cells=True.
+        """
+        return _process_mask(self.mask_image, self.remove_edge_cells)
 
     @cached_property
     def num_cells(self) -> int:
-        """Get the number of cells in the mask."""
+        """Get the number of cells in the mask.
+
+        Returns:
+            Integer count of cells (maximum label value in label_image).
+        """
         return int(self.label_image.max())
 
     @cached_property
-    def cell_outlines(self) -> list[ScalarArray]:
-        """Extract cell outlines using the configured outline extractor."""
+    def cell_outlines(self) -> list[FloatArray]:
+        """Extract cell outlines using the configured outline extractor.
+
+        Returns:
+            List of arrays, one per cell, containing outline coordinates in (y, x) format.
+            Returns empty list if no cells found.
+        """
         if self.num_cells == 0:
             return []
 
-        return self._outline_extractor.extract_outlines(self.label_image)
+        if self.outline_extractor == "cellpose":
+            return _extract_outlines_cellpose(self.label_image)
+        else:  # Must be "skimage" due to Literal type
+            return _extract_outlines_skimage(self.label_image)
 
     @cached_property
     def cell_properties(self) -> dict[str, ScalarArray]:
@@ -190,11 +204,12 @@ class SegmentationMask:
         properties (mean, max, min intensity) for each channel if intensity images are provided.
 
         For multichannel intensity images, property names are suffixed with the channel name:
-        - Channel.DAPI: "intensity_mean_DAPI"
-        - Channel.FITC: "intensity_mean_FITC"
+        - DAPI: "intensity_mean_DAPI"
+        - FITC: "intensity_mean_FITC"
 
         Returns:
             Dictionary mapping property names to arrays of values (one per cell).
+            Returns empty dict if no cells found.
         """
         if self.num_cells == 0:
             empty_props = (
@@ -210,10 +225,17 @@ class SegmentationMask:
             return empty_props
 
         # Extract morphological properties (no intensity image needed)
+        # Only compute extra properties if explicitly requested
+        extra_props = []
+        if self.property_names and "circularity" in self.property_names:
+            extra_props.append(circularity)
+        if self.property_names and "volume" in self.property_names:
+            extra_props.append(volume)
+
         properties = ski.measure.regionprops_table(
             self.label_image,
             properties=self.property_names,
-            extra_properties=[circularity, volume],
+            extra_properties=extra_props,
         )
 
         # Extract intensity properties for each channel
@@ -231,19 +253,13 @@ class SegmentationMask:
         return properties
 
     @cached_property
-    def centroids_yx(self) -> ScalarArray:
+    def centroids_yx(self) -> FloatArray:
         """Get cell centroids as (y, x) coordinates.
 
-        Extracts centroid coordinates from cell properties and returns them as a 2D array
-        where each row represents one cell's centroid in (y, x) format.
-
         Returns:
             Array of shape (num_cells, 2) with centroid coordinates.
             Each row is [y_coordinate, x_coordinate] for one cell.
-            Returns empty array if "centroid" is not included in property_names.
-
-        Note:
-            If "centroid" is not in property_names, issues a warning and returns an empty array.
+            Returns empty (0, 2) array with warning if "centroid" not in property_names.
         """
         if self.property_names and "centroid" not in self.property_names:
             warnings.warn(
@@ -328,7 +344,7 @@ def circularity(region_mask: BoolArray) -> float:
         Circularity value between 0 and 1. Returns 0 if perimeter is zero.
     """
     # regionprops expects a labeled image, so convert the mask (0/1)
-    labeled_mask = region_mask.astype(np.int64, copy=False)
+    labeled_mask = region_mask.astype(np.int64)
 
     # Compute standard region properties on this mask
     props = ski.measure.regionprops(labeled_mask)[0]
@@ -356,7 +372,7 @@ def volume(region_mask: BoolArray) -> float:
         Estimated volume in cubic pixels. Returns 0 if axis lengths cannot be computed.
     """
     # regionprops expects a labeled image, so convert the mask (0/1)
-    labeled_mask = region_mask.astype(np.int64, copy=False)
+    labeled_mask = region_mask.astype(np.int64)
 
     # Compute standard region properties on this mask
     props = ski.measure.regionprops(labeled_mask)[0]

arcadia_microscopy_tools-0.2.3/src/arcadia_microscopy_tools/microplate.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class Well:
+    """Represents a single well in a microplate.
+
+    Attributes:
+        id: Well identifier (e.g., "A01", "B12").
+        sample: Sample identifier or name in this well.
+        properties: Additional metadata or properties for this well.
+    """
+
+    id: str
+    sample: str = ""
+    properties: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate and normalize the well ID."""
+        if not self.id or len(self.id) < 2:
+            raise ValueError("Well ID must be at least 2 characters (e.g., 'A1' or 'A01')")
+
+        row = self.id[0].upper()
+        if not "A" <= row <= "Z":
+            raise ValueError(f"Row must be A-Z, got '{row}'")
+
+        try:
+            column = int(self.id[1:])
+        except ValueError as e:
+            raise ValueError(f"Could not parse column number from '{self.id}'") from e
+
+        # Support up to 48 columns
+        if not 1 <= column <= 48:
+            raise ValueError(f"Column must be 1-48, got {column}")
+
+        # Normalize to capital letter, zero-padded format (a1 -> A01)
+        normalized = f"{row}{column:02d}"
+        if normalized != self.id:
+            object.__setattr__(self, "id", normalized)
+
+    @property
+    def row(self) -> str:
+        """Extract row letter from well ID."""
+        return self.id[0]
+
+    @property
+    def column(self) -> int:
+        """Extract column number from well ID."""
+        return int(self.id[1:])
+
+    def __str__(self) -> str:
+        """Return well ID string."""
+        return self.id
+
+    def __repr__(self) -> str:
+        """Return a string that could be used to recreate this object."""
+        props = f", properties={self.properties!r}" if self.properties else ""
+        return f"Well(id='{self.id}', sample='{self.sample}'{props})"
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Well:
+        """Create a Well from a dictionary (e.g., from CSV row).
+
+        Args:
+            data: Dictionary containing 'well_id' key and optional 'sample' and property keys.
+                CSV files should have a 'well_id' column.
+
+        Returns:
+            Well instance created from the dictionary.
+
+        Raises:
+            ValueError: If 'well_id' key is missing from the dictionary or is not a string.
+        """
+        if "well_id" not in data:
+            raise ValueError("Dictionary must contain 'well_id' key")
+
+        well_id = data["well_id"]
+        if not isinstance(well_id, str):
+            raise ValueError(f"well_id must be a string, got {type(well_id).__name__}")
+
+        sample = data.get("sample", "")
+        properties = {k: v for k, v in data.items() if k not in ("well_id", "sample")}
+
+        return cls(well_id, sample, properties)
+
+
+@dataclass(frozen=True)
+class MicroplateLayout:
+    """Representation of a microwell plate layout.
+
+    Args:
+        wells: Sequence of Well objects (converted to dict internally for efficient lookup).
+    """
+
+    wells: Sequence[Well]
+    _layout: dict[str, Well] = field(init=False, repr=False)
+
+    def __post_init__(self):
+        """Build internal dict from wells and validate for duplicates."""
+        well_dict = {}
+        for well in self.wells:
+            if well.id in well_dict:
+                raise ValueError(f"Duplicate well ID: '{well.id}'")
+            well_dict[well.id] = well
+
+        # Store as dict internally for efficient lookup
+        object.__setattr__(self, "_layout", well_dict)
+
+    @property
+    def layout(self) -> dict[str, Well]:
+        """Return the mapping of well IDs to Well objects."""
+        return self._layout
+
+    @property
+    def rows(self) -> list[str]:
+        """Unique rows in the plate layout."""
+        return sorted({well.row for well in self.layout.values()})
+
+    @property
+    def columns(self) -> list[int]:
+        """Unique columns in the plate layout."""
+        return sorted({well.column for well in self.layout.values()})
+
+    @property
+    def well_ids(self) -> list[str]:
+        """Return a list of all well IDs in the layout."""
+        return sorted(self.layout.keys())
+
+    def __getitem__(self, well_id: str) -> Well:
+        """Get a well by its ID.
+
+        Args:
+            well_id: The well ID to retrieve (e.g., "A01", "A1", "H12")
+                Non-normalized IDs (e.g., "A1") are automatically normalized.
+
+        Returns:
+            The Well object corresponding to the given ID
+
+        Raises:
+            KeyError: If the well ID doesn't exist in the layout
+        """
+        # Normalize the well_id before lookup to support both "A1" and "A01" formats
+        try:
+            normalized = Well(well_id).id
+        except ValueError as e:
+            raise KeyError(f"Invalid well ID '{well_id}': {e}") from None
+
+        try:
+            return self.layout[normalized]
+        except KeyError:
+            raise KeyError(f"Well ID '{well_id}' not found in plate layout.") from None
+
+    def __len__(self) -> int:
+        """Return the number of wells in the layout."""
+        return len(self.layout)
+
+    def __contains__(self, well_id: str) -> bool:
+        """Check if a well ID exists in the layout.
+
+        Args:
+            well_id: The well ID to check (e.g., "A01", "A1", "H12")
+                Non-normalized IDs (e.g., "A1") are automatically normalized.
+
+        Returns:
+            True if the well exists, False otherwise
+        """
+        # Normalize the well_id before checking to support both "A1" and "A01" formats
+        try:
+            normalized = Well(well_id).id
+            return normalized in self.layout
+        except ValueError:
+            # Invalid well ID format
+            return False
+
+    def __iter__(self) -> Iterator[Well]:
+        """Iterate over wells in the layout."""
+        return iter(self.layout.values())
+
+    @classmethod
+    def from_csv(cls, csv_path: Path, **kwargs) -> MicroplateLayout:
+        """Load a microplate layout from a CSV file using pandas.
+
+        Args:
+            csv_path: Path to CSV file containing well_id, sample, and optional property columns.
+            **kwargs: Additional arguments passed to pd.read_csv (e.g., encoding, dtype).
+
+        Returns:
+            MicroplateLayout instance with wells parsed from the CSV.
+
+        Raises:
+            ValueError: If CSV is empty or missing required 'well_id' column.
+        """
+        df = pd.read_csv(csv_path, **kwargs)
+
+        if df.empty:
+            raise ValueError(f"CSV file '{csv_path}' is empty")
+
+        if "well_id" not in df.columns:
+            raise ValueError(
+                f"CSV file '{csv_path}' missing required 'well_id' column. "
+                f"Found columns: {list(df.columns)}"
+            )
+
+        wells = [Well.from_dict(row) for row in df.to_dict("records")]
+
+        return cls(wells)
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Convert plate layout to a pandas DataFrame with all well data.
+
+        Returns:
+            DataFrame with columns: well_id, row, column, sample, and any additional properties.
+            One row per well in the layout.
+        """
+        if not self.layout:
+            return pd.DataFrame()
+
+        data = []
+        for well in self.layout.values():
+            row_data = {
+                "well_id": well.id,
+                "row": well.row,
+                "column": well.column,
+                "sample": well.sample,
+            }
+            # Add any additional properties
+            row_data.update(well.properties)
+            data.append(row_data)
+
+        return pd.DataFrame(data)
+
+    def display(self) -> str:
+        """Display the plate layout as a formatted grid table.
+
+        Returns:
+            String representation of the plate as a pivot table with rows and columns.
+        """
+        df = self.to_dataframe()
+        if df.empty:
+            return "Empty plate layout"
+
+        # Create pivot table: rows as index, columns as columns, sample as values
+        pivot = df.pivot(index="row", columns="column", values="sample")
+        pivot = pivot.fillna("-")
+        return pivot.to_string()