dspk.custom

Custom operations: your own Python functions over a recording, window by window.

dspk reads the recording in windows (the next one is read on another thread while your function runs), so a recording of any length goes through a function that only ever sees a window:

measure calls fn(x, w) on each window and gathers what it returns into a table: one row per window (band power per channel, a count, a dict of several values).
transform wraps fn(x) (or fn(x, w)) that returns the window processed, same shape. Windows are read with halo samples of context on each side and the result is trimmed back, so the windowed output equals fn on the whole array for any fn that looks at most halo samples away (a moving average of 2 · halo + 1 samples, a filter whose response has died out within halo). apply returns an array; write writes the whole recording to Zarr without holding it in memory.

x is (channels, samples) float32 NumPy in each channel’s unit, as io.Recording.read gives it; w is the Window it came from.


`measure`	Calls your function on every window and gathers what it returns into a table.
`transform`	Wraps a function of a window as a `Transform`; also a decorator.
`windows`	The slice of the read array that holds the window’s own samples.
`Transform`	Your function of a window, run over recordings window by window.
`Window`	Where a window’s samples come from.

Functions

`measure`

measure(
    rec,
    fn: Callable,
    *,
    window_s: float = DEFAULT_WINDOW_S,
    channels: Sequence[int] | None = None,
    start: int = 0,
    stop: int | None = None,
) -> dict[str, np.ndarray]

Calls your function on every window and gathers what it returns into a table.

Parameters

rec : dspk.io.Recording
The recording.
fn : callable
fn(x) or fn(x, w): x the window (channels, samples) float32, w its Window. Returns a value (a number, a row per channel) or a dict of values, with the same keys and shapes for every window.
window_s : float, default DEFAULT_WINDOW_S
Seconds per window: one row of the table each.
channels : sequence of int, default None
Channels to read; by default all.
start : int, default 0
First sample.
stop : int, default None
The sample after the last; by default the end.

Returns

dict of np.ndarray — start_s and stop_s of each window, and each value fn returns, stacked by window (a number per window gives (windows,), a row per channel (windows, channels)). A value returned alone is called "value". The last window may be shorter.

Raises

ValueError: When windows return different keys or shapes.

Examples

>>> import numpy as np
>>> import dspk
>>> rec = dspk.io.open("session.zarr")
>>> table = dspk.custom.measure(rec, lambda x: {"rms": np.sqrt((x**2).mean(axis=1))})

`transform`

transform(
    fn: Callable | None = None,
    *,
    halo: int = 0,
    window_s: float = DEFAULT_WINDOW_S,
)

Wraps a function of a window as a Transform; also a decorator.

Parameters

fn : callable, default None
fn(x) or fn(x, w), returning the window processed, the same shape as x. Leave it out to use transform(...) as a decorator.
halo : int, default 0
Samples of context fn needs on each side.
window_s : float, default DEFAULT_WINDOW_S
Seconds per window (memory only: results do not depend on it).

Returns

Transform

Examples

>>> import numpy as np
>>> import dspk
>>> @dspk.custom.transform(halo=12)
... def smooth(x):
...     k = np.ones(25, dtype=np.float32) / 25
...     return np.stack([np.convolve(c, k, mode="same") for c in x])
>>> rec = dspk.io.open("session.zarr")
>>> smooth.write(rec, "smoothed.zarr")

`windows`

windows(
    rec,
    *,
    window_s: float = DEFAULT_WINDOW_S,
    halo: int = 0,
    channels: Sequence[int] | None = None,
    start: int = 0,
    stop: int | None = None,
) -> Iterator[tuple[np.ndarray, Window]]

The slice of the read array that holds the window’s own samples.

Parameters

rec
window_s : float, default DEFAULT_WINDOW_S
halo : int, default 0
channels : Sequence[int] | None, default None
start : int, default 0
stop : int | None, default None

Classes

`Transform`

Transform(
    fn: Callable,
    *,
    halo: int = 0,
    window_s: float = DEFAULT_WINDOW_S,
)

Your function of a window, run over recordings window by window.

Windows are read with halo samples of context on each side and the output is trimmed back, so the result equals fn on the whole array for any fn that looks at most halo samples away (a moving average of 2 * halo + 1 samples, a filter whose response dies out within halo). Make one with transform.

Parameters

fn : Callable
halo : int, default 0
window_s : float, default DEFAULT_WINDOW_S

`Transform.blocks`

blocks(
    rec,
    *,
    channels: Sequence[int] | None = None,
    start: int = 0,
    stop: int | None = None,
) -> Iterator[tuple[np.ndarray, Window]]

The processed windows of a recording, one at a time.

Parameters

rec : dspk.io.Recording
The recording.
channels : sequence of int, default None
Channels to read; by default all.
start : int, default 0
First sample.
stop : int, default None
The sample after the last; by default the end.

Raises

ValueError: When fn returns another shape than it was given.

`Transform.apply`

apply(
    rec,
    *,
    channels: Sequence[int] | None = None,
    start: int = 0,
    stop: int | None = None,
) -> np.ndarray

A recording processed, as one array in memory.

Parameters

rec : dspk.io.Recording
The recording.
channels : sequence of int, default None
Channels to read; by default all.
start : int, default 0
First sample.
stop : int, default None
The sample after the last; by default the end.

Returns

np.ndarray — (channels, stop - start), float32.

`Transform.write`

write(
    rec,
    path: str | PathLike,
    *,
    channels: Sequence[int] | None = None,
    start: int = 0,
    stop: int | None = None,
    chunk_samples: int = io.ZARR_CHUNK_SAMPLES,
    compression: str = 'zstd',
) -> None

A recording processed and written to a new Zarr store, window by window.

The whole recording is never held in memory. Channel names and units are the recording’s.

Parameters

rec : dspk.io.Recording
The recording.
path : str or os.PathLike
The store to create.
channels : sequence of int, default None
Channels to read; by default all.
start : int, default 0
First sample.
stop : int, default None
The sample after the last; by default the end.
chunk_samples : int, default io.ZARR_CHUNK_SAMPLES
Samples per Zarr chunk.
compression : {"zstd", "blosc_lz4", "none"}, default 'zstd'
How chunks are compressed.

Raises

ValueError: When fn returns another shape than it was given, or the range is outside the recording.
OSError: When the store cannot be written.

`Window`

Window(
    index: int,
    start: int,
    stop: int,
    read_start: int,
    read_stop: int,
    sample_rate: float,
    channels: tuple[int, ...],
) -> None

Where a window’s samples come from.

Parameters

index : int
start : int
stop : int
read_start : int
read_stop : int
sample_rate : float
channels : tuple[int, ...]

Properties

Name	Type	Description
`index`	`int`
`start`	`int`
`stop`	`int`
`read_start`	`int`
`read_stop`	`int`
`sample_rate`	`float`
`channels`	`tuple[int, ...]`
`inner`	`slice`
`start_s`	`float`	Start of the window, in seconds.
`stop_s`	`float`	End of the window, in seconds.

Constants

Name	Type	Value	Description
`DEFAULT_WINDOW_S`	`float`	`1.0`