arcadia-microscopy-tools 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

arcadia_microscopy_tools/__init__.py

@@ -3,7 +3,7 @@ from arcadia_microscopy_tools.channels import Channel
 from arcadia_microscopy_tools.microscopy import MicroscopyImage
 from arcadia_microscopy_tools.pipeline import ImageOperation, Pipeline, PipelineParallelized
 
-__version__ = "0.2.2"
+__version__ = "0.2.5"
 
 __all__ = [
     "Channel",

arcadia_microscopy_tools/blending.py

@@ -7,7 +7,7 @@ from matplotlib.colors import LinearSegmentedColormap, Normalize
 from skimage.color import gray2rgb
 
 from .channels import Channel
-from .typing import FloatArray
+from .typing import Float64Array
 
 
 @dataclass
@@ -23,7 +23,7 @@ class Layer:
     """
 
     channel: Channel
-    intensities: FloatArray
+    intensities: Float64Array
     opacity: float = 1.0
     transparent: bool = True
 
@@ -34,11 +34,11 @@ class Layer:
 
 
 def overlay_channels(
-    background: FloatArray,
-    channel_intensities: dict[Channel, FloatArray],
+    background: Float64Array,
+    channel_intensities: dict[Channel, Float64Array],
     opacity: float = 1.0,
     transparent: bool = True,
-) -> FloatArray:
+) -> Float64Array:
     """Create a fluorescence overlay.
 
     All channels are blended with the same opacity and transparency settings.
@@ -73,9 +73,9 @@ def overlay_channels(
 
 
 def create_sequential_overlay(
-    background: FloatArray,
+    background: Float64Array,
     layers: list[Layer],
-) -> FloatArray:
+) -> Float64Array:
     """Create an overlay by sequentially blending multiple channels onto a background.
 
     Args:
@@ -109,10 +109,10 @@ def create_sequential_overlay(
 
 
 def alpha_blend(
-    background: FloatArray,
-    foreground: FloatArray,
-    alpha: FloatArray,
-) -> FloatArray:
+    background: Float64Array,
+    foreground: Float64Array,
+    alpha: Float64Array,
+) -> Float64Array:
     """Alpha blend foreground onto background.
 
     Args:
@@ -127,9 +127,9 @@ def alpha_blend(
 
 
 def colorize(
-    intensities: FloatArray,
+    intensities: Float64Array,
     colormap: LinearSegmentedColormap,
-) -> FloatArray:
+) -> Float64Array:
     """Apply a colormap to a 2D intensity array.
 
     Args:

arcadia_microscopy_tools/masks.py

@@ -10,7 +10,7 @@ import skimage as ski
 from cellpose.utils import outlines_list
 
 from .channels import Channel
-from .typing import BoolArray, FloatArray, Int64Array, ScalarArray, UInt16Array
+from .typing import BoolArray, Float64Array, Int64Array, ScalarArray, UInt16Array
 
 DEFAULT_CELL_PROPERTY_NAMES = [
     "label",
@@ -34,8 +34,6 @@ DEFAULT_INTENSITY_PROPERTY_NAMES = [
     "intensity_std",
 ]
 
-OutlineExtractorMethod = Literal["cellpose", "skimage"]
-
 
 def _process_mask(
     mask_image: BoolArray | Int64Array,
@@ -59,7 +57,7 @@ def _process_mask(
     return label_image
 
 
-def _extract_outlines_cellpose(label_image: Int64Array) -> list[FloatArray]:
+def _extract_outlines_cellpose(label_image: Int64Array) -> list[Float64Array]:
     """Extract cell outlines using Cellpose's outlines_list function.
 
     Args:
@@ -68,10 +66,12 @@ def _extract_outlines_cellpose(label_image: Int64Array) -> list[FloatArray]:
     Returns:
         List of arrays, one per cell, containing outline coordinates in (y, x) format.
     """
-    return outlines_list(label_image, multiprocessing=False)
+    outlines = outlines_list(label_image, multiprocessing=False)
+    # Cellpose returns (x, y) coordinates, flip to (y, x) to match standard (row, col) format
+    return [outline[:, [1, 0]] if len(outline) > 0 else outline for outline in outlines]
 
 
-def _extract_outlines_skimage(label_image: Int64Array) -> list[FloatArray]:
+def _extract_outlines_skimage(label_image: Int64Array) -> list[Float64Array]:
     """Extract cell outlines using scikit-image's find_contours.
 
     Args:
@@ -91,8 +91,6 @@ def _extract_outlines_skimage(label_image: Int64Array) -> list[FloatArray]:
         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
@@ -112,7 +110,8 @@ class SegmentationMask:
                 {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").
-            Defaults to "cellpose".
+            Defaults to "cellpose". In practice, cellpose is ~2x faster but skimage handles
+            vertically oriented cell outlines better.
         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.
@@ -122,7 +121,7 @@ class SegmentationMask:
     mask_image: BoolArray | Int64Array
     intensity_image_dict: Mapping[Channel, UInt16Array] | None = None
     remove_edge_cells: bool = True
-    outline_extractor: OutlineExtractorMethod = "cellpose"
+    outline_extractor: Literal["cellpose", "skimage"] = "cellpose"
     property_names: list[str] | None = field(default=None)
     intensity_property_names: list[str] | None = field(default=None)
 
@@ -133,8 +132,10 @@ class SegmentationMask:
             raise TypeError("mask_image must be a numpy array")
         if self.mask_image.ndim != 2:
             raise ValueError("mask_image must be a 2D array")
-        if self.mask_image.min() < 0:
+        if np.any(self.mask_image < 0):
             raise ValueError("mask_image must have non-negative values")
+        if self.mask_image.max() == 0:
+            raise ValueError("mask_image contains no cells (all values are 0)")
 
         # Validate intensity_image dict if provided
         if self.intensity_image_dict is not None:
@@ -181,19 +182,25 @@ class SegmentationMask:
         return int(self.label_image.max())
 
     @cached_property
-    def cell_outlines(self) -> list[FloatArray]:
+    def cell_outlines(self) -> list[Float64Array]:
         """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.
+
+        Raises:
+            ValueError: If no cells are found in the mask.
+
+        Note:
+            The cellpose method is ~2x faster in general but skimage handles
+            vertically oriented cells/outlines better.
         """
         if self.num_cells == 0:
-            return []
+            raise ValueError("No cells found in mask. Cannot extract cell outlines.")
 
         if self.outline_extractor == "cellpose":
             return _extract_outlines_cellpose(self.label_image)
-        else:  # Must be "skimage" due to Literal type
+        else:  # must be "skimage" due to Literal type
             return _extract_outlines_skimage(self.label_image)
 
     @cached_property
@@ -205,24 +212,16 @@ class SegmentationMask:
 
         For multichannel intensity images, property names are suffixed with the channel name:
         - DAPI: "intensity_mean_DAPI"
-        - FITC: "intensity_mean_FITC"
+        - FITC: "intensity_max_FITC"
 
         Returns:
             Dictionary mapping property names to arrays of values (one per cell).
-            Returns empty dict if no cells found.
+
+        Raises:
+            ValueError: If no cells are found in the mask.
         """
         if self.num_cells == 0:
-            empty_props = (
-                {property_name: np.array([]) for property_name in self.property_names}
-                if self.property_names
-                else {}
-            )
-            # Add empty intensity properties if requested
-            if self.intensity_image_dict and self.intensity_property_names:
-                for channel in self.intensity_image_dict:
-                    for prop_name in self.intensity_property_names:
-                        empty_props[f"{prop_name}_{channel.name}"] = np.array([])
-            return empty_props
+            raise ValueError("No cells found in mask. Cannot extract cell properties.")
 
         # Extract morphological properties (no intensity image needed)
         # Only compute extra properties if explicitly requested
@@ -232,12 +231,18 @@ class SegmentationMask:
         if self.property_names and "volume" in self.property_names:
             extra_props.append(volume)
 
+        # Compute cell properties
         properties = ski.measure.regionprops_table(
             self.label_image,
             properties=self.property_names,
             extra_properties=extra_props,
         )
 
+        if "centroid-0" in properties:
+            properties["centroid_y"] = properties.pop("centroid-0")
+        if "centroid-1" in properties:
+            properties["centroid_x"] = properties.pop("centroid-1")
+
         # Extract intensity properties for each channel
         if self.intensity_image_dict and self.intensity_property_names:
             for channel, intensities in self.intensity_image_dict.items():
@@ -248,18 +253,21 @@ class SegmentationMask:
                 )
                 # Add channel suffix to property names
                 for prop_name, prop_values in channel_props.items():
-                    properties[f"{prop_name}_{channel.name}"] = prop_values
+                    properties[f"{prop_name}_{channel.name.lower()}"] = prop_values
 
         return properties
 
     @cached_property
-    def centroids_yx(self) -> FloatArray:
+    def centroids_yx(self) -> Float64Array:
         """Get cell centroids as (y, x) coordinates.
 
         Returns:
             Array of shape (num_cells, 2) with centroid coordinates.
             Each row is [y_coordinate, x_coordinate] for one cell.
             Returns empty (0, 2) array with warning if "centroid" not in property_names.
+
+        Raises:
+            ValueError: If no cells are found in the mask.
         """
         if self.property_names and "centroid" not in self.property_names:
             warnings.warn(
@@ -270,8 +278,8 @@ class SegmentationMask:
             )
             return np.array([]).reshape(0, 2)
 
-        yc = self.cell_properties["centroid-0"]
-        xc = self.cell_properties["centroid-1"]
+        yc = self.cell_properties["centroid_y"]
+        xc = self.cell_properties["centroid_x"]
         return np.array([yc, xc], dtype=float).T
 
     def convert_properties_to_microns(
@@ -281,34 +289,28 @@ class SegmentationMask:
         """Convert cell properties from pixels to microns.
 
         Applies appropriate scaling factors based on the dimensionality of each property:
-            - Linear measurements (1D): multiplied by pixel_size_um
-            - Area measurements (2D): multiplied by pixel_size_um²
-            - Volume measurements (3D): multiplied by pixel_size_um³
-            - Dimensionless properties: unchanged
+            - Linear measurements (1D): multiplied by pixel_size_um, keys suffixed with "_um"
+            - Area measurements (2D): multiplied by pixel_size_um², keys suffixed with "_um2"
+            - Volume measurements (3D): multiplied by pixel_size_um³, keys suffixed with "_um3"
+            - Dimensionless properties: unchanged, keys unchanged
 
         Args:
             pixel_size_um: Pixel size in microns.
 
         Returns:
-            Dictionary with the same keys as cell_properties but with values
+            Dictionary with keys renamed to include units and values
             converted to micron units where applicable.
 
         Note:
-            Properties like 'label', 'circularity', 'eccentricity', 'solidity',
-            and 'orientation' are dimensionless and remain unchanged.
-            Intensity properties (intensity_mean, intensity_max, etc.) are also
-            dimensionless and remain unchanged.
-            Tensor properties (inertia_tensor, inertia_tensor_eigvals) are scaled
-            as 2D quantities (pixel_size_um²).
+            Properties like 'label', 'circularity', 'eccentricity', 'solidity', and 'orientation'
+            are dimensionless and remain unchanged. Intensity properties (intensity_mean,
+            intensity_max, etc.) are also dimensionless and remain unchanged. Centroid coordinates
+            (centroid_y, centroid_x) remain in pixel coordinates as they represent image positions.
+            Tensor properties (inertia_tensor, inertia_tensor_eigvals) are scaled as 2D quantities
+            (pixel_size_um²) and suffixed with "_um2".
         """
         # Define which properties need which scaling
-        linear_properties = {
-            "perimeter",
-            "axis_major_length",
-            "axis_minor_length",
-            "centroid-0",
-            "centroid-1",
-        }
+        linear_properties = {"perimeter", "axis_major_length", "axis_minor_length"}
         area_properties = {"area", "area_convex"}
         volume_properties = {"volume"}
         tensor_properties = {"inertia_tensor", "inertia_tensor_eigvals"}
@@ -316,13 +318,13 @@ class SegmentationMask:
         converted = {}
         for prop_name, prop_values in self.cell_properties.items():
             if prop_name in linear_properties:
-                converted[prop_name] = prop_values * pixel_size_um
+                converted[f"{prop_name}_um"] = prop_values * pixel_size_um
             elif prop_name in area_properties:
-                converted[prop_name] = prop_values * (pixel_size_um**2)
+                converted[f"{prop_name}_um2"] = prop_values * (pixel_size_um**2)
             elif prop_name in volume_properties:
-                converted[prop_name] = prop_values * (pixel_size_um**3)
+                converted[f"{prop_name}_um3"] = prop_values * (pixel_size_um**3)
             elif prop_name in tensor_properties:
-                converted[prop_name] = prop_values * (pixel_size_um**2)
+                converted[f"{prop_name}_um2"] = prop_values * (pixel_size_um**2)
             else:
                 # Intensity-related, dimensionless, or label - no conversion
                 converted[prop_name] = prop_values

arcadia_microscopy_tools/metadata_structures.py

@@ -5,7 +5,7 @@ from enum import Flag, auto
 from typing import TYPE_CHECKING
 
 from .channels import Channel
-from .typing import FloatArray
+from .typing import Float64Array
 
 if TYPE_CHECKING:
     from dataclasses import Field
@@ -86,8 +86,8 @@ class AcquisitionSettings(DimensionValidatorMixin):
     exposure_time_ms: float
     zoom: float | None = None
     binning: str | None = None
-    frame_intervals_ms: FloatArray | None = dimension_field(DimensionFlags.TIMELAPSE)
-    wavelengths_nm: FloatArray | None = dimension_field(DimensionFlags.SPECTRAL)
+    frame_intervals_ms: Float64Array | None = dimension_field(DimensionFlags.TIMELAPSE)
+    wavelengths_nm: Float64Array | None = dimension_field(DimensionFlags.SPECTRAL)
 
 
 @dataclass

arcadia_microscopy_tools/model.py

@@ -7,7 +7,7 @@ import numpy as np
 import torch
 from cellpose.models import CellposeModel
 
-from .typing import FloatArray, Int64Array
+from .typing import Float64Array, Int64Array
 
 logger = logging.getLogger(__name__)
 
@@ -167,7 +167,7 @@ class SegmentationModel:
 
     def segment(
         self,
-        intensities: FloatArray,
+        intensities: Float64Array,
         cell_diameter_px: float | None = None,
         flow_threshold: float | None = None,
         cellprob_threshold: float | None = None,
@@ -213,7 +213,7 @@ class SegmentationModel:
 
     def batch_segment(
         self,
-        intensities_batch: Sequence[FloatArray],
+        intensities_batch: Sequence[Float64Array],
         cell_diameter_px: float | None = None,
         flow_threshold: float | None = None,
         cellprob_threshold: float | None = None,

arcadia_microscopy_tools/nikon.py

@@ -16,7 +16,7 @@ from .metadata_structures import (
     PhysicalDimensions,
 )
 from .microscopy import ImageMetadata
-from .typing import FloatArray
+from .typing import Float64Array
 
 
 def create_image_metadata_from_nd2(
@@ -247,7 +247,7 @@ class _NikonMetadataParser:
                     return time_s * 1000  # Convert to ms for AcquisitionSettings
         return None
 
-    def _parse_frame_intervals(self) -> FloatArray | None:
+    def _parse_frame_intervals(self) -> Float64Array | None:
         """Parse frame intervals from events metadata."""
         if self._nd2f.events():
             acquisition_start_times_s = [event["Time [s]"] for event in self._nd2f.events()]

arcadia_microscopy_tools/operations.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
+from typing import Literal
 
 import numpy as np
 import skimage as ski
 
-from .typing import FloatArray, ScalarArray
+from .typing import BoolArray, Float64Array, ScalarArray
 
 
 def rescale_by_percentile(
@@ -18,11 +19,9 @@ def rescale_by_percentile(
 
     Args:
         intensities: Input image array.
-        percentile_range:
-            Tuple of (min, max) percentiles to use for intensity scaling.
+        percentile_range: Tuple of (min, max) percentiles to use for intensity scaling.
             Default is (0, 100) which uses the full intensity range.
-        out_range:
-            Tuple of (min, max) values for the output intensity range.
+        out_range: Tuple of (min, max) values for the output intensity range.
             Default is (0, 1) for float normalization.
 
     Returns:
@@ -60,7 +59,7 @@ def subtract_background_dog(
     low_sigma: float = 0.6,
     high_sigma: float = 16.0,
     percentile: float = 0,
-) -> FloatArray:
+) -> Float64Array:
     """Subtract background from image using difference of Gaussians and percentile thresholding.
 
     Applies difference of Gaussians filter to enhance features and then estimates and subtracts
@@ -68,18 +67,15 @@ def subtract_background_dog(
 
     Args:
         intensities: Input image array.
-        low_sigma:
-            Standard deviation for the smaller Gaussian kernel. Controls fine detail enhancement.
-            Default is 0.6.
-        high_sigma:
-            Standard deviation for the larger Gaussian kernel. Controls background estimation
-            extent. Default is 16.
-        percentile:
-            Percentile of filtered image to use as background level (0-100).
+        low_sigma: Standard deviation for the smaller Gaussian kernel.
+            Controls fine detail enhancement. Default is 0.6.
+        high_sigma: Standard deviation for the larger Gaussian kernel.
+        Controls background estimation extent. Default is 16.
+        percentile: Percentile of filtered image to use as background level (0-100).
             Default is 0 (minimum value).
 
     Returns:
-        FloatArray: Background-subtracted image with negative values clipped to zero.
+        Float64Array: Background-subtracted image with negative values clipped to zero.
 
     Notes:
         - For best results, low_sigma should be smaller than the smallest feature of interest,
@@ -134,3 +130,87 @@ def crop_to_center(
     top = (height - crop_height) // 2
 
     return intensities[..., top : top + crop_height, left : left + crop_width]
+
+
+def apply_threshold(
+    intensities: ScalarArray,
+    method: Literal[
+        "otsu",
+        "li",
+        "yen",
+        "isodata",
+        "mean",
+        "minimum",
+        "triangle",
+        "local",
+        "niblack",
+        "sauvola",
+    ] = "otsu",
+    **kwargs,
+) -> BoolArray:
+    """Apply thresholding to convert grayscale image to binary using various methods.
+
+    Uses threshold calculation methods from skimage.filters to determine an optimal
+    threshold value, then applies it to create a binary image.
+
+    Args:
+        intensities: Input grayscale image array.
+        method: Thresholding method to use. Supported methods include:
+            - 'otsu': Otsu's method (default)
+            - 'li': Li's minimum cross entropy method
+            - 'yen': Yen's method
+            - 'isodata': ISODATA method
+            - 'mean': Mean-based threshold
+            - 'minimum': Minimum method
+            - 'triangle': Triangle algorithm
+            - 'local': Adaptive local threshold
+            - 'niblack': Niblack local threshold
+            - 'sauvola': Sauvola local threshold
+        **kwargs: Additional keyword arguments passed to the thresholding function.
+            For local methods (niblack, sauvola, local), common kwargs include:
+            - window_size: Size of the local neighborhood
+            - k: Parameter controlling threshold adjustment
+
+    Returns:
+        BoolArray: Binary image where pixels above threshold are True.
+
+    Raises:
+        ValueError: If the specified method is not supported.
+
+    Examples:
+        >>> binary = apply_threshold(image, method='otsu')
+        >>> binary = apply_threshold(image, method='sauvola', window_size=25)
+    """
+    # Map method names to skimage.filters threshold functions
+    threshold_methods = {
+        "otsu": ski.filters.threshold_otsu,
+        "li": ski.filters.threshold_li,
+        "yen": ski.filters.threshold_yen,
+        "isodata": ski.filters.threshold_isodata,
+        "mean": ski.filters.threshold_mean,
+        "minimum": ski.filters.threshold_minimum,
+        "triangle": ski.filters.threshold_triangle,
+        "local": ski.filters.threshold_local,
+        "niblack": ski.filters.threshold_niblack,
+        "sauvola": ski.filters.threshold_sauvola,
+    }
+
+    # Handle empty or constant images
+    if intensities.size == 0:
+        return np.zeros_like(intensities, dtype=bool)
+    if np.min(intensities) == np.max(intensities):
+        return np.zeros_like(intensities, dtype=bool)
+
+    method_lower = method.lower()
+    if method_lower not in threshold_methods:
+        raise ValueError(
+            f"Unsupported thresholding method: '{method}'. "
+            f"Supported methods: {', '.join(threshold_methods.keys())}"
+        )
+
+    threshold_func = threshold_methods[method_lower]
+
+    # Local methods (niblack, sauvola) return threshold array, others return scalar
+    threshold_value = threshold_func(intensities, **kwargs)
+
+    return intensities > threshold_value

arcadia_microscopy_tools/pipeline.py

@@ -54,10 +54,14 @@ class Pipeline:
         operations: List of ImageOperation instances to apply in sequence.
         copy: If True, creates a copy of the input array before processing. If False,
             operations are applied directly to the input. Default is False for performance.
+        preserve_dtype: If True, forces output to have the same dtype as input. If False,
+            allows dtype to change based on operations (e.g., uint16 -> float64 for
+            normalization). Default is True.
     """
 
     operations: list[ImageOperation]
     copy: bool = False
+    preserve_dtype: bool = True
 
     def __post_init__(self):
         """Validate the pipeline configuration."""
@@ -80,7 +84,10 @@ class Pipeline:
         Returns:
             ScalarArray: The processed image intensity array after applying all operations.
         """
-        return self._apply_operations(intensities)
+        result = self._apply_operations(intensities)
+        if self.preserve_dtype and result.dtype != intensities.dtype:
+            return result.astype(intensities.dtype)  # type: ignore
+        return result
 
     def __len__(self) -> int:
         """Return the number of operations in the pipeline."""
@@ -89,8 +96,13 @@ class Pipeline:
     def __repr__(self) -> str:
         """Create a string representation of the pipeline."""
         operations_repr = ", ".join(repr(operation) for operation in self.operations)
-        copy_str = ", copy=True" if self.copy else ""
-        return f"Pipeline([{operations_repr}]{copy_str})"
+        params = []
+        if self.copy:
+            params.append("copy=True")
+        if not self.preserve_dtype:
+            params.append("preserve_dtype=False")
+        params_str = f", {', '.join(params)}" if params else ""
+        return f"Pipeline([{operations_repr}]{params_str})"
 
 
 @dataclass
@@ -106,10 +118,13 @@ class PipelineParallelized:
 
     Attributes:
         operations: List of ImageOperation instances to apply in sequence.
-        max_workers: Maximum number of worker threads for parallel processing. If None,
-            ThreadPoolExecutor will use its default (typically number of CPU cores).
         copy: If True, creates a copy of each frame before processing. If False,
             operations are applied directly to each frame. Default is False for performance.
+        preserve_dtype: If True, forces output to have the same dtype as input. If False,
+            allows dtype to change based on operations (e.g., uint16 -> float64 for
+            normalization). Default is True.
+        max_workers: Maximum number of worker threads for parallel processing. If None,
+            ThreadPoolExecutor will use its default (typically number of CPU cores).
 
     Note:
         Uses thread-based parallelism, which is most effective for operations that release
@@ -118,8 +133,9 @@ class PipelineParallelized:
     """
 
     operations: list[ImageOperation]
-    max_workers: int | None = None
     copy: bool = False
+    preserve_dtype: bool = True
+    max_workers: int | None = None
 
     def __post_init__(self):
         """Validate the pipeline configuration."""
@@ -145,7 +161,10 @@ class PipelineParallelized:
         with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
             processed = list(executor.map(self._apply_operations, intensities))
 
-        return np.array(processed, dtype=intensities.dtype)  # type: ignore
+        if self.preserve_dtype:
+            return np.array(processed, dtype=intensities.dtype)  # type: ignore
+        else:
+            return np.array(processed)  # type: ignore
 
     def __len__(self) -> int:
         """Return the number of operations in the pipeline."""
@@ -155,9 +174,11 @@ class PipelineParallelized:
         """Create a string representation of the pipeline."""
         operations_repr = ", ".join(repr(operation) for operation in self.operations)
         params = []
-        if self.max_workers is not None:
-            params.append(f"max_workers={self.max_workers}")
         if self.copy:
             params.append("copy=True")
+        if not self.preserve_dtype:
+            params.append("preserve_dtype=False")
+        if self.max_workers is not None:
+            params.append(f"max_workers={self.max_workers}")
         params_str = f", {', '.join(params)}" if params else ""
         return f"PipelineParallelized([{operations_repr}]{params_str})"

arcadia_microscopy_tools/tests/test_pipeline.py

@@ -0,0 +1,278 @@
+import numpy as np
+import pytest
+
+from arcadia_microscopy_tools.pipeline import ImageOperation, Pipeline, PipelineParallelized
+
+
+# Simple test operations for testing
+def double_intensity(intensities):
+    """Double all intensity values."""
+    return intensities * 2
+
+
+def add_ten(intensities):
+    """Add 10 to all intensity values."""
+    return intensities + 10
+
+
+def to_float_normalized(intensities):
+    """Convert to float and normalize to [0, 1]."""
+    return intensities.astype(float) / intensities.max()
+
+
+def square_values(intensities):
+    """Square all values."""
+    return intensities**2
+
+
+class TestImageOperation:
+    def test_create_operation_no_args(self):
+        op = ImageOperation(double_intensity)
+        assert op.method == double_intensity
+        assert op.args == ()
+        assert op.kwargs == {}
+
+    def test_create_operation_with_args(self):
+        op = ImageOperation(np.add, 5)
+        assert op.method == np.add
+        assert op.args == (5,)
+
+    def test_create_operation_with_kwargs(self):
+        op = ImageOperation(np.clip, a_min=0, a_max=100)
+        assert op.kwargs == {"a_min": 0, "a_max": 100}
+
+    def test_call_operation(self):
+        op = ImageOperation(double_intensity)
+        image = np.array([1, 2, 3])
+        result = op(image)
+        np.testing.assert_array_equal(result, [2, 4, 6])
+
+    def test_call_operation_with_args(self):
+        op = ImageOperation(np.add, 10)
+        image = np.array([1, 2, 3])
+        result = op(image)
+        np.testing.assert_array_equal(result, [11, 12, 13])
+
+    def test_repr(self):
+        op = ImageOperation(double_intensity)
+        assert "double_intensity" in repr(op)
+
+
+class TestPipeline:
+    def test_create_pipeline(self):
+        ops = [ImageOperation(double_intensity), ImageOperation(add_ten)]
+        pipeline = Pipeline(operations=ops)
+        assert len(pipeline) == 2
+        assert pipeline.copy is False
+        assert pipeline.preserve_dtype is True
+
+    def test_create_pipeline_with_copy(self):
+        ops = [ImageOperation(double_intensity)]
+        pipeline = Pipeline(operations=ops, copy=True)
+        assert pipeline.copy is True
+
+    def test_create_pipeline_with_preserve_dtype_false(self):
+        ops = [ImageOperation(to_float_normalized)]
+        pipeline = Pipeline(operations=ops, preserve_dtype=False)
+        assert pipeline.preserve_dtype is False
+
+    def test_pipeline_requires_operations(self):
+        with pytest.raises(ValueError, match="at least one operation"):
+            Pipeline(operations=[])
+
+    def test_pipeline_single_operation(self):
+        pipeline = Pipeline(operations=[ImageOperation(double_intensity)])
+        image = np.array([1, 2, 3], dtype=np.uint16)
+        result = pipeline(image)
+        np.testing.assert_array_equal(result, [2, 4, 6])
+        assert result.dtype == np.uint16
+
+    def test_pipeline_multiple_operations(self):
+        pipeline = Pipeline(operations=[ImageOperation(double_intensity), ImageOperation(add_ten)])
+        image = np.array([1, 2, 3], dtype=np.uint16)
+        result = pipeline(image)
+        # First double: [2, 4, 6], then add 10: [12, 14, 16]
+        np.testing.assert_array_equal(result, [12, 14, 16])
+        assert result.dtype == np.uint16
+
+    def test_pipeline_preserve_dtype_default(self):
+        """Test that dtype is preserved by default when it changes."""
+        pipeline = Pipeline(operations=[ImageOperation(to_float_normalized)])
+        image = np.array([10, 20, 30], dtype=np.uint16)
+        result = pipeline(image)
+        # to_float_normalized returns float, but preserve_dtype=True should cast back
+        assert result.dtype == np.uint16
+
+    def test_pipeline_preserve_dtype_false(self):
+        """Test that dtype can change when preserve_dtype=False."""
+        pipeline = Pipeline(operations=[ImageOperation(to_float_normalized)], preserve_dtype=False)
+        image = np.array([10, 20, 30], dtype=np.uint16)
+        result = pipeline(image)
+        # Should return float
+        assert result.dtype in (np.float32, np.float64)
+        np.testing.assert_allclose(result, [1 / 3, 2 / 3, 1.0])
+
+    def test_pipeline_with_2d_image(self):
+        """Test pipeline with 2D image arrays."""
+        pipeline = Pipeline(operations=[ImageOperation(double_intensity)])
+        image = np.array([[1, 2], [3, 4]], dtype=np.uint16)
+        result = pipeline(image)
+        expected = np.array([[2, 4], [6, 8]], dtype=np.uint16)
+        np.testing.assert_array_equal(result, expected)
+
+
+class TestPipelineParallelized:
+    def test_create_pipeline_parallelized(self):
+        ops = [ImageOperation(double_intensity)]
+        pipeline = PipelineParallelized(operations=ops)
+        assert len(pipeline) == 1
+        assert pipeline.max_workers is None
+        assert pipeline.copy is False
+        assert pipeline.preserve_dtype is True
+
+    def test_create_pipeline_with_max_workers(self):
+        ops = [ImageOperation(double_intensity)]
+        pipeline = PipelineParallelized(operations=ops, max_workers=4)
+        assert pipeline.max_workers == 4
+
+    def test_pipeline_parallelized_requires_operations(self):
+        with pytest.raises(ValueError, match="at least one operation"):
+            PipelineParallelized(operations=[])
+
+    def test_pipeline_parallelized_3d_array(self):
+        """Test parallel processing of 3D array (e.g., time series)."""
+        pipeline = PipelineParallelized(operations=[ImageOperation(double_intensity)])
+        # Create 3D array: (time, height, width)
+        image = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]], [[9, 10], [11, 12]]], dtype=np.uint16)
+        result = pipeline(image)
+        expected = image * 2
+        np.testing.assert_array_equal(result, expected)
+        assert result.dtype == np.uint16
+
+    def test_pipeline_parallelized_preserve_dtype_default(self):
+        """Test that dtype is preserved by default."""
+        pipeline = PipelineParallelized(operations=[ImageOperation(to_float_normalized)])
+        image = np.array([[[10, 20], [30, 40]]], dtype=np.uint16)
+        result = pipeline(image)
+        # Should preserve uint16 dtype by default
+        assert result.dtype == np.uint16
+
+    def test_pipeline_parallelized_preserve_dtype_false(self):
+        """Test that dtype can change when preserve_dtype=False."""
+        pipeline = PipelineParallelized(
+            operations=[ImageOperation(to_float_normalized)], preserve_dtype=False
+        )
+        image = np.array([[[10, 20], [30, 40]]], dtype=np.uint16)
+        result = pipeline(image)
+        # Should return float
+        assert result.dtype in (np.float32, np.float64)
+
+    def test_pipeline_parallelized_multiple_operations(self):
+        """Test multiple operations in parallel pipeline."""
+        pipeline = PipelineParallelized(
+            operations=[ImageOperation(double_intensity), ImageOperation(add_ten)]
+        )
+        image = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]], dtype=np.uint16)
+        result = pipeline(image)
+        # First double, then add 10
+        expected = (image * 2) + 10
+        np.testing.assert_array_equal(result, expected)
+
+    def test_pipeline_parallelized_single_frame(self):
+        """Test with single frame (edge case)."""
+        pipeline = PipelineParallelized(operations=[ImageOperation(double_intensity)])
+        image = np.array([[[1, 2], [3, 4]]], dtype=np.uint16)
+        result = pipeline(image)
+        expected = image * 2
+        np.testing.assert_array_equal(result, expected)
+
+    def test_pipeline_parallelized_many_frames(self):
+        """Test with many frames to ensure parallelization works."""
+        pipeline = PipelineParallelized(
+            operations=[ImageOperation(double_intensity)], max_workers=2
+        )
+        # Create 10 frames
+        image = np.random.randint(0, 100, size=(10, 32, 32), dtype=np.uint16)
+        result = pipeline(image)
+        expected = image * 2
+        np.testing.assert_array_equal(result, expected)
+
+
+class TestPipelineIntegration:
+    """Integration tests for realistic use cases."""
+
+    def test_normalization_workflow_preserve_dtype_false(self):
+        """Test a realistic normalization workflow for ML preprocessing."""
+        from arcadia_microscopy_tools.operations import rescale_by_percentile
+
+        # Simulate 16-bit microscopy images (3 frames)
+        image = np.random.randint(0, 65535, size=(3, 128, 128), dtype=np.uint16)
+
+        pipeline = PipelineParallelized(
+            operations=[
+                ImageOperation(
+                    rescale_by_percentile,
+                    percentile_range=(2, 98),
+                    out_range=(0, 1),
+                )
+            ],
+            preserve_dtype=False,
+        )
+
+        result = pipeline(image)
+
+        # Should be normalized to [0, 1] float range
+        assert result.dtype in (np.float32, np.float64)
+        assert result.min() >= 0
+        assert result.max() <= 1
+
+    def test_normalization_workflow_preserve_dtype_true(self):
+        """Test normalization with dtype preservation (legacy behavior)."""
+        from arcadia_microscopy_tools.operations import rescale_by_percentile
+
+        # Simulate 16-bit microscopy images
+        image = np.random.randint(0, 65535, size=(3, 128, 128), dtype=np.uint16)
+
+        pipeline = PipelineParallelized(
+            operations=[
+                ImageOperation(
+                    rescale_by_percentile,
+                    percentile_range=(2, 98),
+                    out_range=(0, 65535),
+                )
+            ],
+            preserve_dtype=True,
+        )
+
+        result = pipeline(image)
+
+        # Should stay as uint16
+        assert result.dtype == np.uint16
+
+    def test_background_subtraction_and_normalization(self):
+        """Test combining background subtraction with normalization."""
+        from arcadia_microscopy_tools.operations import (
+            rescale_by_percentile,
+            subtract_background_dog,
+        )
+
+        # Create test image with background
+        image = np.random.randint(100, 200, size=(2, 64, 64), dtype=np.uint16)
+
+        pipeline = PipelineParallelized(
+            operations=[
+                ImageOperation(subtract_background_dog, low_sigma=1, high_sigma=10),
+                ImageOperation(
+                    rescale_by_percentile,
+                    percentile_range=(1, 99),
+                    out_range=(0, 1),
+                ),
+            ],
+            preserve_dtype=False,
+        )
+
+        result = pipeline(image)
+
+        # Should be float after processing
+        assert result.dtype in (np.float32, np.float64)
+        assert result.shape == image.shape

arcadia_microscopy_tools/typing.py

@@ -2,8 +2,9 @@ import numpy as np
 from numpy.typing import NDArray
 
 BoolArray = NDArray[np.bool_]
-FloatArray = NDArray[np.float64]
-Int64Array = NDArray[np.int64]
+UByteArray = NDArray[np.uint8]
 UInt16Array = NDArray[np.uint16]
-UByteArray = NDArray[np.ubyte]
-ScalarArray = BoolArray | FloatArray | Int64Array | UInt16Array
+Int64Array = NDArray[np.int64]
+Float64Array = NDArray[np.float64]
+
+ScalarArray = BoolArray | Float64Array | Int64Array | UInt16Array | UByteArray

{arcadia_microscopy_tools-0.2.3.dist-info → arcadia_microscopy_tools-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arcadia-microscopy-tools
-Version: 0.2.3
+Version: 0.2.5
 Summary: Python package for processing large-scale microscopy datasets generated by Arcadia's imaging suite
 License: MIT License
         

{arcadia_microscopy_tools-0.2.3.dist-info → arcadia_microscopy_tools-0.2.5.dist-info}/RECORD

@@ -1,15 +1,15 @@
-arcadia_microscopy_tools/__init__.py,sha256=e6hSuo_4-fBlPEt6M9dMvNPH-HcDWboWSy6Vhp5_WzI,440
-arcadia_microscopy_tools/blending.py,sha256=mZNveRf7oNMbRt-Uxas6xCWZH8_U2pKP218j2Zo3cKc,7086
+arcadia_microscopy_tools/__init__.py,sha256=HmMHWrlDh8pAB6f_an39kuDiujpPl4UBAvL0eBd1Bdo,440
+arcadia_microscopy_tools/blending.py,sha256=Y5xuius1tHRKIEfueUjZ7qGlBK02arEYqrzRRhEdSTI,7112
 arcadia_microscopy_tools/channels.py,sha256=sE54mJoJnFIMowO_qRG4lx-s_LOaVO10tuxpuVadJg8,6854
-arcadia_microscopy_tools/masks.py,sha256=Qlgy24jQkx3j09vuObRdgLuYy18PMJcv8XqiAqvvi1Q,15262
-arcadia_microscopy_tools/metadata_structures.py,sha256=fRi0nFwsfavW3YB_1QrpkfH-klp7GC84tCgoogXmMes,3475
+arcadia_microscopy_tools/masks.py,sha256=112486kqgMwNxLvTk9FBj8Rdo-cMOaOpToFD1_RwUQ0,15800
+arcadia_microscopy_tools/metadata_structures.py,sha256=Bb4UXgiNuJcOITNGV_4hGR09HaN8Wt7heET4bXmNcw0,3481
 arcadia_microscopy_tools/microplate.py,sha256=df6HTeQdYQRD7rYKubx8_FWOZ1BbJVoyg7lYySHJQOU,8298
 arcadia_microscopy_tools/microscopy.py,sha256=gPvMVKukGkBY74Ajy71JOd7DfZOoCEfiE40qkBW-C-I,11313
-arcadia_microscopy_tools/model.py,sha256=k4VL3OY2Uw_Oij-9ZJOAHaIbaFtOdtWNQVsE7nHKh_U,12482
-arcadia_microscopy_tools/nikon.py,sha256=JzvPH6IdLMY_txUyVqMu_ENVA7xeznWiijE4KWy6De8,10807
-arcadia_microscopy_tools/operations.py,sha256=3haiordlZ-vBZ8CdOIo-xzgANoNMI-DThon3gudfB3k,4968
-arcadia_microscopy_tools/pipeline.py,sha256=EHn7GYgtFJBA_yKopRXzXBteXu117zXxL6YBOGw4Xu0,6304
-arcadia_microscopy_tools/typing.py,sha256=8y9AWMfRK83sjkxlx2z7DdZOLHhWQ7vEShIwcyOPeOQ,275
+arcadia_microscopy_tools/model.py,sha256=IfDmTE7zUW2xa0O1fA0kQd_SL7Ank0_p-tIx-_UYdII,12488
+arcadia_microscopy_tools/nikon.py,sha256=RdkpN2M77h7_2Bb28nEou6m2MAEIjvwPvxxCHmWzf98,10811
+arcadia_microscopy_tools/operations.py,sha256=lI1SazqOGzYdQtMR2aF3aKwhglul5XJz8qZwYMQwAJE,7939
+arcadia_microscopy_tools/pipeline.py,sha256=uq0O7dwFLiGWMNAZw1rdTbWFRML0Zvk2as9cAvjVQAo,7338
+arcadia_microscopy_tools/typing.py,sha256=cGGvVo4cuW7xtL5MUCBPMW9_8H5yB8GFL_N1xdgBo78,293
 arcadia_microscopy_tools/utils.py,sha256=W2x4q7pbPrVvZ0xZiW4BSyvJZ5bHDZ16am520_zA6rc,2970
 arcadia_microscopy_tools/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 arcadia_microscopy_tools/tests/conftest.py,sha256=NJh9D_k_rrtHdnUfWtsc5CDbqbFIhZhXgRcFb7Dqc78,1461
@@ -17,6 +17,7 @@ arcadia_microscopy_tools/tests/test_channels.py,sha256=ztrnknb9cZuIR6hwTmgQ5uP51
 arcadia_microscopy_tools/tests/test_microplate.py,sha256=3xVdv958IwH52XTThuqWuj5ZGrJrCfJqAY2Vi93IPPo,1838
 arcadia_microscopy_tools/tests/test_microscopy.py,sha256=nLiCG3sQ1huZJu2W11k9UCmSBCGDCXsXGb_9G4h1jAg,2062
 arcadia_microscopy_tools/tests/test_model.py,sha256=aVqAalWoyB_Ay03Y5ErLXIgKBqnUBorxflvllzBO4eQ,19743
+arcadia_microscopy_tools/tests/test_pipeline.py,sha256=rlMPiRwOKGnL5uIlgTu0_oMtt6bAGLcBSmPNi654SxQ,10643
 arcadia_microscopy_tools/tests/data/README.md,sha256=TLV01Qo_QYTqIk351Q_9hO9NrR5FARnezKDZbI5oREc,1683
 arcadia_microscopy_tools/tests/data/example-cerevisiae.nd2,sha256=ymhS7GciOyD6XJqJvYF3iZRZtnEf-6n_z_MHjufIGoE,503808
 arcadia_microscopy_tools/tests/data/example-multichannel.nd2,sha256=_Ol47B_PK5GcF8ruBBvBElOa17nfLjeQsiYp0UUpkx0,876544
@@ -24,7 +25,7 @@ arcadia_microscopy_tools/tests/data/example-pbmc.nd2,sha256=gqVP7cGePBJk45xRpyXa
 arcadia_microscopy_tools/tests/data/example-timelapse.nd2,sha256=KHCubkVWmkRRmJabhfINx_aTwNi5nVUl-IiYNKQsJ9Y,827392
 arcadia_microscopy_tools/tests/data/example-zstack.nd2,sha256=j70DrFhRTwRgzAAJivVM3mCho05YVgsqJwTmPBobRYo,606208
 arcadia_microscopy_tools/tests/data/known-metadata.yml,sha256=_ZIE04MnoLpZtG-6e8ZytYnmAkGh0Q7-2AwSP3v6rQk,1886
-arcadia_microscopy_tools-0.2.3.dist-info/METADATA,sha256=X9XmEfOs5OHYyRhhsfAdtNmYQ3CbOQcQj_seQODVe6o,5007
-arcadia_microscopy_tools-0.2.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-arcadia_microscopy_tools-0.2.3.dist-info/licenses/LICENSE,sha256=5pPae5U0NNXysjBv3vjoquhhoCqTTi1Zh0SehM_IXHI,1072
-arcadia_microscopy_tools-0.2.3.dist-info/RECORD,,
+arcadia_microscopy_tools-0.2.5.dist-info/METADATA,sha256=y2JLq5xdW2Anen9vmLV0LN4nOOrPSacQLvAmj3Q6IzA,5007
+arcadia_microscopy_tools-0.2.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+arcadia_microscopy_tools-0.2.5.dist-info/licenses/LICENSE,sha256=5pPae5U0NNXysjBv3vjoquhhoCqTTi1Zh0SehM_IXHI,1072
+arcadia_microscopy_tools-0.2.5.dist-info/RECORD,,