apply

method of dascore.proc.window.PatchWindow source

apply(
    self ,
    function: Callable ,
    mode: str = overlap_add,
    engine: str = auto,
)

Apply a function to the windows, and blend or stack what it returns.

Parameters

Parameter Description
function What to do to the windows. On the numpy engine it is given all
of them at once, an array of [n_tiles, *window], and returns
one of the same shape: one vectorized call, not one per window.
A function compiled with numba is given one window at a time by
the numba engine, in parallel, and returns a window of the same
shape; it compiles the first time it is used in each process,
which takes a few seconds.
mode "overlap_add" blends the windows back under the window’s
taper into a patch shaped like the input. "stack" returns
them unblended: each windowed dimension becomes an axis of
window centres, and the samples within a window become a new
{dim}_offset dimension at the end.
Patch.reassemble blends a stack
back.
engine "numpy", "numba", or "auto", which is numba for a
numba-compiled function and numpy otherwise.

Returns

Patch In "overlap_add" mode, a patch with the input’s coordinates. In "stack" mode, the windows: the windowed dimensions carry the window centres, {dim}_start and {dim}_stop give each one’s closed low and open high edges in the dimension’s units, and {dim}_offset is the position within a window.

Examples

import numpy as np
import dascore as dc
patch = dc.get_example_patch("example_event_2")

# Automatic gain control: every window scaled to unit RMS, blended.
def agc(tiles):
    rms = np.sqrt(np.mean(tiles**2, axis=(1, 2), keepdims=True))
    return tiles / np.where(rms > 0, rms, 1)
normalized = patch.window(time=0.05, distance=50).apply(agc)

# The windows themselves, to work on and put back.
tiles = patch.window(time=0.05, distance=50).apply(
    lambda x: x, mode="stack"
)
back = tiles.reassemble()
Note
  • A window with no overlap or step given overlaps the next by half. Under a taper the overlap is never more than half, since the ramps would cross; under an analysis window it may be as deep as scipy can invert.
  • Windows start before the data and run past its end, holding the window’s fill there, so every sample is under a whole taper. The function sees those values.