rolling

rolling(
    patch: Patch ,
    step = None,
    center = False,
    engine: Literal[‘numpy’, ‘pandas’, None] = None,
    samples = False,
    **kwargs ,
)-> ’_NumpyPatchRoller | _PandasPatchRoller’

Apply a rolling function along a specified dimension.

Parameters

Parameter	Description
step	The window is evaluated at every step result, equivalent to slicing at every step. If the step argument is not None, the result will have a different shape than the input. Default None.
center	If False, set the window labels as the right edge of the window index. If True, set the window labels as the center of the window index. Default False.
engine	Determines how the rolling operations are applied. If None, try to determine which will be fastest for a given step. Options are: “numpy” - which uses np.lib.stride_tricks.sliding_window_view. “pandas” - which uses pandas.rolling. If step < 10 samples, pandas is faster for all operations other than apply. If step > 10 samples, or `apply` is the desired rolling operation, numpy is probably better.
samples	If True, the values in kwargs and step represent samples along a dimension. Must be integers. Otherwise, values are assumed to have same units as the specified dimension, or have units attached.

**kwargs	Used to pass dimension and window size. For example `time=10` represents window size of 10*(default unit) along the time axis.

Note

Here we have included some useful notes for the rolling function.

Note 1: Length of the output and NaN values

Rolling is designed to behaves like Pandas DataFrame.rolling which has some important implications:

First, when step is not defined or set to 1, the output patch will have the same shape as the input patch. The consequence of this is that NaN values will appear at the start of the dimension. You can use patch.dropna to remove the NaN values.
Second, the step parameter is equivalent applying to the output along the specified dimension. For example, if step=2 the output of the chosen dimension will be 1/2 of the input length.

Here are a few examples to help illustrate how rolling works.

Consider a patch with a simple 1D array in the dimension “time”: [0, 1, 2, 3, 4, 5]

If time = 2 * dt the output is [NaN, 0.5, 1.5, 2.5, 3.5, 4.5]
If time = 3 * dt the output is [NaN, NaN, 1.0, 2.0, 3.0, 4.0]
if time = 3 * dt and step = 2 * dt [NaN, 1.0, 3.0]
if time = 3 * dt and step = 3 * dt [NaN, 2.0]

Note 2: Applying custom functions with rolling operation

When apply is the desired rolling operation and we are interested to use our own function over a desired window, we need to define our finction the way that it performs the operation on the last axis of the sliced matrix

Below is an example of applying a custom zero crossing rate function (zcr_std) with rolling operation for a window size of 100 samples and skipping every other samples. It applys the desired operation (which is multiplying every sample to its next sample to determine the zero crossings) on the last axis of the sliced frame (from rolling).

import numpy as np
import dascore as dc


def zcr_std(frame, axis=-1):
    '''Compute standard deviation of zero crossing rate using rolling function.'''
    zero_crossings = (frame[..., :-1] * frame[..., 1:]) < 0
    return np.std(zero_crossings, axis=axis)


patch = dc.get_example_patch()
zcr_patch = patch.rolling(time=100, step=2, samples=True).apply(zcr_std)

Examples

import dascore as dc

# Simple example for rolling mean function
patch = dc.get_example_patch()

# apply rolling over 1 second with 0.5 step
mean_patch = patch.rolling(time=1, step=0.5).mean()

# drop nan at the start of the time axis.
out = mean_patch.dropna("time")