Source code for gpype.backend.timing.interpolator

from __future__ import annotations

from fractions import Fraction

import numpy as np
from scipy.signal import butter, sosfilt, sosfilt_zi

from ...common._private import channels
from ...common._private.naming import node_label
from ...common.constants import Constants
from ..core.io_node import IONode

#: Default input port identifier
PORT_IN = Constants.Defaults.PORT_IN
#: Default output port identifier
PORT_OUT = Constants.Defaults.PORT_OUT


[docs] class Interpolator(IONode): """Raises the data rate of a stream by an integer factor L. The mirror image of :class:`Decimator`, and the replacement for the former ``Hold`` node: it raises the rate for real, so every downstream node still sees a ``sampling_rate`` and a ``frame_size`` that mean what they say. The rate rises because L frames are emitted per input frame, not because frames grow -- ``frame_size`` is passed through unchanged, which is what lets the output be joined with a stream already running at the higher rate. The cost is burstiness: the L frames arrive together, once per input frame, so a joined result lags by up to one input period. ``method`` chooses how the missing samples are filled. ``"hold"`` (the default) repeats the last computed value, which is exactly what a windowed estimate means; ``"filter"`` zero-stuffs and low-passes for a smooth reconstruction, at the price of overshoot and about two input samples of group delay -- some 400 ms at a 5 Hz feature rate. Use "hold" for a feature stream, "filter" for a genuine signal. Trigger and auxiliary channels are always held, in both methods: filtering a trigger turns a step into a ramp, which can cross a Trigger threshold on a row where nothing happened. A master-timeline index or a quality channel on the input is refused at setup -- both are consumed by Sync, so seeing one means this node sits upstream of Sync, where it must not sit. Only integer-factor upsampling is in scope. A marker in the input context moves to the first of the L output samples its input sample expands into. A gap covers every output sample whose window holds a missing input sample. With ``"hold"`` the window is the input sample an output expands, so a gap covers all L of every missing one. With ``"filter"``, it is the input samples that carry 99 % of the output's filter weight: 14 at L=2, 11 at L=4. """ #: Cutoff as a fraction of the *input* Nyquist frequency. Below one so #: that the transition band fits below that Nyquist rather than #: straddling it, which is where the zero-stuffed spectral images #: this filter exists to remove would leak back in. CUTOFF_RATIO = 0.8 #: Order of the reconstruction low-pass. FILTER_ORDER = 8 #: Input periods of impulse response measured for a gap's window. #: The windows are 11 to 14 of them for factors 2 to 16, and 512 #: gives the same windows. RESPONSE_PERIODS = 64 #: Repeat the last computed value across the L output rows. METHOD_HOLD = "hold" #: Zero-stuff and low-pass to reconstruct a smooth trajectory. METHOD_FILTER = "filter"
[docs] class Configuration(IONode.Configuration):
[docs] class Keys(IONode.Configuration.Keys): pass
[docs] class OptionalKeys(IONode.Configuration.OptionalKeys): """Optional configuration keys.""" #: Integer factor L by which the data rate is raised. INTERPOLATION_FACTOR = "interpolation_factor" #: Which of METHOD_HOLD / METHOD_FILTER to apply to signal #: channels. METHOD = "method"
[docs] def __init__( self, interpolation_factor: int = 1, method: str = METHOD_HOLD, **kwargs, ): """Initialize interpolator with interpolation factor and method. Args: interpolation_factor: Factor L by which to raise the data rate. Must be a positive integer. Value of 1 means no interpolation (a pure pass-through). method: METHOD_HOLD or METHOD_FILTER, applied to signal channels only -- see the class docstring for the trade-off. Trigger and auxiliary channels are always held, regardless of this setting. **kwargs: Additional arguments for parent IONode. Raises: ValueError: If interpolation_factor is not a positive integer, or method is not one of METHOD_HOLD or METHOD_FILTER. """ if type(interpolation_factor) is not int or interpolation_factor < 1: raise ValueError( "interpolation_factor must be a positive integer, got " f"{interpolation_factor!r}." ) if method not in (self.METHOD_HOLD, self.METHOD_FILTER): raise ValueError( f"method must be one of {self.METHOD_HOLD!r}, " f"{self.METHOD_FILTER!r}, got {method!r}." ) super().__init__( interpolation_factor=interpolation_factor, method=method, **kwargs, ) # decimation_factor (ioiocore's engine-cadence key, distinct from # this node's own interpolation_factor above) is deliberately # never passed, so it stays at ONode.Configuration's own default # of 1. That is what makes is_decimation_step() true on every # cycle -- see step()'s docstring for why that is the only cadence # this node can have. self._l = None # Resolved interpolation factor, set in setup() self._method = None # Resolved method, set in setup() self._split = None # Which channels the chosen method may touch self._sos = None # Reconstruction filter coefficients, if built self._zi = None # Streaming filter state, one set per channel self._primed = False # Whether _zi has been anchored yet
[docs] def setup( self, data: dict[str, np.ndarray], port_context_in: dict[str, dict] ) -> dict[str, dict]: """Setup output context with a raised sampling rate. Args: data: Input data arrays. port_context_in: Input port contexts containing frame size, sampling rate, and per-channel role information. Returns: Output port contexts with the interpolated sampling rate. Frame size is unchanged: the rate rises because L frames are emitted per input frame. Channel count, labels, roles and montage are carried through unchanged -- this node changes rows, not columns. Raises: ValueError: If frame_size is not provided in the input context, or if the input carries a master-timeline index or a quality channel. """ port_context_out = super().setup(data, port_context_in) context_in = port_context_in[PORT_IN] roles = Constants.ChannelRoles # Both refusals below mean the same thing: this node sits # upstream of Sync, where it must not sit, because Sync is what # consumes these two channel kinds (see _private/sync.py). if channels.channels_with_role(context_in, roles.INDEX).size: raise ValueError( "Interpolator found a master_index channel on its " "input, which means it sits upstream of Sync. " "Interpolating a timeline position invents positions " "that were never measured, and holding it repeats one " "position across L samples. Place the Interpolator " "after Sync." ) if channels.channels_with_role(context_in, roles.QUALITY).size: raise ValueError( "Interpolator found a quality channel on its input. " "Quality is consumed by Sync, so seeing it here means " "this node sits upstream of Sync, where it must not " "sit." ) frame_size_in = port_context_out[PORT_OUT][Constants.Keys.FRAME_SIZE] if frame_size_in is None: raise ValueError("frame_size must be provided in context.") L = self.config[self.Configuration.OptionalKeys.INTERPOLATION_FACTOR] method = self.config[self.Configuration.OptionalKeys.METHOD] sr_key = Constants.Keys.SAMPLING_RATE sampling_rate_in = context_in[sr_key] sampling_rate_out = sampling_rate_in * L port_context_out[PORT_OUT][sr_key] = sampling_rate_out # frame_size is deliberately NOT scaled. The rate rises because # this node emits L frames per input frame (see step()), not # because the frames grow -- and that is exactly what lets the # output be combined with a stream already running at the higher # rate, since a Router or Equation requires every input to agree # on frame_size as well as on sampling_rate. Measured both ways: # growing the frame fails the join with "All ports must have the # same frame size", while emitting L frames joins a raw 250 Hz # branch cleanly -- Healthy, exactly 250 rows/s, backlog bounded # at 3. FRAME_RATE is left untouched: only a source or fft.py # ever writes it and nothing gates on it. self._l = L self._method = method self._split = channels.SignalSplit(context_in) self._sos = None self._zi = None self._primed = False if L > 1 and method == self.METHOD_FILTER: n_signal = len(self._split.signal) if self._split.all_signal: n_signal = port_context_out[PORT_OUT][ Constants.Keys.CHANNEL_COUNT ] if n_signal: cutoff = self.CUTOFF_RATIO * sampling_rate_in / 2.0 sos = butter( self.FILTER_ORDER, cutoff, btype="lowpass", output="sos", fs=sampling_rate_out, ) # Zero-stuffing divides the signal's mean energy by L (L # - 1 out of every L stuffed samples are 0), so a # unity-gain filter would leave a reconstructed constant # c at c / L instead of c. Baking a gain of L into the # first section's numerator restores it: standard # multirate theory, not a repo-specific measurement. sos[0, :3] *= L self._sos = sos # (sections, 2, channels) for filtering along axis 0. The # template describes the filter's own steady state for a # unit step input -- which, now that the gain above is # baked in, settles at L, not 1 -- and step() rescales it # by the first real sample once that sample is known, so # a stream that starts at a constant offset does not # ramp towards it from that assumed unit step. self._zi = np.repeat( sosfilt_zi(self._sos)[:, :, None], n_signal, axis=2 ) # A held output is the input sample it expands. A filtered one # depends on every input before it, through every L-th filter # tap, and response_window() says how many carry 99 % of its # weight: 14 at L=2, 11 at L=4 (D-BATCH-80). window = 1 if self._sos is not None: impulse = np.zeros(self.RESPONSE_PERIODS * L + 1) impulse[0] = 1.0 window = channels.response_window( sosfilt(self._sos, impulse), stride=L ) warning = channels.rescale_grid( port_context_out[PORT_OUT], Fraction(L), node_label(self), window=window, ) if warning: self.log(warning, type=Constants.LogTypes.WARNING) return port_context_out
def _emit(self, frame: np.ndarray) -> None: """Push one output frame the way the framework would have. ioiocore's ``node_imp._cycle`` runs the post-step hook and then pushes at most once. An upsampler has to emit more often than that to raise the rate without changing the frame shape, so it emits from inside ``step`` -- and does both halves the framework would have done, in the same order, for every frame rather than only the last. The hook is a no-op lambda unless something installed one (only the ``gp.Node(target=...)`` wrapper does), but relying on that would make this node quietly wrong the day it stops being true. Args: frame: One output frame, already in its final shape. """ out = {PORT_OUT: frame} self._imp.post_step_handler(out) self._imp._push_data(out)
[docs] def step(self, data: dict) -> dict | None: """Expand one input frame into L frames at L times the rate. L == 1 is a pure pass-through: the frame is forwarded unchanged, with no filter ever built or run. Otherwise the expanded rows go out as L frames of the input's own frame size, so the frame shape is preserved and only the emission rate rises. Args: data: Input data dictionary containing one frame to expand. Returns: The frame itself when L == 1, otherwise None -- the L frames have already been emitted by then. """ block = data[PORT_IN] L = self._l if L == 1: return {PORT_OUT: block} signal_in = self._split.take(block) if self._method == self.METHOD_FILTER and self._sos is not None: n_in, n_signal = signal_in.shape # Insert L - 1 zeros after each input sample: the real # sample lands on the first row of the L-row block it # expands into, exactly as Trigger's held edge does (see the # class docstring), so both methods agree on where in the # block the observation itself sits. stuffed = np.zeros((n_in * L, n_signal), dtype=Constants.DATA_TYPE) stuffed[0::L, :] = signal_in if not self._primed: self._zi = self._zi * signal_in[0, :] self._primed = True signal_out, self._zi = sosfilt( self._sos, stuffed, axis=0, zi=self._zi ) else: signal_out = np.repeat(signal_in, L, axis=0) if self._split.all_signal: expanded = signal_out else: # channels.SignalSplit.merge() cannot be reused here: it # assumes the operated block has no more rows than the frame # it is merged back into (frame[-operated.shape[0]:]), which # is true for a Decimator shrinking rows but false here, # where signal_out already has L times the input's rows. # Every carried (trigger, auxiliary) channel is always held # here too, regardless of method, so it is repeated the same # way rather than merged against the original row count. held = np.repeat(block[:, self._split.other], L, axis=0) expanded = np.empty( (signal_out.shape[0], block.shape[1]), dtype=Constants.DATA_TYPE, ) expanded[:, self._split.signal] = signal_out expanded[:, self._split.other] = held # Hand the expanded rows out as L frames of the input's own # frame size, in time order, and return None so _cycle does not # push a duplicate. Returning None to emit nothing from _cycle is # an established pattern here -- Decimator and Trigger both do # it. n_in = block.shape[0] for i in range(L): self._emit(expanded[i * n_in : (i + 1) * n_in, :]) return None