Merge pull request #228 from bobleesj/no-empty-object

Do not allow an empty instance of DiffractionObject - require `xarrays` `yarrays` `xtype`

Author: sbillinge

news/no-empty-object.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* `DiffractionObject` requires 3 input parameters of `xarray`, `yarray`, `xtype`, to be instantiated.  It can be instantiated with empty arrays.
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/utils/diffraction_objects.py

@@ -35,27 +35,84 @@ def _setter_wmsg(attribute):
 
 
 class DiffractionObject:
+    """
+    Initialize a DiffractionObject instance.
+
+    Parameters
+    ----------
+    xarray : array-like
+        The independent variable array containing "q", "tth", or "d" values.
+    yarray : array-like
+        The dependent variable array corresponding to intensity values.
+    xtype : str
+        The type of the independent variable in `xarray`. Must be one of {*XQUANTITIES}.
+    wavelength : float, optional
+        The wavelength of the incoming beam, specified in angstroms (Å). Default is none.
+    scat_quantity : str, optional
+        The type of scattering experiment (e.g., "x-ray", "neutron"). Default is an empty string "".
+    name : str, optional
+        The name or label for the scattering data. Default is an empty string "".
+    metadata : dict, optional
+        The additional metadata associated with the diffraction object. Default is {}.
+
+    Examples
+    --------
+    Create a DiffractionObject for X-ray scattering data:
+
+    >>> import numpy as np
+    >>> from diffpy.utils.diffraction_objects import DiffractionObject
+    ...
+    >>> x = np.array([0.12, 0.24, 0.31, 0.4])  # independent variable (e.g., q)
+    >>> y = np.array([10, 20, 40, 60])  # intensity values
+    >>> metadata = {
+    ...     "sample": "rock salt from the beach",
+    ...     "composition": "NaCl",
+    ...     "temperature": "300 K,",
+    ...     "experimenters": "Phill, Sally"
+    ... }
+    >>> do = DiffractionObject(
+    ...     xarray=x,
+    ...     yarray=y,
+    ...     xtype="q",
+    ...     wavelength=1.54,
+    ...     scat_quantity="x-ray",
+    ...     name="beach_rock_salt_1",
+    ...     metadata=metadata
+    ... )
+    >>> print(do.metadata)
+    """
+
     def __init__(
-        self, name=None, wavelength=None, scat_quantity=None, metadata=None, xarray=None, yarray=None, xtype=None
+        self,
+        xarray,
+        yarray,
+        xtype,
+        wavelength=None,
+        scat_quantity="",
+        name="",
+        metadata={},
     ):
-        if name is None:
-            name = ""
-        self.name = name
-        if metadata is None:
-            metadata = {}
-        self.metadata = metadata
-        if xtype is None:
-            xtype = ""
-        self.scat_quantity = scat_quantity
-        self.wavelength = wavelength
-
-        if xarray is None:
-            xarray = np.empty(0)
-        if yarray is None:
-            yarray = np.empty(0)
 
         self._id = uuid.uuid4()
-        self.input_data(xarray, yarray, xtype)
+        self._input_data(xarray, yarray, xtype, wavelength, scat_quantity, name, metadata)
+
+    def _input_data(self, xarray, yarray, xtype, wavelength, scat_quantity, name, metadata):
+        if xtype not in XQUANTITIES:
+            raise ValueError(_xtype_wmsg(xtype))
+        if len(xarray) != len(yarray):
+            raise ValueError(
+                "'xarray' and 'yarray' are different lengths.  They must "
+                "correspond to each other and have the same length. "
+                "Please re-initialize 'DiffractionObject'"
+                "with valid 'xarray' and 'yarray's"
+            )
+        self.scat_quantity = scat_quantity
+        self.wavelength = wavelength
+        self.metadata = metadata
+        self.name = name
+        self._input_xtype = xtype
+        self._set_arrays(xarray, yarray, xtype)
+        self._set_min_max_xarray()
 
     def __eq__(self, other):
         if not isinstance(other, DiffractionObject):
@@ -231,16 +288,16 @@ def get_array_index(self, value, xtype=None):
         the index of the value in the array
         """
 
-        if xtype is None:
-            xtype = self._input_xtype
+        xtype = self._input_xtype
         array = self.on_xtype(xtype)[0]
         if len(array) == 0:
             raise ValueError(f"The '{xtype}' array is empty. Please ensure it is initialized.")
         i = (np.abs(array - value)).argmin()
         return i
 
-    def _set_xarrays(self, xarray, xtype):
+    def _set_arrays(self, xarray, yarray, xtype):
         self._all_arrays = np.empty(shape=(len(xarray), 4))
+        self._all_arrays[:, 0] = yarray
         if xtype.lower() in QQUANTITIES:
             self._all_arrays[:, 1] = xarray
             self._all_arrays[:, 2] = q_to_tth(xarray, self.wavelength)
@@ -253,70 +310,15 @@ def _set_xarrays(self, xarray, xtype):
             self._all_arrays[:, 3] = xarray
             self._all_arrays[:, 1] = d_to_q(xarray)
             self._all_arrays[:, 2] = d_to_tth(xarray, self.wavelength)
+
+    def _set_min_max_xarray(self):
         self.qmin = np.nanmin(self._all_arrays[:, 1], initial=np.inf)
         self.qmax = np.nanmax(self._all_arrays[:, 1], initial=0.0)
         self.tthmin = np.nanmin(self._all_arrays[:, 2], initial=np.inf)
         self.tthmax = np.nanmax(self._all_arrays[:, 2], initial=0.0)
         self.dmin = np.nanmin(self._all_arrays[:, 3], initial=np.inf)
         self.dmax = np.nanmax(self._all_arrays[:, 3], initial=0.0)
 
-    def input_data(
-        self,
-        xarray,
-        yarray,
-        xtype,
-        metadata={},
-        scat_quantity=None,
-        name=None,
-        wavelength=None,
-    ):
-        f"""
-        insert a new scattering quantity into the scattering object
-
-        Parameters
-        ----------
-        xarray array-like of floats
-          the independent variable array
-        yarray array-like of floats
-          the dependent variable array
-        xtype string
-          the type of quantity for the independent variable from {*XQUANTITIES, }
-        metadata, scat_quantity, name and wavelength are optional.  They have the same
-        meaning as in the constructor. Values will only be overwritten if non-empty values are passed.
-
-        Returns
-        -------
-        Nothing.  Updates the object in place.
-
-        """
-
-        # Check xarray and yarray have the same length
-        if len(xarray) != len(yarray):
-            raise ValueError(
-                "'xarray' and 'yarray' must have the same length. "
-                "Please re-initialize 'DiffractionObject' or re-run the method 'input_data' "
-                "with 'xarray' and 'yarray' of identical length."
-            )
-
-        self._set_xarrays(xarray, xtype)
-        self._all_arrays[:, 0] = yarray
-        self._input_xtype = xtype
-        # only update these optional values if non-empty quantities are passed to avoid overwriting
-        # valid data inadvertently
-        if metadata:
-            self.metadata = metadata
-        if scat_quantity is not None:
-            self.scat_quantity = scat_quantity
-        if name is not None:
-            self.name = name
-        if wavelength is not None:
-            self.wavelength = wavelength
-
-        # Check xtype is valid. An empty string is the default value.
-        if xtype != "":
-            if xtype not in XQUANTITIES:
-                raise ValueError(_xtype_wmsg(xtype))
-
     def _get_original_array(self):
         if self._input_xtype in QQUANTITIES:
             return self.on_q(), "q"

tests/conftest.py

@@ -33,6 +33,13 @@ def _load(filename):
     return _load
 
 
+@pytest.fixture
+def do_minimal():
+    # Create an instance of DiffractionObject with empty xarray and yarray values, and a non-empty wavelength
+    return DiffractionObject(xarray=np.empty(0), yarray=np.empty(0), xtype="tth", wavelength=1.54)
+
+
 @pytest.fixture
 def do_minimal_tth():
+    # Create an instance of DiffractionObject with non-empty xarray, yarray, and wavelength values
     return DiffractionObject(wavelength=2 * np.pi, xarray=np.array([30, 60]), yarray=np.array([1, 2]), xtype="tth")