diff --git a/dascore/proc/rolling.py b/dascore/proc/rolling.py index 3d7421c6..42e6c884 100644 --- a/dascore/proc/rolling.py +++ b/dascore/proc/rolling.py @@ -249,16 +249,16 @@ def rolling( Notes ----- - This class behaves like pandas.rolling - (https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.rolling.html) - which has some important implications. + Rolling is designed to behaves like Pandas [DataFrame.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 + - 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`](`dascore.Patch.dropna`) to remove the NaN values. - Second, the step parameter is equivalent applying to the output along the + - 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. @@ -266,13 +266,17 @@ def rolling( 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 + + - 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 + + - 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 + + - if time = 3 * dt and step = 2 * dt [NaN, 1.0, 3.0] - if time = 3 * dt and step = 3 * dt + + - if time = 3 * dt and step = 3 * dt [NaN, 2.0] Examples diff --git a/docs/recipes/smoothing.qmd b/docs/recipes/smoothing.qmd index 45f139d3..eb706dfa 100644 --- a/docs/recipes/smoothing.qmd +++ b/docs/recipes/smoothing.qmd @@ -4,7 +4,7 @@ execute: warn: false --- -This recipe compares various smoothing strategies. +This recipe compares several smoothing strategies. A few patch methods useful for smoothing are: @@ -16,12 +16,12 @@ A few patch methods useful for smoothing are: :::{.callout-note} [`Patch.rolling`](`dascore.Patch.rolling`) is quite flexible and can be used for many different processing tasks. However, as mentioned in the [rolling section of the tutorial](/tutorial/processing.qmd#rolling), [`Patch.rolling`](`dascore.Patch.rolling`) includes `NaN` entries in the output due to edge effects. This can require some additional thought to properly deal with. -The other methods mentioned above generally deal with edge effects differently (governed by the `mode` parameter) and so don't have the same issue. +The other methods mentioned above deal with edge effects differently (governed by the `mode` parameter) and so don't have the same issue. ::: ## Example Data -We will use [example_event_2](`dascore.examples.example_event_2`) to demonstrate the effects of the smoothing methods. +We will use [example_event_2](`dascore.examples.example_event_2`) to demonstrate how to use each smoothing methods. ```{python} import numpy as np @@ -35,7 +35,7 @@ ax.set_title("un-smoothed patch"); ## Rolling -[`Patch.rolling`](`dascore.Patch.rolling`) can be used for applying several different aggregation functions to rolling windows along one dimension of the `Patch` instance. For instance, to apply a rolling mean to the time axis: +[`Patch.rolling`](`dascore.Patch.rolling`) can be used for applying aggregation functions to rolling windows along one dimension of the `Patch` instance. For instance, to apply a rolling mean to the time axis: ```{python} smoothed_patch = ( @@ -80,6 +80,10 @@ ax = nan_patch.viz.waterfall() ax.set_title("NaNs in Patch"); ``` +Which can be conveniently dropped with [Patch.dropna](`dascore.Patch.dropna`). + +['Patch.fill_nan`] + ## Savgol filter [`Patch.savgol_filter`](`dascore.Patch.savgol_filter`) uses [SciPy's savgol_filter](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.savgol_filter.html), which is an implementation of the [Savitzky-Golay Filter](https://en.wikipedia.org/wiki/Savitzky%E2%80%93Golay_filter) to apply smoothing along a single dimension. @@ -109,19 +113,19 @@ ax.set_title("savgol time and distance"); ## Gaussian filter -[`Patch.gaussian_filter`](`dascore.Patch.gaussian_filter`) uses [SciPy's gaussian_filter](https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html) to apply a gaussian smoothing kernel to a patch. Note that the keyword arguments here specify standard deviation, and the `truncate` keyword determines how many standard deviations are included in the smoothing kernel. +[`Patch.gaussian_filter`](`dascore.Patch.gaussian_filter`) uses [SciPy's gaussian_filter](https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html) to apply a gaussian smoothing operator to the patch. Note that the keyword arguments here specify standard deviation, and the `truncate` keyword determines how many standard deviations are included in the smoothing kernel. ```{python} smoothed_patch = patch.gaussian_filter( - time=6, - distance=6, + time=5, + distance=5, samples=True, ) ax = smoothed_patch.viz.waterfall() ax.set_title("gaussian time and distance"); ``` -To visualize the smoothing kernel we can apply the operator to a patch which has all 0 values except a 1 in the center. +To visualize the smoothing kernel we can apply the operator to a patch whose data is all 0s except for a single 1 in the center. ```{python} data = np.zeros_like(smoothed_patch.data)