dspk.ops.stage

Pipeline stages (see ops.Pipeline). Defaults follow scipy where an equivalent exists.


`car`	Common average reference, as `ops.spatial.car`.
`clamp`	Clips to a range.
`cmr`	Common median reference, as `ops.spatial.cmr`.
`fir`	An FIR filter with explicit taps, causal or centred.
`gaussian_smooth`	Zero-phase Gaussian smoothing, as `ops.filter.gaussian_smooth`.
`laplacian`	A `ops.spatial.Laplacian` as a stage.
`whiten`	A fitted `ops.spatial.Whitening` as a stage.
`iir`	An IIR filter, as `ops.filter.iir`; the pipeline gives the sample rate.
`median`	Running median, as `ops.filter.median`.
`notch`	A second-order notch, as `ops.filter.notch`.
`scale`	Scales and shifts.
`sos`	Second-order sections you already have, such as from `scipy.signal`.
`subtract_baseline`	Subtracts a constant.
`remap`	A channel map that keeps every channel, as a stage (`reorder_channels` of its order).
`reorder_channels`	The channels in a new order.
`teager_kaiser`	Teager–Kaiser energy, as `ops.filter.teager_kaiser`.
`rectify`	Full-wave rectification, `\|x\|`; a low-pass after it gives an envelope.
`square`	Instantaneous power, `x**2`; a low-pass and `sqrt` after it give a moving RMS.
`sqrt`	Square root, `sqrt(x)`, with negative values taken as 0.
`log10`	`log10(\|x\|)`, with magnitudes below `LOG10_FLOOR` taken as it.
`Stage`	One pipeline stage (build with the functions of `dspk.ops.stage`).

Functions

`car`

car() -> Stage

Common average reference, as ops.spatial.car.

Returns

Stage

`clamp`

clamp(min: float, max: float) -> Stage

Clips to a range: y = clip(x, min, max).

Parameters

min : float
Lower bound.
max : float
Upper bound, at least min.

Returns

Stage

Raises

ValueError: When min is above max.

`cmr`

cmr() -> Stage

Common median reference, as ops.spatial.cmr.

Returns

Stage

`fir`

fir(
    taps,
    *,
    centered: bool = False,
    edge: str = FIR_DEFAULT_EDGE,
) -> Stage

An FIR filter with explicit taps, causal or centred.

Parameters

taps : array_like
Filter taps (1-D), e.g. from ops.filter.firwin.
centered : bool, default False
False: causal. True: the taps (an odd number) centred on each sample.
edge : {"zeros", "odd", "reflect", "nearest"}, default FIR_DEFAULT_EDGE (‘zeros’)
What the samples past each end are taken to be.

Returns

Stage

Raises

ValueError: For empty taps or an even number of centred taps.

Notes

In Pipeline(stream=True) the taps’ history is not carried from one chunk to the next: run it on independent chunks with settling of context, which is exact for a FIR.

`gaussian_smooth`

gaussian_smooth(
    sigma_samples: float,
    *,
    edge: str = GAUSSIAN_DEFAULT_EDGE,
) -> Stage

Zero-phase Gaussian smoothing, as ops.filter.gaussian_smooth.

Parameters

sigma_samples : float
Standard deviation, in samples.
edge : {"zeros", "odd", "reflect", "nearest"}, default GAUSSIAN_DEFAULT_EDGE (‘reflect’)
What the samples past each end are taken to be.

Returns

Stage

Raises

ValueError: For a non-positive sigma_samples.

`laplacian`

laplacian(laplacian) -> Stage

A ops.spatial.Laplacian as a stage.

Parameters

laplacian : dspk.ops.spatial.Laplacian
Made for as many channels as the pipeline’s input.

Returns

Stage

`whiten`

whiten(whitening) -> Stage

A fitted ops.spatial.Whitening as a stage.

Parameters

whitening : dspk.ops.spatial.Whitening
Fitted on as many channels as the pipeline’s input.

Returns

Stage

`iir`

iir(
    band: str,
    cutoff: float | Sequence[float],
    *,
    order: int = DEFAULT_ORDER,
    design: str = 'butterworth',
    ripple_db: float | None = None,
    mode: str = 'forward_backward',
    start: str = 'rest',
) -> Stage

An IIR filter, as ops.filter.iir; the pipeline gives the sample rate.

Parameters

band : {"lowpass", "highpass", "bandpass", "bandstop"}
The band the filter passes (or stops).
cutoff : float or (float, float)
Cutoff in Hz: one, or (low, high) for the band filters.
order : int, default DEFAULT_ORDER (5)
Filter order.
design : {"butterworth", "chebyshev1", "bessel"}, default 'butterworth'
The filter family.
ripple_db : float, default None
Passband ripple in dB; "chebyshev1" needs it.
mode : {"forward_backward", "forward"}, default 'forward_backward'
"forward_backward": zero phase (windowed runs only). "forward": causal, the mode stream=True needs.
start : {"rest", "steady_state"}, default 'rest'
Where a "forward" pass starts, as in ops.filter.iir.

Returns

Stage

Raises

ValueError: For an invalid design, mode or start.

`median`

median(width: int, *, edge: str = MEDIAN_DEFAULT_EDGE) -> Stage

Running median, as ops.filter.median.

Parameters

width : int
Window length in samples, odd, at most MAX_MEDIAN_WIDTH.
edge : {"zeros", "odd", "reflect", "nearest"}, default MEDIAN_DEFAULT_EDGE (‘zeros’)
What the samples past each end are taken to be.

Returns

Stage

Raises

ValueError: For an even or too large width.

`notch`

notch(
    freq: float,
    q: float,
    *,
    mode: str = 'forward_backward',
    start: str = 'rest',
) -> Stage

A second-order notch, as ops.filter.notch.

Parameters

freq : float
Frequency to remove, in Hz.
q : float
Quality factor: the notch is freq / q Hz wide at -3 dB.
mode : {"forward_backward", "forward"}, default 'forward_backward'
"forward_backward": zero phase (windowed runs only). "forward": causal, the mode stream=True needs.
start : {"rest", "steady_state"}, default 'rest'
Where a "forward" pass starts, as in ops.filter.iir.

Returns

Stage

`scale`

scale(alpha: float, beta: float = 0.0) -> Stage

Scales and shifts: y = alpha * x + beta.

Parameters

alpha : float
Factor.
beta : float, default 0.0
Offset, in the signal’s unit.

Returns

Stage

`sos`

sos(
    sections: np.ndarray,
    *,
    mode: str = 'forward_backward',
    start: str = 'rest',
) -> Stage

Second-order sections you already have, such as from scipy.signal.

Parameters

sections : numpy.ndarray
(sections, 6) in scipy’s layout.
mode : {"forward_backward", "forward"}, default 'forward_backward'
"forward_backward": zero phase (windowed runs only). "forward": causal, the mode stream=True needs.
start : {"rest", "steady_state"}, default 'rest'
Where a "forward" pass starts, as in ops.filter.iir.

Returns

Stage

`subtract_baseline`

subtract_baseline(baseline: float) -> Stage

Subtracts a constant: y = x - baseline.

Parameters

baseline : float
In the signal’s unit.

Returns

Stage

`remap`

remap(map) -> Stage

A channel map that keeps every channel, as a stage (reorder_channels of its order).

Parameters

map : dict, list of dict, str or os.PathLike
A channel map: a {"base", "pairs"} dict (or a file’s {"remap": {...}}), a list of {"from", "to", "name"} pairs, or the path of a .toml / .json map file.

Returns

Stage

Raises

ValueError: When the map is invalid or drops channels.

`reorder_channels`

reorder_channels(order: Sequence[int]) -> Stage

The channels in a new order: output channel i is input channel order[i].

Every channel is used once, so the channel count stays. To drop channels, use ops.layout.remap, or a remap node right after read or before write in a pipeline spec.

Parameters

order : sequence of int
A permutation of 0..channels.

Returns

Stage

Raises

ValueError: When order is not a permutation.

`teager_kaiser`

teager_kaiser(
    *,
    edge: str = TEAGER_KAISER_DEFAULT_EDGE,
) -> Stage

Teager–Kaiser energy, as ops.filter.teager_kaiser.

Parameters

edge : {"zeros", "odd", "reflect", "nearest"}, default TEAGER_KAISER_DEFAULT_EDGE (‘reflect’)
What the samples past each end are taken to be.

Returns

Stage

`rectify`

rectify() -> Stage

Full-wave rectification, |x|; a low-pass after it gives an envelope.

Returns

Stage

`square`

square() -> Stage

Instantaneous power, x**2; a low-pass and sqrt after it give a moving RMS.

Returns

Stage

`sqrt`

sqrt() -> Stage

Square root, sqrt(x), with negative values taken as 0.

Returns

Stage

`log10`

log10() -> Stage

log10(|x|), with magnitudes below LOG10_FLOOR taken as it.

Returns

Stage

Classes

`Stage`

One pipeline stage (build with the functions of dspk.ops.stage).

Constants

Name	Type	Value
`GAUSSIAN_DEFAULT_EDGE`	`str`	`'reflect'`
`MAX_MEDIAN_WIDTH`	`int`	`31`
`MEDIAN_DEFAULT_EDGE`	`str`	`'zeros'`
`TEAGER_KAISER_DEFAULT_EDGE`	`str`	`'reflect'`
`FIR_DEFAULT_EDGE`	`str`	`'zeros'`
`LOG10_FLOOR`	`float`	`1e-12`