ref: deprecate hologram input type in favor of raw-oah

CHANGELOG

@@ -1,3 +1,5 @@
+0.7.6
+ - ref: deprecate "hologram" input type in favor of "raw-oah"
 0.7.5
  - enh: write HDF5 image metadata so that HDFView 3.1.1 can
    visualize the phase data

examples/background_mask_sphere.py

@@ -27,7 +27,7 @@
 
 # create QPImage instance
 qpi = qpimage.QPImage(data=edata,
-                      which_data="hologram",
+                      which_data="raw-oah",
                       meta_data={"medium index": 1.335,
                                  "wavelength": 550e-9,
                                  "pixel size": 0.107e-6})

examples/background_poly2o.py

@@ -18,7 +18,7 @@
 edata = np.array(Image.open("./data/hologram_cell_curved_bg.jpg"))
 
 # create QPImage instance
-qpi = qpimage.QPImage(data=edata, which_data="hologram")
+qpi = qpimage.QPImage(data=edata, which_data="raw-oah")
 pha0 = qpi.pha
 
 # background correction using tilt only

examples/hologram_cell.py

@@ -22,8 +22,8 @@
 # create QPImage instance
 qpi = qpimage.QPImage(data=edata["data"],
                       bg_data=edata["bg_data"],
-                      which_data="hologram",
-                      # This parameter allows to pass arguments to the
+                      which_data="raw-oah",
+                      # This parameter allows passing arguments to the
                       # hologram-analysis algorithm of qpimage.
                       # (see qpimage.holo.get_field)
                       holo_kw={

examples/hologram_filters.py

@@ -24,7 +24,7 @@
   quality. Contributions from the central band can lead to strong
   artifacts. A balance between high resolution (large filter size)
   and small contributions from the central band (small filter size)
-  usually has be found.
+  usually has to be found.
 - It is not trivial to compare a gaussian filter with a disk filter
   in terms of filter size (sigma vs. radius).
   The gaussian filter takes into account larger frequencies and
@@ -61,7 +61,7 @@
 
 for filter_name in filters:
     qpi = qpimage.QPImage(data=hologram,
-                          which_data="hologram",
+                          which_data="raw-oah",
                           holo_kw={"filter_size": .5,
                                    "filter_name": filter_name})
     qpis.append(qpi)

qpimage/core.py

@@ -13,7 +13,9 @@
 
 #: valid combinations for keyword argument `which_data`
 VALID_INPUT_DATA = ["field",
-                    "hologram",
+                    "hologram",  # deprecated
+                    "raw-oah",  # off-axis holography
+                    "raw-qlsi",  # quadri-wave lateral shearing interferometry
                     "phase",
                     ("phase", "amplitude"),
                     ("phase", "intensity"),
@@ -42,15 +44,15 @@ def __init__(self, data=None, bg_data=None, which_data="phase",
         which_data: str or tuple
             String or comma-separated list of strings indicating
             the order and type of input data. Valid values are
-            "hologram", "field", "phase", "phase,amplitude",
-            or "phase,intensity", where the latter two require an
-            indexable object with the phase data as first element.
+            defined in :const:`VALID_INPUT_DATA`, where phase and
+            amplitude/intensity data require an indexable object
+            with the phase data as first element.
         meta_data: dict or qpimage.MetaDict
             Metadata associated with the input data.
             see :data:`qpimage.meta.META_KEYS`
         holo_kw: dict
             Special keyword arguments for phase retrieval from
-            hologram data (`which_data="hologram"`).
+            hologram data (`which_data="raw-oah"`).
             See :func:`qpimage.holo.get_field` for valid keyword
             arguments.
 
@@ -263,9 +265,9 @@ def _get_amp_pha(self, data, which_data, proc_phase=True):
         which_data: str
             String or comma-separated list of strings indicating
             the order and type of input data. Valid values are
-            "field", "phase", "hologram", "phase,amplitude", or
-            "phase,intensity", where the latter two require an
-            indexable object with the phase data as first element.
+            defined in :const:`VALID_INPUT_DATA`, where phase and
+            amplitude/intensity data require an indexable object
+            with the phase data as first element.
         proc_phase: bool
             Process the phase data. This includes phase unwrapping
             using :func:`skimage.restoration.unwrap_phase` and
@@ -294,7 +296,11 @@ def _get_amp_pha(self, data, which_data, proc_phase=True):
         elif which_data == ("phase", "intensity"):
             amp = np.sqrt(data[1])
             pha = data[0]
-        elif which_data == "hologram":
+        elif which_data in ["hologram", "raw-oah"]:
+            if which_data == "hologram":
+                warnings.warn("The 'hologram' data type is deprecated, "
+                              + "please use 'raw-oah' instead!",
+                              DeprecationWarning)
             amp, pha = self._get_amp_pha(holo.get_field(data, **self.holo_kw),
                                          which_data="field")
         else:

tests/requirements.txt

@@ -0,0 +1 @@
+pytest

tests/test_core.py

@@ -134,7 +134,7 @@ def test_get_amp_pha_holo():
     kx = -.6
     ky = -.4
     image = np.sin(kx * x + ky * y)
-    qpi = qpimage.QPImage(image, which_data="hologram")
+    qpi = qpimage.QPImage(image, which_data="raw-oah")
     qpi.compute_bg(which_data="phase",
                    fit_offset="fit",
                    fit_profile="tilt",

tests/test_holo.py

@@ -293,7 +293,7 @@ def test_qpimage_holo():
     data = disk_max * ((x - size / 2)**2 + (y - size / 2)**2 < 30**2)
     image = np.sin(kx * x + ky * y + data)
     qpi = qpimage.QPImage(image,
-                          which_data="hologram",
+                          which_data="raw-oah",
                           holo_kw={"filter_name": "gauss"})
     qpi.compute_bg(which_data="phase",
                    fit_offset="fit",