rolling

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

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.
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.
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.

Examples

# Simple example for rolling mean function
import dascore as dc
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")

Note

This class behaves like pandas.rolling (https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.rolling.html) 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]