window

method of dascore.core.patch.Patch source

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:

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 the
window; 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 the
taper 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 array
get_window knows, applied along every windowed dimension, or
a 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 of
NaN unless a fill is given; "drop" leaves it out;
"partial" keeps it, reduced over the samples it has, under
the 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 even
window); "right", the last; "left", the first.
"middle" places windows as "left" does and labels each
halfway 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 as
time=0.5 (seconds) or time=64, distance=16, samples=True.
A dimension named as one of the options above cannot be given.

Examples

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")
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 a PatchProcessor, 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 to apply has no such limits.
  • An operation may keep every n-th sample of a windowed dimension, as decimate and fbe with a step do, 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, as fbe and stalta do 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. apply gives 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. apply and the reductions do not run on a lazy patch yet.