Add log_to_attrs decorator to scale function (#604)

* added log_to_attrs decorator to scale function and documented its effects

* adapted tests for the scale function

* fixed mistakes in docstring formatting

* use monospace consistently in docstring

* updated docstring to follow new log style

* adapt tests for the serialized attrs.log

* more specific name for test helper function

---------

Co-authored-by: Adam Tyson <[email protected]>

Author: niksirbi

movement/transforms.py

@@ -4,9 +4,11 @@
 import xarray as xr
 from numpy.typing import ArrayLike
 
+from movement.utils.logging import log_to_attrs
 from movement.validators.arrays import validate_dims_coords
 
 
+@log_to_attrs
 def scale(
     data: xr.DataArray,
     factor: ArrayLike | float = 1.0,
@@ -27,8 +29,8 @@ def scale(
         broadcasted.
     space_unit : str or None
         The unit of the scaled data stored as a property in
-        xarray.DataArray.attrs['space_unit']. In case of the default (``None``)
-        the ``space_unit`` attribute is dropped.
+        ``xarray.DataArray.attrs['space_unit']``. In case of the default
+        (``None``) the ``space_unit`` attribute is dropped.
 
     Returns
     -------
@@ -37,9 +39,50 @@ def scale(
 
     Notes
     -----
-    When scale is used multiple times on the same xarray.DataArray,
-    xarray.DataArray.attrs["space_unit"] is overwritten each time or is dropped
-    if ``None`` is passed by default or explicitly.
+    This function makes two changes to the resulting data array's attributes
+    (``xarray.DataArray.attrs``) each time it is called:
+
+    - It sets the ``space_unit`` attribute to the value of the parameter
+      with the same name, or removes it if ``space_unit=None``.
+    - It adds a new entry to the ``log`` attribute of the data array, which
+      contains a record of the operations performed, including the
+      parameters used, as well as the datetime of the function call.
+
+    Examples
+    --------
+    Let's imagine a camera viewing a 2D plane from the top, with an
+    estimated resolution of 10 pixels per cm. We can scale down
+    position data by a factor of 1/10 to express it in cm units.
+
+    >>> from movement.transforms import scale
+    >>> ds["position"] = scale(ds["position"], factor=1 / 10, space_unit="cm")
+    >>> print(ds["position"].space_unit)
+    cm
+    >>> print(ds["position"].log)
+    [
+        {
+            "operation": "scale",
+            "datetime": "2025-06-05 15:08:16.919947",
+            "factor": "0.1",
+            "space_unit": "'cm'"
+        }
+    ]
+
+    Note that the attributes of the scaled data array now contain the assigned
+    ``space_unit`` as well as a ``log`` entry with the arguments passed to
+    the function.
+
+    We can also scale the two spatial dimensions by different factors.
+
+    >>> ds["position"] = scale(ds["position"], factor=[10, 20])
+
+    The second scale operation restored the x axis to its original scale,
+    and scaled up the y axis to twice its original size.
+    The log will now contain two entries, but the ``space_unit`` attribute
+    has been removed, as it was not provided in the second function call.
+
+    >>> "space_unit" in ds["position"].attrs
+    False
 
     """
     if len(data.coords["space"]) == 2:

tests/test_unit/test_transforms.py

@@ -1,3 +1,4 @@
+import json
 from typing import Any
 
 import numpy as np
@@ -32,6 +33,16 @@ def data_array_with_dims_and_coords(
     )
 
 
+def drop_attrs_log(attrs: dict) -> dict:
+    """Drop the log string from attrs to faclitate testing.
+    The log string will never exactly match, because datetimes differ.
+    """
+    attrs_copy = attrs.copy()
+    if "log" in attrs:
+        attrs_copy.pop("log", None)
+    return attrs_copy
+
+
 @pytest.fixture
 def sample_data_2d() -> xr.DataArray:
     """Turn the nparray_0_to_23 into a DataArray."""
@@ -103,7 +114,7 @@ def test_scale(
     """Test scaling with different factors and space_units."""
     scaled_data = scale(sample_data_2d, **optional_arguments)
     xr.testing.assert_equal(scaled_data, expected_output)
-    assert scaled_data.attrs == expected_output.attrs
+    assert drop_attrs_log(scaled_data.attrs) == expected_output.attrs
 
 
 @pytest.mark.parametrize(
@@ -180,7 +191,7 @@ def test_scale_twice(
         **optional_arguments_2,
     )
     xr.testing.assert_equal(output_data_array, expected_output)
-    assert output_data_array.attrs == expected_output.attrs
+    assert drop_attrs_log(output_data_array.attrs) == expected_output.attrs
 
 
 @pytest.mark.parametrize(
@@ -241,3 +252,30 @@ def test_scale_invalid_3d_space(factor):
     assert str(error.value) == (
         "Input data must contain ['z'] in the 'space' coordinates.\n"
     )
+
+
+def test_scale_log(sample_data_2d: xr.DataArray):
+    """Test that the log attribute is correctly populated
+    in the scaled data array.
+    """
+
+    def verify_log_entry(entry, expected_factor, expected_space_unit):
+        """Verify each scale log entry."""
+        assert entry["factor"] == expected_factor
+        assert entry["space_unit"] == expected_space_unit
+        assert entry["operation"] == "scale"
+        assert "datetime" in entry
+
+    # scale data twice
+    scaled_data = scale(
+        scale(sample_data_2d, factor=2, space_unit="elephants"),
+        factor=[1, 2],
+        space_unit="crabs",
+    )
+
+    # verify the log attribute
+    assert "log" in scaled_data.attrs
+    log_entries = json.loads(scaled_data.attrs["log"])
+    assert len(log_entries) == 2
+    verify_log_entry(log_entries[0], "2", "'elephants'")
+    verify_log_entry(log_entries[1], "[1, 2]", "'crabs'")