rolling

function of dascore.proc.rolling source

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

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]

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")