fix rabit comment, add support for percentages

d-chambers · d-chambers · commit 3698adcf8add · 2025-10-28T09:46:34.000Z
diff --git a/dascore/proc/taper.py b/dascore/proc/taper.py
@@ -277,7 +277,6 @@ def taper_range(
     >>> # Apply two non-overlapping tapers
     >>> taper_range = ((25,50,100,125), (150,175,200,225))
     >>> patch_tapered_5 = patch.taper_range(distance=taper_range)
-
     """
     dim, ax, values = get_dim_axis_value(patch, kwargs=kwargs)[0]
     coord = patch.get_coord(dim, require_sorted=True)
diff --git a/dascore/units.py b/dascore/units.py
@@ -14,7 +14,7 @@
 import dascore as dc
 from dascore.compat import is_array
 from dascore.exceptions import UnitError
-from dascore.utils.misc import unbyte
+from dascore.utils.misc import iterate, unbyte
 from dascore.utils.time import dtype_time_like, is_datetime64, is_timedelta64, to_float
 
 str_or_none = TypeVar("str_or_none", None, str)
@@ -357,6 +357,60 @@ def quant_sequence_to_quant_array(sequence: Sequence[Quantity]) -> Quantity:
     return array * next(iter(units))
 
 
+def maybe_convert_percent_to_fraction(obj):
+    """
+    Iterate an object and convert any percentages to fractions.
+
+    Parameters
+    ----------
+    obj
+        The input object. Can be a single value or an iterable.
+
+    Returns
+    -------
+    list
+        A list where any percentage quantities are converted to their
+        fractional equivalents (e.g., 50% becomes 0.5).
+
+    Examples
+    --------
+    >>> from dascore.units import maybe_convert_percent_to_fraction, get_quantity
+    >>>
+    >>> # Convert a single percentage to fraction
+    >>> result = maybe_convert_percent_to_fraction(get_quantity("50%"))
+    >>> assert result == [0.5]
+    >>>
+    >>> # Convert a list with percentages
+    >>> result = maybe_convert_percent_to_fraction(
+    ...     [get_quantity("25%"), get_quantity("75%")]
+    ... )
+    >>> assert result == [0.25, 0.75]
+    >>>
+    >>> # Non-percentage values are unchanged
+    >>> result = maybe_convert_percent_to_fraction([get_quantity("10 m"), 5])
+    >>> assert result[0] == get_quantity("10 m")
+    >>> assert result[1] == 5
+    >>>
+    >>> # Mixed values
+    >>> result = maybe_convert_percent_to_fraction(
+    ...     [get_quantity("100%"), 0.5, get_quantity("2 Hz")]
+    ... )
+    >>> assert result[0] == 1.0
+    >>> assert result[1] == 0.5
+    >>> assert result[2] == get_quantity("2 Hz")
+    """
+    percent = get_unit("percent")
+    out = []
+    obj = [obj] if isinstance(obj, Quantity | Unit) and obj.ndim == 0 else obj
+    for val in iterate(obj):
+        if hasattr(val, "units"):
+            mag, unit = val.magnitude, val.units
+            if unit == percent:
+                val = mag / 100
+        out.append(val)
+    return out
+
+
 def __getattr__(name):
     """
     Allows arbitrary units (quantities) to be imported from this module.
diff --git a/dascore/viz/waterfall.py b/dascore/viz/waterfall.py
@@ -10,7 +10,7 @@
 
 from dascore.constants import PatchType
 from dascore.exceptions import ParameterError
-from dascore.units import get_quantity_str
+from dascore.units import get_quantity_str, maybe_convert_percent_to_fraction
 from dascore.utils.patch import patch_function
 from dascore.utils.plotting import (
     _format_time_axis,
@@ -51,23 +51,25 @@ def _get_scale(scale, scale_type, data):
     Calculate the color bar scale limits based on scale and scale_type.
     """
     _validate_scale_type(scale_type)
-
+    # This ensures we have a list of the previous scale parameters.
+    scale = maybe_convert_percent_to_fraction(scale)
     match (scale, scale_type):
         # Case 1: Single value with relative scaling
         # Scale is symmetric around the mean, using fraction of dynamic range
-        case (scale, "relative") if isinstance(scale, float | int):
+        case (scale, "relative") if len(scale) == 1:
+            scale = scale[0]
             mod = 0.5 * (np.nanmax(data) - np.nanmin(data))
             mean = np.nanmean(data)
             scale = np.asarray([mean - scale * mod, mean + scale * mod])
         # Case 2: No scale specified with relative scaling
         # Use Tukey's fence (C*IQR, C is normally 1.5) to exclude outliers.
         # This prevents a few extreme values from obscuring the majority of the
         # data at the cost of a slight performance penalty.
-        case (None, "relative"):
-            q2, q3 = np.nanpercentile(data, [25, 75])
+        case ([], "relative"):
+            q1, q3 = np.nanpercentile(data, [25, 75])
             dmin, dmax = np.nanmin(data), np.nanmax(data)
-            diff = q3 - q2  # Interquartile range (IQR)
-            q_lower = np.nanmax([q2 - diff * IQR_FENCE_MULTIPLIER, dmin])
+            diff = q3 - q1  # Interquartile range (IQR)
+            q_lower = np.nanmax([q1 - diff * IQR_FENCE_MULTIPLIER, dmin])
             q_upper = np.nanmin([q3 + diff * IQR_FENCE_MULTIPLIER, dmax])
             scale = np.asarray([q_lower, q_upper])
             return scale
@@ -88,8 +90,8 @@ def _get_scale(scale, scale_type, data):
             # Map [0, 1] to [data_min, data_max]
             scale = dmin + scale * data_range
         # Case 4: Absolute scaling
-        case (scale, "absolute") if isinstance(scale, int | float):
-            scale = np.array([-abs(scale), abs(scale)])
+        case (scale, "absolute") if len(scale) == 1:
+            scale = np.array([-abs(scale[0]), abs(scale[0])])
         # Case 5: Absolute scaling with sequence: no match needed.
 
     # Scale values are used directly as colorbar limits
@@ -168,13 +170,16 @@ def waterfall(
     --------
     >>> # Plot with default scaling (uses 1.5*IQR fence to exclude outliers)
     >>> import dascore as dc
+    >>> from dascore.units import percent
     >>> patch = dc.get_example_patch("example_event_1").normalize("time")
     >>> _ = patch.viz.waterfall()
     >>>
-    >>> # Use relative scaling with a float to saturate at 10% of dynamic range
-    >>> # This centers the colorbar around the mean and extends ±10% of the
-    >>> # data's dynamic range in each direction
+    >>> # Use relative scaling with a tuple to show a specific fraction
+    >>> # of data range. Scale values of (0.1, 0.9) map to 10% and 90%
+    >>> # of the [data_min, data_max] range data's dynamic range
     >>> _ = patch.viz.waterfall(scale=0.1, scale_type="relative")
+    >>> # Likewise, percent units can be used for additional clarity
+    >>> _ = patch.viz.waterfall(scale=10*percent, scale_type="absolute")
     >>>
     >>> # Use relative scaling with a tuple to show the middle 80% of data range
     >>> # Scale values of (0.1, 0.9) map to 10th and 90th percentile of data
@@ -218,15 +223,13 @@ def waterfall(
     """
     # Validate inputs
     patch = _validate_patch_dims(patch)
-
     # Setup axes and data
     ax = _get_ax(ax)
     cmap = _get_cmap(cmap)
     data = np.log10(np.absolute(patch.data)) if log else patch.data
     dims = patch.dims
     dims_r = tuple(reversed(dims))
     coords = {dim: patch.coords.get_array(dim) for dim in dims}
-
     # Plot using imshow and set colorbar limits
     extents = _get_extents(dims_r, coords)
     scale = _get_scale(scale, scale_type, data)
@@ -244,14 +247,11 @@ def waterfall(
         interpolation_stage="data",
     )
     im.set_clim(scale)
-
     # Format axis labels and handle time-like dimensions
     _format_axis_labels(ax, patch, dims_r)
-
     # Add colorbar if requested
     if cmap is not None:
         _add_colorbar(ax, im, patch, log)
-
     if show:
         plt.show()
     return ax
diff --git a/tests/test_units.py b/tests/test_units.py
@@ -17,6 +17,7 @@
     get_quantity_str,
     get_unit,
     invert_quantity,
+    maybe_convert_percent_to_fraction,
     quant_sequence_to_quant_array,
 )
 
@@ -353,3 +354,66 @@ def test_numpy_array_input(self):
         sequence = np.array([1, 2, 3])
         out = quant_sequence_to_quant_array(sequence)
         assert isinstance(out, Quantity)
+
+
+class TestMaybeConvertPercentToFraction:
+    """Tests for converting percentages to fractions."""
+
+    def test_single_percentage(self):
+        """Test converting a single percentage value."""
+        result = maybe_convert_percent_to_fraction(get_quantity("50%"))
+        assert len(result) == 1
+        assert result[0] == 0.5
+
+    def test_list_of_percentages(self):
+        """Test converting a list of percentages."""
+        result = maybe_convert_percent_to_fraction(
+            [get_quantity("25%"), get_quantity("75%"), get_quantity("100%")]
+        )
+        assert len(result) == 3
+        assert result[0] == 0.25
+        assert result[1] == 0.75
+        assert result[2] == 1.0
+
+    def test_non_percentage_quantity_unchanged(self):
+        """Test that non-percentage quantities remain unchanged."""
+        meter = get_quantity("10 m")
+        hz = get_quantity("5 Hz")
+        result = maybe_convert_percent_to_fraction([meter, hz])
+        assert len(result) == 2
+        assert result[0] == meter
+        assert result[1] == hz
+
+    def test_plain_numeric_values(self):
+        """Test that plain numeric values without units are unchanged."""
+        result = maybe_convert_percent_to_fraction([1, 2.5, 0])
+        assert result == [1, 2.5, 0]
+
+    def test_mixed_values(self):
+        """Test a mix of percentages, quantities, and plain values."""
+        percent_val = get_quantity("50%")
+        meter_val = get_quantity("10 m")
+        plain_val = 0.5
+        result = maybe_convert_percent_to_fraction([percent_val, plain_val, meter_val])
+        assert len(result) == 3
+        assert result[0] == 0.5  # 50% converted to fraction
+        assert result[1] == 0.5  # plain value unchanged
+        assert result[2] == meter_val  # quantity unchanged
+
+    def test_zero_percent(self):
+        """Test that 0% converts correctly."""
+        result = maybe_convert_percent_to_fraction(get_quantity("0%"))
+        assert len(result) == 1
+        assert result[0] == 0.0
+
+    def test_large_percentage(self):
+        """Test that percentages over 100% convert correctly."""
+        result = maybe_convert_percent_to_fraction(get_quantity("250%"))
+        assert len(result) == 1
+        assert result[0] == 2.5
+
+    def test_fractional_percentage(self):
+        """Test that fractional percentages convert correctly."""
+        result = maybe_convert_percent_to_fraction(get_quantity("12.5%"))
+        assert len(result) == 1
+        assert np.isclose(result[0], 0.125)
diff --git a/tests/test_viz/test_waterfall.py b/tests/test_viz/test_waterfall.py
@@ -233,3 +233,6 @@ def test_constant_patch(self, random_patch):
         patch = random_patch.update(data=data)
         ax = patch.viz.waterfall()
         assert isinstance(ax, plt.Axes)
+
+    def test_precent_scale(self, random_patch):
+        """Ensure the percent unit works with scale."""
