Signal Processing Utilities

Signal Processing Utilities

This module contains utility functions for signal generation, analysis, and filtering. It consolidates functionality from the former signals module.

Functions

brownian : Generate Brownian motion (Wiener process) approximate_entropy : Calculate approximate entropy of a signal filter_1d_timeseries : Filter a 1D time series using various methods filter_signals : Filter multiple signals (2D array) adaptive_filter_signals : Adaptively filter based on SNR

driada.utils.signals.brownian(x0, n, dt=1.0, delta=1.0, out=None)[source]

Generate an instance of Brownian motion (i.e. the Wiener process).

The Brownian motion follows:

X(t) = X(0) + N(0, delta**2 * t; 0, t)

where N(a,b; t0, t1) is a normally distributed random variable with mean a and variance b. The parameters t0 and t1 make explicit the statistical independence of N on different time intervals.

Written as an iteration scheme:

X(t + dt) = X(t) + N(0, delta**2 * dt; t, t+dt)

Parameters:

  • x0 (float or np.ndarray) – The initial condition(s) (i.e. position(s)) of the Brownian motion. If array, each value is treated as an initial condition.

  • n (int) – The number of steps to take.

  • dt (float, optional) – The time step. Default is 1.0.

  • delta (float, optional) – Determines the “speed” of the Brownian motion. The random variable of the position at time t, X(t), has a normal distribution whose mean is the position at time t=0 and whose variance is delta**2*t. Default is 1.0.

  • out (np.ndarray, optional) – If provided, specifies the array in which to put the result. If None, a new numpy array is created and returned.

Returns:

Array of floats with shape x0.shape + (n,). Note that the initial value x0 is not included in the returned array.

Return type:

np.ndarray

Raises:

ValueError – If n <= 0, dt <= 0, or delta < 0

Examples

>>> # Generate single Brownian motion path
>>> path = brownian(0.0, 1000, dt=0.01)
>>> path.shape
(1000,)

>>> # Generate multiple paths with different initial conditions
>>> paths = brownian([0.0, 1.0, -1.0], 1000, dt=0.01)
>>> paths.shape
(3, 1000)
driada.utils.signals.approximate_entropy(U, m, r)[source]

Calculate approximate entropy (ApEn) of a signal.

Approximate entropy is a regularity statistic that quantifies the unpredictability of fluctuations in a time series. A time series containing many repetitive patterns has a relatively small ApEn; a less predictable process has a higher ApEn.

Parameters:

  • U (array-like) – Input signal/time series. Must have length >= m + 2.

  • m (int) – Pattern length. Common values are 1 or 2.

  • r (float) – Tolerance threshold for pattern matching. Typically 0.1-0.25 times the standard deviation of the data.

Returns:

The approximate entropy value. Higher values indicate more randomness/complexity.

Return type:

float

Raises:

ValueError – If length of U < m + 2, m < 1, or r < 0

Notes

The algorithm: 1. Fix m (pattern length) and r (tolerance) 2. Look at patterns of length m and m+1 3. Count pattern matches within tolerance r 4. Calculate the logarithmic frequency of patterns 5. Return the difference between m and m+1 pattern frequencies

Complexity is O(N²). For long signals consider downsampling.

References

Pincus, S. M. (1991). Approximate entropy as a measure of system complexity. Proceedings of the National Academy of Sciences, 88(6), 2297-2301.

Examples

>>> # Regular signal has low entropy
>>> regular = [1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> apen = approximate_entropy(regular, m=2, r=0.5)
>>> apen < 0.1
True

>>> # Random signal has high entropy
>>> import numpy as np
>>> random_signal = np.random.randn(100)
>>> apen = approximate_entropy(random_signal, m=2, r=0.2 * np.std(random_signal))
>>> apen > 0.5  # Typically true for random signals
True
driada.utils.signals.filter_1d_timeseries(data, method='gaussian', **kwargs)[source]

Filter a 1D time series using various denoising methods.

This is the core filtering function used by TimeSeries.filter() method. Supports Gaussian smoothing, Savitzky-Golay filtering, and wavelet denoising.

Parameters:

  • data (ndarray) – 1D time series data

  • method (str) – Filtering method: ‘gaussian’, ‘savgol’, ‘wavelet’, or ‘none’

  • **kwargs (dict) –

    Method-specific parameters:

    • gaussian: sigma (default: 1.0) - standard deviation for Gaussian kernel

    • savgol: window_length (default: 5), polyorder (default: 2)

    • wavelet: wavelet (default: ‘db4’), level (default: auto), mode (default: ‘smooth’), threshold_method (default: ‘mad’)

Returns:

Filtered 1D time series

Return type:

ndarray

Raises:

ValueError – If unknown method or invalid parameters (e.g., polyorder >= window_length)

Examples

>>> import numpy as np
>>> np.random.seed(42)
>>> # Create noisy signal
>>> t = np.linspace(0, 1, 100)
>>> data = np.sin(2 * np.pi * 5 * t) + 0.2 * np.random.randn(100)

>>> # Gaussian smoothing for general noise reduction
>>> filtered = filter_1d_timeseries(data, method='gaussian', sigma=1.5)
>>> filtered.shape
(100,)

>>> # Savitzky-Golay for preserving peaks while smoothing
>>> filtered = filter_1d_timeseries(data, method='savgol', window_length=5)
>>> filtered.shape
(100,)

>>> # Wavelet denoising for multi-scale noise removal
>>> filtered = filter_1d_timeseries(data, method='wavelet', wavelet='db4')
>>> filtered.shape
(100,)
driada.utils.signals.filter_signals(data, method='gaussian', **kwargs)[source]

Filter multiple signals (2D array compatibility wrapper).

Parameters:

  • data (ndarray) – Data with shape (n_signals, n_timepoints) or 1D array

  • method (str) – Filtering method: ‘gaussian’, ‘savgol’, ‘wavelet’, or ‘none’

  • **kwargs (dict) – Method-specific parameters (see filter_1d_timeseries)

Returns:

Filtered data with same shape as input

Return type:

ndarray

Raises:

ValueError – If unknown method or invalid parameters

Examples

>>> # Filter multiple signals
>>> signals = np.random.randn(10, 1000)  # 10 signals, 1000 points each
>>> filtered = filter_signals(signals, method='gaussian', sigma=2.0)

>>> # Also works with 1D arrays
>>> signal = np.random.randn(1000)
>>> filtered = filter_signals(signal, method='savgol')
driada.utils.signals.adaptive_filter_signals(data, snr_threshold=2.0)[source]

Adaptively filter signals based on signal-to-noise ratio.

Parameters:

  • data (ndarray) – Data with shape (n_signals, n_timepoints)

  • snr_threshold (float) – SNR threshold for determining filter strength. Default 2.0.

Returns:

Adaptively filtered data with same shape as input

Return type:

ndarray

Raises:

ValueError – If data is not 2D or snr_threshold <= 0

Notes

Uses simple binary threshold: strong filtering (sigma=2.0) for low SNR, light filtering (sigma=0.5) for high SNR.

Examples

>>> # Adaptively filter based on estimated SNR
>>> signals = np.random.randn(5, 1000)
>>> filtered = adaptive_filter_signals(signals, snr_threshold=3.0)

>>> # Lower threshold applies stronger filtering to more signals
>>> filtered = adaptive_filter_signals(signals, snr_threshold=1.0)

Signal processing and analysis utilities for time series data.