import numpy as np
import dascore as dc
from dascore.units import percent
patch = dc.get_example_patch()
# A moving average over half a second, shaped like the patch.
smooth = patch.window(time=0.5).mean()
# One mean each quarter second, labelled where each window ends.
means = patch.window(time=0.5, step=0.25, align="right").mean()
# Means of pairs of channels, each labelled between its two.
pairs = patch.window(distance=2, step=2, samples=True, align="middle")
stacked = pairs.mean()
# Windows overlapping by a quarter, blended linearly.
window = patch.window(time=0.5, overlap=25 * percent, taper="triang")
out = window.apply(lambda tiles: tiles - tiles.mean(axis=-1, keepdims=True))
# A trend taken out of each second, not out of the whole patch.
local = patch.window(time=1).detrend("time")window
window(
self ,
overlap: Any = None,
step: Any = None,
samples: bool = False,
taper: Any = None,
analysis: Any = None,
ends: str = pad,
align: str = center,
fill: Any = None,
**kwargs ,
)-> ‘PatchWindow’
Declare windows over the patch, to work in or to reduce.
Nothing is computed. A call on what this returns is one operation, and gives back a patch:
- a patch operation, such as
window(time=10).detrend("time"), runs in each window and the windows are blended back; applydoes the same with any function, or stacks the windows instead;- a reduction, such as
mean, gives one value for each window.
See PatchWindow.
Parameters
| Parameter | Description |
|---|---|
| overlap |
How far each window reaches into the next, in coordinate units or, with samples, in samples; a percent is a fraction of thewindow; a mapping gives each dimension its own. |
| step |
How far each window advances, given instead of overlap.
|
| samples | If True, windows, overlaps and steps are sample counts. |
| taper |
For windows which are blended: the shape of the ramps neighbouring windows are blended under – any name dascore.utils.signal.get_window knows. Hann when not given;"triang" blends linearly. The ramps are made complementary,so windows left unchanged blend back to the input exactly. Not applied in "stack" mode, where Patch.reassemble takes thetaper instead. |
| analysis |
For windows which are blended: a window each one is multiplied by before the operation or function sees it – any name, (name, parameter) tuple, or one-dimensional arrayget_window knows, applied along every windowed dimension, ora list with one per windowed dimension in the patch’s dimension order. The windows are then blended back under its dual, so the blend is still exact. Exclusive with taper.
|
| ends |
For a reduction: what becomes of a window which reaches past either end of the data. "pad" keeps it, with a value ofNaN unless a fill is given; "drop" leaves it out;"partial" keeps it, reduced over the samples it has, underthe label the whole window would have. |
| align |
For a reduction: which sample of a window labels it:"center", the middle one (the later of two for an evenwindow); "right", the last; "left", the first."middle" places windows as "left" does and labels eachhalfway between its first and last sample, between two samples for an even window. |
| fill |
The value a window holds where it reaches beyond the data. For windows which are blended, zero when not given. For a reduction, giving one has the incomplete windows computed over data filled out with it, rather than left as NaN. |
| **kwargs |
The dimensions to window and the window along each, such astime=0.5 (seconds) or time=64, distance=16, samples=True.A dimension named as one of the options above cannot be given. |
Examples
Note
- A window chosen here changes the result: the mean of each window is not the mean of the patch, and an operation run in each window and blended is not that operation run on the patch.
- One plan is worked out for the operation, from the first window, and run in every window. A patch operation can therefore run in a window only if it acts relative to its window, which its class states (see
Windowed); it must also be written as aPatchProcessor, give back a window with the same coordinates, or every n-th sample of them along a windowed dimension, take no other patch, and not settle its result from the data it computed, and the window must fit inside its dimension. Anything else is refused before any data are touched; a function given toapplyhas no such limits. - An operation may keep every n-th sample of a windowed dimension, as
decimateandfbewith astepdo, when the windows advance by a multiple of n samples; the result is n times shorter. What an operation leaves empty at the start of each window, asfbeandstaltado until a whole rolling window is behind a sample, is discarded and the rest blended, so the windows must overlap by at least as much; the first samples of the patch stay empty, as they are without a window. - For a patch operation, data on an array backend other than NumPy stay where they are: a dask array is computed a piece at a time when it is asked for, and on any other the windows are run and blended there, unless the operation has no implementation for it, when it is converted through NumPy as it is outside a window.
applygives back NumPy data, and a reduction converts through NumPy. - On a lazy patch an operation in a window needs only the windows a chunk overlaps, so a windowed dimension is computed in pieces even where the operation alone would need it whole.
applyand the reductions do not run on a lazy patch yet.