waveorder 3.0.0a2__py3-none-any.whl → 3.0.0a3__py3-none-any.whl

waveorder/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.0.0a2'
-__version_tuple__ = version_tuple = (3, 0, 0, 'a2')
+__version__ = version = '3.0.0a3'
+__version_tuple__ = version_tuple = (3, 0, 0, 'a3')
 
 __commit_id__ = commit_id = None

waveorder/cli/apply_inverse_models.py

@@ -5,6 +5,7 @@ This module converts GUI-level reconstruction calls into library calls
 import numpy as np
 import torch
 
+from waveorder.cli.settings import FluorescenceSettings, PhaseSettings
 from waveorder.models import (
     inplane_oriented_thick_pol3d,
     inplane_oriented_thick_pol3d_vector,
@@ -62,7 +63,7 @@ def birefringence(
 def phase(
     czyx_data,
     recon_dim,
-    settings_phase,
+    settings_phase: PhaseSettings,
     transfer_function_dataset,
 ):
     # [phase only, 2]
@@ -83,7 +84,7 @@ def phase(
         ) = isotropic_thin_3d.apply_inverse_transfer_function(
             czyx_data[0],
             (U, S, Vh),
-            **settings_phase.apply_inverse.dict(),
+            **settings_phase.apply_inverse.model_dump(),
         )
         # Stack to C1YX
         output = phase_yx[None, None]
@@ -108,7 +109,7 @@ def phase(
             real_potential_transfer_function,
             imaginary_potential_transfer_function,
             z_padding=settings_phase.transfer_function.z_padding,
-            **settings_phase.apply_inverse.dict(),
+            **settings_phase.apply_inverse.model_dump(),
         )
 
     # Pad to CZYX
@@ -124,7 +125,7 @@ def birefringence_and_phase(
     wavelength_illumination,
     recon_dim,
     biref_inverse_dict,
-    settings_phase,
+    settings_phase: PhaseSettings,
     transfer_function_dataset,
 ):
     # Load birefringence transfer function
@@ -174,7 +175,7 @@ def birefringence_and_phase(
         ) = isotropic_thin_3d.apply_inverse_transfer_function(
             brightfield_3d,
             (U, S, Vh),
-            **settings_phase.apply_inverse.dict(),
+            **settings_phase.apply_inverse.model_dump(),
         )
 
         # Convert retardance
@@ -222,7 +223,7 @@ def birefringence_and_phase(
             real_potential_transfer_function,
             imaginary_potential_transfer_function,
             z_padding=settings_phase.transfer_function.z_padding,
-            **settings_phase.apply_inverse.dict(),
+            **settings_phase.apply_inverse.model_dump(),
         )
 
         # Convert retardance
@@ -253,7 +254,7 @@ def birefringence_and_phase(
             szyx_data=stokes,
             singular_system=singular_system,
             intensity_to_stokes_matrix=None,
-            **settings_phase.apply_inverse.dict(),
+            **settings_phase.apply_inverse.model_dump(),
         )
 
         new_ret = (
@@ -282,7 +283,10 @@ def birefringence_and_phase(
 
 
 def fluorescence(
-    czyx_data, recon_dim, settings_fluorescence, transfer_function_dataset
+    czyx_data,
+    recon_dim,
+    settings_fluorescence: FluorescenceSettings,
+    transfer_function_dataset,
 ):
     # [fluo, 2]
     if recon_dim == 2:
@@ -299,7 +303,7 @@ def fluorescence(
         output = isotropic_fluorescent_thin_3d.apply_inverse_transfer_function(
             czyx_data[0],
             (U, S, Vh),
-            **settings_fluorescence.apply_inverse.dict(),
+            **settings_fluorescence.apply_inverse.model_dump(),
         )
     # [fluo, 3]
     elif recon_dim == 3:
@@ -314,7 +318,7 @@ def fluorescence(
                 czyx_data[0],
                 optical_transfer_function,
                 settings_fluorescence.transfer_function.z_padding,
-                **settings_fluorescence.apply_inverse.dict(),
+                **settings_fluorescence.apply_inverse.model_dump(),
             )
         )
         # Pad to CZYX

waveorder/cli/apply_inverse_transfer_function.py

@@ -47,7 +47,7 @@ def get_reconstruction_output_metadata(position_path: Path, config_path: Path):
         )
         plate_metadata = dict(input_plate.zattrs)
         plate_metadata.pop("plate")
-    except RuntimeError:
+    except (RuntimeError, FileNotFoundError):
         warnings.warn(
             "Position is not part of a plate...no plate metadata will be copied."
         )
@@ -171,7 +171,7 @@ def apply_inverse_transfer_function_single_position(
         # so this section converts the settings to a dict and separates the
         # waveorder parameters (biref_inverse_dict) from the waveorder
         # parameters (cyx_no_sample_data, and wavelength_illumination)
-        biref_inverse_dict = settings.birefringence.apply_inverse.dict()
+        biref_inverse_dict = settings.birefringence.apply_inverse.model_dump()
 
         # Resolve background path into array
         background_path = biref_inverse_dict.pop("background_path")
@@ -279,7 +279,7 @@ def apply_inverse_transfer_function_single_position(
             partial_apply_inverse_to_zyx_and_save(t_idx)
 
     # Save metadata at position level
-    output_dataset.zattrs["settings"] = settings.dict()
+    output_dataset.zattrs["settings"] = settings.model_dump()
 
     echo_headline(f"Closing {output_position_dirpath}\n")
 

waveorder/cli/compute_transfer_function.py

@@ -67,14 +67,14 @@ def generate_and_save_vector_birefringence_transfer_function(
     echo_headline(
         f"Downsampling transfer function in X and Y by {transverse_downsample_factor}x"
     )
-    phase_settings_dict = settings.phase.transfer_function.dict()
+    phase_settings_dict = settings.phase.transfer_function.model_dump()
     phase_settings_dict.pop("z_focus_offset")  # not used in 3D
 
     sfZYX_transfer_function, _, singular_system = (
         inplane_oriented_thick_pol3d_vector.calculate_transfer_function(
             zyx_shape=zyx_shape,
             scheme=str(len(settings.input_channel_names)) + "-State",
-            **settings.birefringence.transfer_function.dict(),
+            **settings.birefringence.transfer_function.model_dump(),
             **phase_settings_dict,
             fourier_oversample_factor=int(transverse_downsample_factor),
         )
@@ -109,7 +109,9 @@ def generate_and_save_vector_birefringence_transfer_function(
     )
 
 
-def generate_and_save_birefringence_transfer_function(settings, dataset):
+def generate_and_save_birefringence_transfer_function(
+    settings: ReconstructionSettings, dataset
+):
     """Generates and saves the birefringence transfer function to the dataset, based on the settings.
 
     Parameters
@@ -125,7 +127,7 @@ def generate_and_save_birefringence_transfer_function(settings, dataset):
     intensity_to_stokes_matrix = (
         inplane_oriented_thick_pol3d.calculate_transfer_function(
             scheme=str(len(settings.input_channel_names)) + "-State",
-            **settings.birefringence.transfer_function.dict(),
+            **settings.birefringence.transfer_function.model_dump(),
         )
     )
     # Save
@@ -152,7 +154,7 @@ def generate_and_save_phase_transfer_function(
     echo_headline("Generating phase transfer function with settings:")
     echo_settings(settings.phase.transfer_function)
 
-    settings_dict = settings.phase.transfer_function.dict()
+    settings_dict = settings.phase.transfer_function.model_dump()
     if settings.reconstruction_dimension == 2:
         # Convert zyx_shape and z_pixel_size into yx_shape and z_position_list
         settings_dict["yx_shape"] = [zyx_shape[1], zyx_shape[2]]
@@ -240,7 +242,7 @@ def generate_and_save_fluorescence_transfer_function(
     """
     echo_headline("Generating fluorescence transfer function with settings:")
     echo_settings(settings.fluorescence.transfer_function)
-    settings_dict = settings.fluorescence.transfer_function.dict()
+    settings_dict = settings.fluorescence.transfer_function.model_dump()
 
     if settings.reconstruction_dimension == 2:
         # Convert zyx_shape and z_pixel_size into yx_shape and z_position_list
@@ -396,7 +398,7 @@ def compute_transfer_function_cli(
         )
 
     # Write settings to metadata
-    output_dataset.zattrs["settings"] = settings.dict()
+    output_dataset.zattrs["settings"] = settings.model_dump()
 
     echo_headline(f"Closing {output_dirpath}\n")
     output_dataset.close()

waveorder/cli/printing.py

@@ -1,10 +1,14 @@
 import click
 import yaml
 
+from waveorder.cli.settings import MyBaseModel
 
-def echo_settings(settings):
+
+def echo_settings(settings: MyBaseModel):
     click.echo(
-        yaml.dump(settings.dict(), default_flow_style=False, sort_keys=False)
+        yaml.dump(
+            settings.model_dump(), default_flow_style=False, sort_keys=False
+        )
     )
 
 

waveorder/cli/settings.py

@@ -3,14 +3,15 @@ import warnings
 from pathlib import Path
 from typing import List, Literal, Optional, Union
 
-from pydantic.v1 import (
+from pydantic import (
     BaseModel,
+    ConfigDict,
     Extra,
     NonNegativeFloat,
     NonNegativeInt,
     PositiveFloat,
-    root_validator,
-    validator,
+    field_validator,
+    model_validator,
 )
 
 # This file defines the configuration settings for the CLI.
@@ -22,8 +23,8 @@ from pydantic.v1 import (
 
 
 # All settings classes inherit from MyBaseModel, which forbids extra parameters to guard against typos
-class MyBaseModel(BaseModel, extra=Extra.forbid):
-    pass
+class MyBaseModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
 
 
 # Bottom level settings
@@ -34,7 +35,8 @@ class WavelengthIllumination(MyBaseModel):
 class BirefringenceTransferFunctionSettings(MyBaseModel):
     swing: float = 0.1
 
-    @validator("swing")
+    @field_validator("swing")
+    @classmethod
     def swing_range(cls, v):
         if v <= 0 or v >= 1.0:
             raise ValueError(f"swing = {v} should be between 0 and 1.")
@@ -43,11 +45,9 @@ class BirefringenceTransferFunctionSettings(MyBaseModel):
 
 class BirefringenceApplyInverseSettings(WavelengthIllumination):
     background_path: Union[str, Path] = ""
-    remove_estimated_background: bool = False
-    flip_orientation: bool = False
-    rotate_orientation: bool = False
 
-    @validator("background_path")
+    @field_validator("background_path")
+    @classmethod
     def check_background_path(cls, v):
         if v == "":
             return v
@@ -57,34 +57,36 @@ class BirefringenceApplyInverseSettings(WavelengthIllumination):
             raise ValueError(f"{v} is not a existing directory")
         return raw_dir
 
+    remove_estimated_background: bool = False
+    flip_orientation: bool = False
+    rotate_orientation: bool = False
+
 
 class FourierTransferFunctionSettings(MyBaseModel):
     yx_pixel_size: PositiveFloat = 6.5 / 20
     z_pixel_size: PositiveFloat = 2.0
     z_padding: NonNegativeInt = 0
-    z_focus_offset: Union[int, Literal["auto"]] = 0
+    z_focus_offset: Union[float, Literal["auto"]] = 0
     index_of_refraction_media: PositiveFloat = 1.3
     numerical_aperture_detection: PositiveFloat = 1.2
 
-    @validator("numerical_aperture_detection")
-    def na_det(cls, v, values):
-        n = values["index_of_refraction_media"]
-        if v > n:
+    @model_validator(mode="after")
+    def validate_numerical_aperture_detection(self):
+        if self.numerical_aperture_detection > self.index_of_refraction_media:
             raise ValueError(
-                f"numerical_aperture_detection = {v} must be less than or equal to index_of_refraction_media = {n}"
+                f"numerical_aperture_detection = {self.numerical_aperture_detection} must be less than or equal to index_of_refraction_media = {self.index_of_refraction_media}"
             )
-        return v
+        return self
 
-    @validator("z_pixel_size")
-    def warn_unit_consistency(cls, v, values):
-        yx_pixel_size = values["yx_pixel_size"]
-        ratio = yx_pixel_size / v
+    @model_validator(mode="after")
+    def warn_unit_consistency(self):
+        ratio = self.yx_pixel_size / self.z_pixel_size
         if ratio < 1.0 / 20 or ratio > 20:
             warnings.warn(
-                f"yx_pixel_size ({yx_pixel_size}) / z_pixel_size ({v}) = {ratio}. Did you use consistent units?",
+                f"yx_pixel_size ({self.yx_pixel_size}) / z_pixel_size ({self.z_pixel_size}) = {ratio}. Did you use consistent units?",
                 UserWarning,
             )
-        return v
+        return self
 
 
 class FourierApplyInverseSettings(MyBaseModel):
@@ -101,30 +103,31 @@ class PhaseTransferFunctionSettings(
     numerical_aperture_illumination: NonNegativeFloat = 0.5
     invert_phase_contrast: bool = False
 
-    @validator("numerical_aperture_illumination")
-    def na_ill(cls, v, values):
-        n = values.get("index_of_refraction_media")
-        if v > n:
+    @model_validator(mode="after")
+    def validate_numerical_aperture_illumination(self):
+        if (
+            self.numerical_aperture_illumination
+            > self.index_of_refraction_media
+        ):
             raise ValueError(
-                f"numerical_aperture_illumination = {v} must be less than or equal to index_of_refraction_media = {n}"
+                f"numerical_aperture_illumination = {self.numerical_aperture_illumination} must be less than or equal to index_of_refraction_media = {self.index_of_refraction_media}"
             )
-        return v
+        return self
 
 
 class FluorescenceTransferFunctionSettings(FourierTransferFunctionSettings):
     wavelength_emission: PositiveFloat = 0.507
     confocal_pinhole_diameter: Optional[PositiveFloat] = None
 
-    @validator("wavelength_emission")
-    def warn_unit_consistency(cls, v, values):
-        yx_pixel_size = values.get("yx_pixel_size")
-        ratio = yx_pixel_size / v
+    @model_validator(mode="after")
+    def warn_unit_consistency(self):
+        ratio = self.yx_pixel_size / self.wavelength_emission
         if ratio < 1.0 / 20 or ratio > 20:
             warnings.warn(
-                f"yx_pixel_size ({yx_pixel_size}) / wavelength_illumination ({v}) = {ratio}. Did you use consistent units?",
+                f"yx_pixel_size ({self.yx_pixel_size}) / wavelength_illumination ({self.wavelength_emission}) = {ratio}. Did you use consistent units?",
                 UserWarning,
             )
-        return v
+        return self
 
 
 # Second level settings
@@ -158,24 +161,21 @@ class ReconstructionSettings(MyBaseModel):
         NonNegativeInt, List[NonNegativeInt], Literal["all"]
     ] = "all"
     reconstruction_dimension: Literal[2, 3] = 3
-    birefringence: Optional[BirefringenceSettings]
-    phase: Optional[PhaseSettings]
-    fluorescence: Optional[FluorescenceSettings]
-
-    @root_validator(pre=False)
-    def validate_reconstruction_types(cls, values):
-        if (values.get("birefringence") or values.get("phase")) and values.get(
-            "fluorescence"
-        ) is not None:
+    birefringence: Optional[BirefringenceSettings] = None
+    phase: Optional[PhaseSettings] = None
+    fluorescence: Optional[FluorescenceSettings] = None
+
+    @model_validator(mode="after")
+    def validate_reconstruction_types(self):
+        if (
+            self.birefringence or self.phase
+        ) and self.fluorescence is not None:
             raise ValueError(
                 '"fluorescence" cannot be present alongside "birefringence" or "phase". Please use one configuration file for a "fluorescence" reconstruction and another configuration file for a "birefringence" and/or "phase" reconstructions.'
             )
-        num_channel_names = len(values.get("input_channel_names"))
-        if values.get("birefringence") is None:
-            if (
-                values.get("phase") is None
-                and values.get("fluorescence") is None
-            ):
+        num_channel_names = len(self.input_channel_names)
+        if self.birefringence is None:
+            if self.phase is None and self.fluorescence is None:
                 raise ValueError(
                     "Provide settings for either birefringence, phase, birefringence + phase, or fluorescence."
                 )
@@ -184,4 +184,4 @@ class ReconstructionSettings(MyBaseModel):
                     f"{num_channel_names} channels names provided. Please provide a single channel for fluorescence/phase reconstructions."
                 )
 
-        return values
+        return self

waveorder/cli/utils.py

@@ -37,7 +37,7 @@ def is_single_position_store(position_path: Path) -> bool:
         # Try to open as HCS plate 3 levels up
         open_ome_zarr(position_path.parent.parent.parent, mode="r")
         return False  # Successfully opened as plate
-    except RuntimeError:
+    except (RuntimeError, FileNotFoundError):
         return True  # Not a plate structure
 
 

waveorder/focus.py

@@ -60,6 +60,8 @@ def focus_from_transverse_band(
     polynomial_fit_order: Optional[int] = None,
     plot_path: Optional[str] = None,
     threshold_FWHM: float = 0,
+    return_statistics: bool = False,
+    enable_subpixel_precision: bool = False,
 ):
     """Estimates the in-focus slice from a 3D stack by optimizing a transverse spatial frequency band.
 
@@ -91,14 +93,22 @@ def focus_from_transverse_band(
         The default value, 0, applies no threshold, and the maximum midband power is always considered in focus.
         For values > 0, the peak's FWHM must be greater than the threshold for the slice to be considered in focus.
         If the peak does not meet this threshold, the function returns None.
+    return_statistics: bool, optional
+        If True, returns a tuple (in_focus_index, peak_stats) instead of just in_focus_index.
+        Default is False for backward compatibility.
+    enable_subpixel_precision: bool, optional
+        If True and polynomial_fit_order is provided, enables sub-pixel precision focus detection
+        by finding the continuous extremum of the polynomial fit. Default is False for backward compatibility.
 
     Returns
-    ------
-    slice : int or None
-        If peak's FWHM > peak_width_threshold:
-            return the index of the in-focus slice
-        else:
-            return None
+    -------
+    slice : int, float, None, or tuple
+        If return_statistics is False (default):
+            Returns in_focus_index (int if enable_subpixel_precision=False,
+            float if enable_subpixel_precision=True and polynomial_fit_order is not None, or None).
+        If return_statistics is True:
+            Returns tuple (in_focus_index, peak_stats) where peak_stats is a dict
+            containing 'peak_index' and 'peak_FWHM'.
 
     Example
     ------
@@ -109,6 +119,7 @@ def focus_from_transverse_band(
     >>> in_focus_data = data[slice,:,:]
     """
     minmaxfunc = _mode_to_minmaxfunc(mode)
+    peak_stats = {"peak_index": None, "peak_FWHM": None}
 
     _check_focus_inputs(
         zyx_array, NA_det, lambda_ill, pixel_size, midband_fractions
@@ -119,6 +130,8 @@ def focus_from_transverse_band(
         warnings.warn(
             "The dataset only contained a single slice. Returning trivial slice index = 0."
         )
+        if return_statistics:
+            return 0, peak_stats
         return 0
 
     # Calculate midband power for each slice
@@ -140,10 +153,48 @@ def focus_from_transverse_band(
     else:
         x = np.arange(len(midband_sum))
         coeffs = np.polyfit(x, midband_sum, polynomial_fit_order)
-        peak_index = minmaxfunc(np.poly1d(coeffs)(x))
+        poly_func = np.poly1d(coeffs)
+
+        if enable_subpixel_precision:
+            # Find the continuous extremum using derivative
+            poly_deriv = np.polyder(coeffs)
+            # Find roots of the derivative (critical points)
+            critical_points = np.roots(poly_deriv)
 
-    peak_results = peak_widths(midband_sum, [peak_index])
+            # Filter for real roots within the data range
+            real_critical_points = []
+            for cp in critical_points:
+                if np.isreal(cp) and 0 <= cp.real < len(midband_sum):
+                    real_critical_points.append(cp.real)
+
+            if real_critical_points:
+                # Evaluate the polynomial at critical points to find extremum
+                critical_values = [
+                    poly_func(cp) for cp in real_critical_points
+                ]
+                if mode == "max":
+                    best_idx = np.argmax(critical_values)
+                else:  # mode == "min"
+                    best_idx = np.argmin(critical_values)
+                peak_index = real_critical_points[best_idx]
+            else:
+                # Fall back to discrete maximum if no valid critical points
+                peak_index = float(minmaxfunc(poly_func(x)))
+        else:
+            peak_index = minmaxfunc(poly_func(x))
+
+    # For peak width calculation, use integer peak index
+    if enable_subpixel_precision and polynomial_fit_order is not None:
+        # Use the closest integer index for peak width calculation
+        integer_peak_index = int(np.round(peak_index))
+    else:
+        integer_peak_index = int(peak_index)
+
+    peak_results = peak_widths(midband_sum, [integer_peak_index])
     peak_FWHM = peak_results[0][0]
+    peak_stats.update(
+        {"peak_index": int(peak_index), "peak_FWHM": float(peak_FWHM)}
+    )
 
     if peak_FWHM >= threshold_FWHM:
         in_focus_index = peak_index
@@ -161,6 +212,9 @@ def focus_from_transverse_band(
             threshold_FWHM,
         )
 
+    if return_statistics:
+        return in_focus_index, peak_stats
+
     return in_focus_index
 
 
@@ -215,9 +269,19 @@ def _plot_focus_metric(
 ):
     _, ax = plt.subplots(1, 1, figsize=(4, 4))
     ax.plot(midband_sum, "-k")
+
+    # Handle floating-point peak_index for plotting
+    if isinstance(peak_index, float) and not peak_index.is_integer():
+        # Use interpolation to get the y-value at the floating-point x-position
+        peak_y_value = np.interp(
+            peak_index, np.arange(len(midband_sum)), midband_sum
+        )
+    else:
+        peak_y_value = midband_sum[int(peak_index)]
+
     ax.plot(
         peak_index,
-        midband_sum[peak_index],
+        peak_y_value,
         "go" if in_focus_index is not None else "ro",
     )
     ax.hlines(*peak_results[1:], color="k", linestyles="dashed")

waveorder/io/utils.py

@@ -7,6 +7,8 @@ import torch
 import yaml
 from iohub import open_ome_zarr
 
+from waveorder.cli.settings import MyBaseModel
+
 
 def add_index_to_path(path: Path):
     """Takes a path to a file or folder and appends the smallest index that does
@@ -76,13 +78,13 @@ def ram_message():
     return (is_warning, message)
 
 
-def model_to_yaml(model, yaml_path: Path) -> None:
+def model_to_yaml(model: MyBaseModel, yaml_path: Path) -> None:
     """
     Save a model's dictionary representation to a YAML file.
 
     Parameters
     ----------
-    model : object
+    model : MyBaseModel
         The model object to convert to YAML.
     yaml_path : Path
         The path to the output YAML file.
@@ -110,7 +112,7 @@ def model_to_yaml(model, yaml_path: Path) -> None:
     if not hasattr(model, "dict"):
         raise TypeError("The 'model' object does not have a 'dict()' method.")
 
-    model_dict = model.dict()
+    model_dict = model.model_dump()
 
     # Remove None-valued fields
     clean_model_dict = {