Steps tendency

docs/source/tendencies.rst

@@ -18,7 +18,8 @@ Most tendencies accept the following parameters to define their time interval. Y
 *   ``end``: The absolute time at which the tendency ends. If omitted, it's calculated from ``start + duration``.
 
 .. note::
-    The :ref:`Piecewise Linear Tendency <piecewise-linear-tendency>` is an exception and derives its time interval solely from its ``time`` parameter list. It does *not* accept ``start``, ``duration``, or ``end``.
+    The :ref:`Piecewise Linear Tendency <piecewise-linear-tendency>` and :ref:`Steps <steps-tendency>` are an exception, they derive their time interval solely from the ``time`` parameter list. 
+    These tendencies do *not* accept ``start``, ``duration``, or ``end``.
 
 Constant Tendency
 =================
@@ -212,7 +213,7 @@ Defines a sequence of points connected by straight lines.
 
 Parameters
 ----------
-*   ``time``: A list of time points. Must be strictly monotonically increasing and must have at least 1 point.
+*   ``time``: A list of the tendency's time points. The time points are absolute, and must be strictly monotonically increasing and must have at least 1 point.
 *   ``value``: A list of corresponding values at each time point in the ``time`` list. Must have the same length as ``time``.
 
 .. image:: images/piecewise.png
@@ -227,6 +228,43 @@ Parameters
 .. warning::
     This tendency does **not** accept the common ``start``, ``duration``, or ``end`` parameters. These are derived directly from the required ``time`` list.
 
+.. _steps-tendency:
+
+Steps Tendency
+==============
+
+Defines a sequence of steps, each held constant from its time point until the next one.
+``time`` and ``value`` must have the same length. This is a compact
+alternative to writing out a sequence of :ref:`Constant Tendencies <constant-value-types>`.
+
+Parameters
+----------
+*   ``time``: A list of the tendency's time points. The time points are absolute, and must be strictly monotonically increasing and must have at least 1 point.
+*   ``value``: A list of the values held during each step. Must have the same length as ``time``.
+
+.. image:: images/steps_1.png
+   :alt: Example plot of a Steps Tendency
+   :width: 400px
+   :align: center
+
+.. code-block:: yaml
+
+    - {type: steps, time: [0, 2, 4, 6], value: [1, 3, 5, 5]}
+
+Just like the :ref:`Constant Tendency <constant-value-types>`, the ``value`` list may contain numbers or strings:
+
+.. image:: images/steps_2.png
+   :alt: Example plot of a Steps Tendency containing string values
+   :width: 400px
+   :align: center
+
+.. code-block:: yaml
+
+    - {type: steps, time: [0, 10, 20, 30], value: [ohmic, nbi, ec, ec]}
+
+.. warning::
+    This tendency does **not** accept the common ``start``, ``duration``, or ``end`` parameters. These are derived directly from the required ``time`` list.
+
 Periodic Tendencies
 ===================
 

tests/tendencies/test_piecewise.py → tests/tendencies/points/test_piecewise.py

@@ -1,7 +1,7 @@
 import numpy as np
 from pytest import approx
 
-from waveform_editor.tendencies.piecewise import PiecewiseLinearTendency
+from waveform_editor.tendencies.points.piecewise import PiecewiseLinearTendency
 
 
 def test_empty():

tests/tendencies/points/test_points_base.py

@@ -0,0 +1,104 @@
+from unittest.mock import patch
+
+import numpy as np
+import pytest
+
+from waveform_editor.tendencies.points.points_base import PointsBaseTendency
+
+
+@pytest.fixture(autouse=True)
+def patch_points_base_tendency():
+    arr = np.array([0.0])
+    with (
+        patch.object(PointsBaseTendency, "get_value", return_value=(arr, arr)),
+        patch.object(PointsBaseTendency, "get_derivative", return_value=arr),
+    ):
+        yield
+
+
+def test_empty():
+    """Test empty tendency."""
+    tendency = PointsBaseTendency()
+    assert tendency.annotations
+
+    tendency = PointsBaseTendency(user_time=[1, 2, 3])
+    assert tendency.annotations
+
+    tendency = PointsBaseTendency(user_value=[1, 2, 3])
+    assert tendency.annotations
+
+
+def test_filled():
+    """Test value of filled tendency."""
+    tendency = PointsBaseTendency(user_time=[1, 2, 3], user_value=[2, 4, 6])
+    assert np.all(tendency.time == np.array([1, 2, 3]))
+    assert np.all(tendency.value == np.array([2, 4, 6]))
+    assert tendency.value_type is float
+    assert tendency.start == 1
+    assert tendency.end == 3
+    assert not tendency.annotations
+
+
+def test_filled_invalid():
+    """Test value of filled tendency with invalid parameters."""
+    # Not monotonically increasing
+    tendency = PointsBaseTendency(
+        user_time=np.array([3, 2, 1]), user_value=np.array([1, 2, 3])
+    )
+    assert tendency.annotations
+
+    # Mismatched lengths
+    tendency = PointsBaseTendency(
+        user_time=np.array([1, 2]), user_value=np.array([1, 2, 3])
+    )
+    assert tendency.annotations
+
+    # Not strictly increasing (repeated time point)
+    tendency = PointsBaseTendency(
+        user_time=np.array([1, 1, 2]), user_value=np.array([1, 2, 3])
+    )
+    assert tendency.annotations
+
+    # Empty arrays
+    tendency = PointsBaseTendency(user_time=[], user_value=[])
+    assert tendency.annotations
+
+    # Non-finite value
+    tendency = PointsBaseTendency(user_time=[1, 2, 3], user_value=[1, float("inf"), 3])
+    assert tendency.annotations
+
+
+def test_start_duration_end_not_allowed():
+    """Test that `start`, `duration`, and `end` may not be provided; they are always
+    derived from `time[0]`/`time[-1]`."""
+    tendency = PointsBaseTendency(
+        user_time=[1, 2, 3], user_value=[1, 2, 3], user_start=1
+    )
+    assert tendency.annotations
+
+    tendency = PointsBaseTendency(
+        user_time=[1, 2, 3], user_value=[1, 2, 3], user_duration=2
+    )
+    assert tendency.annotations
+
+    tendency = PointsBaseTendency(user_time=[1, 2, 3], user_value=[1, 2, 3], user_end=3)
+    assert tendency.annotations
+
+    tendency = PointsBaseTendency(
+        user_time=[1, 2, 3],
+        user_value=[1, 2, 3],
+        user_start=1,
+        user_duration=2,
+        user_end=3,
+    )
+    assert tendency.annotations
+
+
+def test_single_point():
+    """Test that a single time/value point is allowed (a zero-duration tendency)."""
+    tendency = PointsBaseTendency(user_time=[1.1], user_value=[9.9])
+    assert tendency.time == np.array([1.1])
+    assert tendency.value == np.array([9.9])
+    assert tendency.start == 1.1
+    assert tendency.end == 1.1
+    assert not tendency.annotations

tests/tendencies/points/test_steps.py

@@ -0,0 +1,164 @@
+import numpy as np
+import pytest
+
+from waveform_editor.tendencies.points.steps import StepsTendency
+
+
+def test_empty():
+    """Test empty tendency."""
+    tendency = StepsTendency()
+    assert tendency.annotations
+
+    tendency = StepsTendency(user_time=[0, 2, 4])
+    assert tendency.annotations
+
+    tendency = StepsTendency(user_value=[1, 2, 3])
+    assert tendency.annotations
+
+
+def test_filled():
+    """Test value of a filled tendency."""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 5])
+    assert np.all(tendency.time == np.array([0, 2, 4, 6]))
+    assert list(tendency.value) == [1, 3, 5, 5]
+    assert tendency.value_type is int
+    assert tendency.start == 0
+    assert tendency.end == 6
+    assert not tendency.annotations
+
+
+def test_string_values():
+    """Test a tendency with string values."""
+    tendency = StepsTendency(
+        user_time=[0, 10, 20, 30], user_value=["ohmic", "nbi", "ec", "ec"]
+    )
+    assert list(tendency.value) == ["ohmic", "nbi", "ec", "ec"]
+    assert tendency.value_type is str
+    assert not tendency.annotations
+
+    _, values = tendency.get_value(np.array([0, 5, 10, 15, 20, 25, 30]))
+    assert list(values) == ["ohmic", "ohmic", "nbi", "nbi", "ec", "ec", "ec"]
+
+
+def test_int_float_mixing():
+    """Test that mixing int and float values in a single steps tendency"""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 2.5, 3, 3])
+    assert tendency.value_type is float
+    assert not tendency.annotations
+
+
+def test_mixed_value_types_not_supported():
+    """Test that mixing string and numerical values is not allowed."""
+    tendency = StepsTendency(user_time=[0, 10], user_value=[1, "ec"])
+    assert tendency.annotations
+
+
+def test_unsupported_value_type():
+    """Test that a value which is not an int, float, or str is not supported."""
+    tendency = StepsTendency(user_time=[0, 10], user_value=[1, [2, 3]])
+    assert tendency.annotations
+
+
+def test_duration_not_allowed():
+    """Test that `duration` may not be provided; `end` is always `time[-1]`."""
+    tendency = StepsTendency(user_time=[0, 10], user_value=[1, 2], user_duration=20)
+    assert tendency.annotations
+
+
+def test_end_not_allowed():
+    """Test that `end` may not be provided; it is always `time[-1]`."""
+    tendency = StepsTendency(user_time=[0, 10], user_value=[1, 2], user_end=20)
+    assert tendency.annotations
+
+
+def test_start_not_allowed():
+    """Test that `start` may not be provided; it is always `time[0]`."""
+    tendency = StepsTendency(user_time=[0, 10], user_value=[1, 2], user_start=5)
+    assert tendency.annotations
+
+
+def test_mismatched_lengths():
+    """Test that time and value arrays must have the same length."""
+    tendency = StepsTendency(user_time=[0, 10, 20], user_value=[1, 2])
+    assert tendency.annotations
+
+
+def test_empty_arrays():
+    """Test that time and value arrays must contain at least one element."""
+    tendency = StepsTendency(user_time=[], user_value=[])
+    assert tendency.annotations
+
+
+def test_non_monotonic_time():
+    """Test that the time array must be monotonically increasing."""
+    tendency = StepsTendency(user_time=[0, 10, 5], user_value=[1, 2, 3])
+    assert tendency.annotations
+
+    tendency = StepsTendency(user_time=[0, 10, 10], user_value=[1, 2, 3])
+    assert tendency.annotations
+
+
+def test_start_and_end_values():
+    """Test the start and end values and their derivatives."""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 5])
+    assert tendency.start_value == 1
+    assert tendency.end_value == 5
+    assert tendency.start_derivative == 0
+    assert tendency.end_derivative == 0
+    assert not tendency.annotations
+
+
+def test_generate():
+    """Check the generated values."""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 5])
+    time, values = tendency.get_value()
+    assert np.all(time == [0, 2, 2, 4, 4, 6, 6])
+    assert list(values) == [1, 1, 3, 3, 5, 5, 5]
+    assert not tendency.annotations
+
+
+def test_last_value():
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 7])
+    assert not tendency.annotations
+    assert tendency.end_value == 7
+
+    time, values = tendency.get_value()
+    assert np.all(time == [0, 2, 2, 4, 4, 6, 6])
+    assert list(values) == [1, 1, 3, 3, 5, 5, 7]
+
+    _, values = tendency.get_value(np.array([5.999, 6]))
+    assert list(values) == [5, 7]
+
+
+def test_get_value_at_times():
+    """Check the value assignment at arbitrary time points."""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 5])
+    _, values = tendency.get_value(np.array([0, 1, 1.99, 2, 3, 4, 5, 6]))
+    assert list(values) == [1, 1, 1, 3, 3, 5, 5, 5]
+
+
+def test_get_value_outside_bounds():
+    """Check the generated values outside of the time array"""
+    tendency = StepsTendency(user_time=[1, 2, 3, 4], user_value=[2, 4, 8, 8])
+    _, values = tendency.get_value(np.array([-1, 0, 4.5, 5]))
+    assert list(values) == [2, 2, 8, 8]
+
+    tendency = StepsTendency(user_time=[1, 2, 3, 4], user_value=[2, 4, 8, 10])
+    _, values = tendency.get_value(np.array([-1, 0, 4.5, 5]))
+    assert list(values) == [2, 2, 10, 10]
+
+
+def test_get_derivative():
+    """Check that the derivative is always zero."""
+    tendency = StepsTendency(user_time=[0, 2, 4, 6], user_value=[1, 3, 5, 5])
+    derivatives = tendency.get_derivative(np.array([0, 1, 2, 3, 4, 5, 6]))
+    assert np.all(derivatives == 0)
+
+
+@pytest.mark.parametrize("value", [[1, 2, 3], [1.5, 2.5, 3.5], ["a", "b", "c"]])
+def test_value_types(value):
+    """Test that int, float, and str steps are all supported."""
+    tendency = StepsTendency(user_time=[0, 2, 4], user_value=value)
+    assert not tendency.annotations
+    assert tendency.value_type is type(value[0])
+    assert list(tendency.value) == value