feat: add --check-increase option

news/sort-squeezed-x.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Add ``--check-increase`` option for squeeze morph.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/morph/morph_io.py

@@ -408,7 +408,7 @@ def tabulate_results(multiple_morph_results):
     return tabulated_results
 
 
-def handle_warnings(squeeze_morph):
+def handle_extrapolation_warnings(squeeze_morph):
     if squeeze_morph is not None:
         extrapolation_info = squeeze_morph.extrapolation_info
         is_extrap_low = extrapolation_info["is_extrap_low"]
@@ -443,3 +443,25 @@ def handle_warnings(squeeze_morph):
                 wmsg,
                 UserWarning,
             )
+
+
+def handle_check_increase_warning(squeeze_morph):
+    if squeeze_morph is not None:
+        if squeeze_morph.squeeze_info["monotonic"]:
+            wmsg = None
+        else:
+            overlapping_regions = squeeze_morph.squeeze_info[
+                "overlapping_regions"
+            ]
+            wmsg = (
+                "Warning: The squeeze morph has interpolated your morphed "
+                "function from a non-monotonically increasing grid. "
+                "This can result in strange behavior in the regions "
+                f"{overlapping_regions}. To disable this setting, "
+                "please enable --check-increasing."
+            )
+        if wmsg:
+            warnings.warn(
+                wmsg,
+                UserWarning,
+            )

src/diffpy/morph/morphapp.py

@@ -207,6 +207,16 @@ def custom_error(self, msg):
             "See online documentation for more information."
         ),
     )
+    group.add_option(
+        "--check-increase",
+        action="store_true",
+        dest="check_increase",
+        help=(
+            "Disable squeeze morph to interpolat morphed function "
+            "from a non-monotonically increasing grid."
+        ),
+    )
+
     group.add_option(
         "--smear",
         type="float",
@@ -571,7 +581,7 @@ def single_morph(
                 except ValueError:
                     parser.error(f"{coeff} could not be converted to float.")
         squeeze_poly_deg = len(squeeze_dict_in.keys())
-        squeeze_morph = morphs.MorphSqueeze()
+        squeeze_morph = morphs.MorphSqueeze(check_increase=opts.check_increase)
         chain.append(squeeze_morph)
         config["squeeze"] = squeeze_dict_in
         # config["extrap_index_low"] = None
@@ -701,8 +711,9 @@ def single_morph(
         chain(x_morph, y_morph, x_target, y_target)
 
     # THROW ANY WARNINGS HERE
-    io.handle_warnings(squeeze_morph)
-    io.handle_warnings(shift_morph)
+    io.handle_extrapolation_warnings(squeeze_morph)
+    io.handle_check_increase_warning(squeeze_morph)
+    io.handle_extrapolation_warnings(shift_morph)
 
     # Get Rw for the morph range
     rw = tools.getRw(chain)

src/diffpy/morph/morphpy.py

@@ -51,6 +51,7 @@ def __get_morph_opts__(parser, scale, stretch, smear, plot, **kwargs):
         "reverse",
         "diff",
         "get-diff",
+        "check-increase",
     ]
     opts_to_ignore = ["multiple-morphs", "multiple-targets"]
     for opt in opts_storing_values:

src/diffpy/morph/morphs/morphsqueeze.py

@@ -1,6 +1,7 @@
 """Class MorphSqueeze -- Apply a polynomial to squeeze the morph
 function."""
 
+import numpy
 from numpy.polynomial import Polynomial
 from scipy.interpolate import CubicSpline
 
@@ -68,8 +69,83 @@ class MorphSqueeze(Morph):
     squeeze_cutoff_low = None
     squeeze_cutoff_high = None
 
-    def __init__(self, config=None):
+    def __init__(self, config=None, check_increase=False):
         super().__init__(config)
+        self.check_increase = check_increase
+
+    def _set_squeeze_info(self, x, x_sorted):
+        self.squeeze_info = {"monotonic": True, "overlapping_regions": None}
+        if list(x) != list(x_sorted):
+            if self.check_increase:
+                raise ValueError(
+                    "Error: The polynomial applied by the squeeze morph has "
+                    "resulted in a grid that is no longer strictly increasing"
+                    ", likely due to a convergence issue. A strictly "
+                    "increasing grid is required for diffpy.morph to compute "
+                    "the morphed function through cubic spline interpolation. "
+                    "Here are some suggested methods to resolve this:\n"
+                    "(1) Please decrease the order of your polynomial and "
+                    "try again.\n"
+                    "(2) If you are using initial guesses of all 0, please "
+                    "ensure your objective function only requires a small "
+                    "polynomial squeeze to match your reference. (In other "
+                    "words, there is good agreement between the two functions"
+                    ".)\n"
+                    "(3) If you expect a large polynomial squeeze to be needed"
+                    ", please ensure your initial parameters for the "
+                    "polynomial morph result in good agreement between your "
+                    "reference and objective functions. One way to obtain "
+                    "such parameters is to first apply a --hshift and "
+                    "--stretch morph. Then, use the hshift parameter for a0 "
+                    "and stretch parameter for a1."
+                )
+            else:
+                overlapping_regions = self._get_overlapping_regions(x)
+                self.squeeze_info["monotonic"] = False
+                self.squeeze_info["overlapping_regions"] = overlapping_regions
+
+    def _sort_squeeze(self, x, y):
+        """Sort x,y according to the value of x."""
+        xy = list(zip(x, y))
+        xy_sorted = sorted(xy, key=lambda pair: pair[0])
+        x_sorted, y_sorted = list(zip(*xy_sorted))
+        return x_sorted, y_sorted
+
+    def _get_overlapping_regions(self, x):
+        diffx = numpy.diff(x)
+        monotomic_regions = []
+        monotomic_signs = [numpy.sign(diffx[0])]
+        current_region = [x[0], x[1]]
+        for i in range(1, len(diffx)):
+            if numpy.sign(diffx[i]) == monotomic_signs[-1]:
+                current_region.append(x[i + 1])
+            else:
+                monotomic_regions.append(current_region)
+                monotomic_signs.append(numpy.sign(diffx[i]))
+                current_region = [x[i + 1]]
+        monotomic_regions.append(current_region)
+        overlapping_regions_sign = -1 if x[0] < x[-1] else 1
+        overlapping_regions_x = [
+            monotomic_regions[i]
+            for i in range(len(monotomic_regions))
+            if monotomic_signs[i] == overlapping_regions_sign
+        ]
+        overlapping_regions = [
+            (min(region), max(region)) for region in overlapping_regions_x
+        ]
+        return overlapping_regions
+
+    def _handle_duplicates(self, x, y):
+        """Remove duplicated x and use the mean value of y corresponded
+        to the duplicated x."""
+        unq_x, unq_inv = numpy.unique(x, return_inverse=True)
+        if len(unq_x) == len(x):
+            return x, y
+        else:
+            y_avg = numpy.zeros_like(unq_x)
+            for i in range(len(unq_x)):
+                y_avg[i] = numpy.array(y)[unq_inv == i].mean()
+            return unq_x, y_avg
 
     def morph(self, x_morph, y_morph, x_target, y_target):
         """Apply a polynomial to squeeze the morph function.
@@ -82,9 +158,16 @@ def morph(self, x_morph, y_morph, x_target, y_target):
         coeffs = [self.squeeze[f"a{i}"] for i in range(len(self.squeeze))]
         squeeze_polynomial = Polynomial(coeffs)
         x_squeezed = self.x_morph_in + squeeze_polynomial(self.x_morph_in)
-        self.y_morph_out = CubicSpline(x_squeezed, self.y_morph_in)(
+        x_squeezed_sorted, y_morph_sorted = self._sort_squeeze(
+            x_squeezed, self.y_morph_in
+        )
+        self._set_squeeze_info(x_squeezed, x_squeezed_sorted)
+        x_squeezed_sorted, y_morph_sorted = self._handle_duplicates(
+            x_squeezed_sorted, y_morph_sorted
+        )
+        self.y_morph_out = CubicSpline(x_squeezed_sorted, y_morph_sorted)(
             self.x_morph_in
         )
-        self.set_extrapolation_info(x_squeezed, self.x_morph_in)
+        self.set_extrapolation_info(x_squeezed_sorted, self.x_morph_in)
 
         return self.xyallout

tests/test_morphsqueeze.py

@@ -173,6 +173,94 @@ def test_morphsqueeze_extrapolate(
         single_morph(parser, opts, pargs, stdout_flag=False)
 
 
+@pytest.mark.parametrize(
+    "squeeze_coeffs, x_morph",
+    [
+        ({"a0": -1, "a1": -1, "a2": 2}, np.linspace(-1, 1, 101)),
+    ],
+)
+def test_sort_squeeze_bad(user_filesystem, squeeze_coeffs, x_morph):
+    # call in .py without --check-increase
+    x_target = x_morph
+    y_target = np.sin(x_target)
+    coeffs = [squeeze_coeffs[f"a{i}"] for i in range(len(squeeze_coeffs))]
+    squeeze_polynomial = Polynomial(coeffs)
+    x_squeezed = x_morph + squeeze_polynomial(x_morph)
+    y_morph = np.sin(x_squeezed)
+    morph = MorphSqueeze()
+    morph.squeeze = squeeze_coeffs
+    with pytest.warns() as w:
+        morphpy.morph_arrays(
+            np.array([x_morph, y_morph]).T,
+            np.array([x_target, y_target]).T,
+            squeeze=coeffs,
+            apply=True,
+        )
+    assert len(w) == 1
+    assert w[0].category is UserWarning
+    actual_wmsg = str(w[0].message)
+    expected_wmsg = (
+        "Warning: The squeeze morph has interpolated your morphed "
+        "function from a non-monotonically increasing grid. "
+    )
+    assert expected_wmsg in actual_wmsg
+
+    # call in .py with --check-increase
+    with pytest.raises(ValueError) as excinfo:
+        morphpy.morph_arrays(
+            np.array([x_morph, y_morph]).T,
+            np.array([x_target, y_target]).T,
+            squeeze=coeffs,
+            check_increase=True,
+            apply=True,
+        )
+    actual_emsg = str(excinfo.value)
+    expected_emsg = (
+        "Error: The polynomial applied by the squeeze morph has "
+        "resulted in a grid that is no longer strictly increasing"
+    )
+    assert expected_emsg in actual_emsg
+
+    # call in CLI without --check-increase
+    morph_file, target_file = create_morph_data_file(
+        user_filesystem / "cwd_dir", x_morph, y_morph, x_target, y_target
+    )
+    parser = create_option_parser()
+    (opts, pargs) = parser.parse_args(
+        [
+            "--squeeze",
+            ",".join(map(str, coeffs)),
+            f"{morph_file.as_posix()}",
+            f"{target_file.as_posix()}",
+            "--apply",
+            "-n",
+        ]
+    )
+    with pytest.warns(UserWarning) as w:
+        single_morph(parser, opts, pargs, stdout_flag=False)
+    assert len(w) == 1
+    actual_wmsg = str(w[0].message)
+    assert expected_wmsg in actual_wmsg
+
+    # call in CLI with --check-increase
+    parser = create_option_parser()
+    (opts, pargs) = parser.parse_args(
+        [
+            "--squeeze",
+            ",".join(map(str, coeffs)),
+            f"{morph_file.as_posix()}",
+            f"{target_file.as_posix()}",
+            "--apply",
+            "-n",
+            "--check-increase",
+        ]
+    )
+    with pytest.raises(ValueError) as excinfo:
+        single_morph(parser, opts, pargs, stdout_flag=False)
+    actual_emsg = str(excinfo.value)
+    assert expected_emsg in actual_emsg
+
+
 def create_morph_data_file(
     data_dir_path, x_morph, y_morph, x_target, y_target
 ):