tile_apply

tile_apply(
    patch: Patch ,
    function: Callable ,
    mode: str = overlap_add,
    overlap: Any = None,
    taper: Any = None,
    analysis: Any = None,
    samples: bool = False,
    engine: str = auto,
    **kwargs: Any ,
)-> ‘PatchType’

Apply a function to overlapping windows of the patch.

Parameters

Parameter	Description
patch	The patch to window.
function	What to do to the tiles. On the numpy engine it is given the whole stack at once, an array of `[n_tiles, *window]`, and returns one of the same shape: one vectorized call, not one per tile. A function compiled with numba is given one tile at a time by the numba engine, in parallel, and returns a tile 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 tiles back under `taper` into a patch shaped like the input. `"stack"` returns the tiles unblended: each windowed dimension becomes an axis of tile centres, and the samples within a tile become a new `{dim}_offset` dimension at the end. `reassemble` blends a stack back.
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. Half the window when not given, and never more than half under a taper, whose ramps would cross; under an analysis window, as deep as scipy can invert it.
taper	The window whose edge the taper ramps take – any name `dascore.utils.signal.get_window` knows; Hann when not given. The ramps are made complementary, so blended tiles of an unchanged stack return the input exactly. Not applied in `"stack"` mode.
analysis	A window each tile is multiplied by before `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. Given one, the tiles are blended back under its dual, computed by scipy along each axis, so the blend is still exact; a spectral `function` then sees a properly windowed tile. Exclusive with `taper`, and the overlap may then exceed half the window. None, the default, gives `function` the raw tile.
samples	If True, windows and overlaps are sample counts.
engine	`"numpy"`, `"numba"`, or `"auto"`, which is numba for a numba-compiled `function` and numpy otherwise.
**kwargs	The dimensions to window and the window along each, such as `time=0.5` (seconds) or `time=64, distance=16, samples=True`.

Returns

Patch In "overlap_add" mode, a patch with the input’s coordinates. In "stack" mode, the tiles: the windowed dimensions carry the tile centres, {dim}_start and {dim}_stop say where each tile came from in samples, and {dim}_offset is the position within a tile.

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.tile_apply(agc, time=0.05, distance=50)

# The tiles themselves, to work on and put back.
tiles = patch.tile_apply(lambda x: x, mode="stack", time=0.05, distance=50)
back = tiles.reassemble()

Note

Tiles start before the data and are padded with zeros, as many whole strides before as it takes for every tile which reaches a sample to exist: none when tiles abut, one stride up to half overlap, more beyond it, which an analysis window’s dual relies on.
The adaptive spectral filter is this with a spectral weighting as function; see Patch.adaptive_spectral_filter.