scale#

movement.transforms.scale(data, factor=1.0, space_unit=None)[source]#

Scale data by a given factor with an optional unit.

Parameters:

data (xarray.DataArray) – The input data to be scaled.
factor (ArrayLike or float) – The scaling factor to apply to the data. If factor is a scalar (a single float), the data array is uniformly scaled by the same factor. If factor is an object that can be converted to a 1D numpy array (e.g. a list of floats), the length of the resulting array must match the length of data array’s space dimension along which it will be 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.

Returns:

The scaled data array.

Return type:

xarray.DataArray

Notes

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

scale#

This Page