ref, docs: correct docstrings and use of order for padding_3d

qpretrieve/filter.py

@@ -14,10 +14,10 @@
 
 
 @lru_cache(maxsize=32)
-def get_filter_array(
-        filter_name: str, filter_size: float,
-        freq_pos: tuple[float, float],
-        fft_shape: tuple[int, int]) -> np.ndarray:
+def get_filter_array(filter_name: str,
+                     filter_size: float,
+                     freq_pos: tuple[float, float],
+                     fft_shape: tuple[int, int]) -> np.ndarray:
     """Create a Fourier filter for holography
 
     Parameters

qpretrieve/fourier/base.py

@@ -101,9 +101,10 @@ def __init__(self,
         if padding:
             # zero padding size is next order of 2
             logfact = np.log(padding * max(data_ed.shape))
-            order = int(2 ** np.ceil(logfact / np.log(2)))
+            order = np.ceil(logfact / np.log(2))
+            size = int(2 ** order)
 
-            datapad = padding_3d(data_ed, order, dtype)
+            datapad = padding_3d(data_ed, size, dtype)
             #: padded input data
             self.origin_padded = datapad
             data_ed = datapad

qpretrieve/interfere/if_oah.py

@@ -65,6 +65,8 @@ def run_pipeline(self, **pipeline_kws) -> np.ndarray:
         sideband_freq: tuple of floats
             Frequency coordinates of the sideband to use. By default,
             a heuristic search for the sideband is done.
+            If you pass a 3D array, the first hologram is used to
+            determine the sideband frequencies.
         invert_phase: bool
             Invert the phase data.
         """

qpretrieve/interfere/if_qlsi.py

@@ -88,6 +88,8 @@ def run_pipeline(self, **pipeline_kws) -> np.ndarray:
         sideband_freq: tuple of floats
             Frequency coordinates of the sideband to use. By default,
             a heuristic search for the sideband is done.
+            If you pass a 3D array, the first hologram is used to
+            determine the sideband frequencies.
         invert_phase: bool
             Invert the phase data.
         wavelength: float
@@ -172,9 +174,10 @@ def run_pipeline(self, **pipeline_kws) -> np.ndarray:
 
         # Obtain the phase gradients in x and y by taking the argument
         # of Hx and Hy.
-        # need to do this along the z axis, as skimage `unwrap_3d` does not
-        # work for our use-case
-        # todo: maybe use np.unwrap for the xy axes instead
+        # Every image in the 3D stack must be treated individually with
+        # `unwrap_phase`. If we passed the 3D stack, then skimage would
+        # treat this as a 3D phase-unwrapping problem, which it is not [sic!].
+        # see `tests.test_qlsi.test_qlsi_unwrap_phase_2d_3d`.
         px = np.zeros_like(hx, dtype=float)
         py = np.zeros_like(hy, dtype=float)
         for i, (_hx, _hy) in enumerate(zip(hx, hy)):

qpretrieve/utils.py

@@ -8,7 +8,10 @@ def _mean_2d(data):
 
 
 def mean_3d(data: np.ndarray) -> np.ndarray:
-    """Calculate mean of the data along the z-axis."""
+    """
+    Subtract mean inplace from 3D array `data` for every
+    2D array along z axis.
+    """
     # The mean array here is (1000,), so we need to add newaxes for subtraction
     # (1000, 5, 5) -= (1000, 1, 1)
     data -= data.mean(axis=(-2, -1))[:, np.newaxis, np.newaxis]
@@ -24,21 +27,21 @@ def _padding_2d(data, order, dtype):
     return datapad
 
 
-def padding_3d(data: np.ndarray, order: int, dtype: np.dtype) -> np.ndarray:
-    """Calculate padding of the data along the z-axis.
+def padding_3d(data: np.ndarray, size: int, dtype: np.dtype) -> np.ndarray:
+    """Pad a 3D array in the second and third dimensions (y, x) to `size`
 
     Parameters
     ----------
     data
         3d array. The padding will be applied to the axes (y,x) only.
-    order
-        The data will be padded to this size.
+    size
+        The data will be padded to this size in the (y, x) dimensions.
     dtype
         data type of the padded array.
 
     """
     z, y, x = data.shape
     # this is faster than np.pad
-    datapad = np.zeros((z, order, order), dtype=dtype)
+    datapad = np.zeros((z, size, size), dtype=dtype)
     datapad[:, :y, :x] = data
     return datapad

tests/test_qlsi.py

@@ -48,12 +48,10 @@ def test_qlsi_fftfreq_reshape_2d_3d(hologram):
 
 def test_qlsi_unwrap_phase_2d_3d():
     """
-    Check whether skimage unwrap_2d and unwrap_3d give the same result.
-    In other words, does unwrap_3d apply th unwrapping along the z axis.
-
-    Answer is no, they are different. unwrap_3d is designed for 3D data that
-    is to be unwrapped on all axes at once.
-
+    Check whether `skimage.restoration.unwrap_phase` unwraps 2d
+    images along the z axis when given a 3d array input.
+    Answer is no. `unwrap_phase` is designed for to unwrap data
+    on all axes at once.
     """
     with h5py.File(data_path / "qlsi_paa_bead.h5") as h5:
         image = h5["0"][:]