import dascore as dc
# Simple example for rolling mean function
= dc.get_example_patch()
patch
# apply rolling over 1 second with 0.5 step
= patch.rolling(time=1, step=0.5).mean()
mean_patch
# drop nan at the start of the time axis.
= mean_patch.dropna("time") out
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.
See also the rolling section of the processing tutorial and the smoothing recipe.
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, numpyis 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 of10*(default unit) along the time axis. |
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]