Skip to content

Utilities

Signal conditioning and scalar metrics.

Conditioning

dspkit.utils.detrend(x, order=1)

Remove a polynomial trend from a signal.

Parameters:

Name Type Description Default
x (array_like, shape(N))

Input signal.

 required
order int

Polynomial order. 0 removes the mean, 1 removes a linear trend, higher orders fit and subtract a polynomial of that degree.

 1

Returns:

Type Description
ndarray

Detrended signal with the same shape as x.
Source code in dspkit/utils.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def detrend(x: np.ndarray, order: int = 1) -> np.ndarray:
    """
    Remove a polynomial trend from a signal.

    Parameters
    ----------
    x : array_like, shape (N,)
        Input signal.
    order : int
        Polynomial order.
        ``0`` removes the mean, ``1`` removes a linear trend,
        higher orders fit and subtract a polynomial of that degree.

    Returns
    -------
    ndarray
        Detrended signal with the same shape as ``x``.
    """
    x = np.asarray(x, dtype=float)
    if order == 0:
        return x - x.mean()
    if order == 1:
        return _signal.detrend(x, type="linear")
    # General polynomial detrending
    t = np.arange(len(x))
    coeffs = np.polyfit(t, x, order)
    return x - np.polyval(coeffs, t)

dspkit.utils.integrate(x, fs, detrend_after=True, detrend_order=1)

Cumulative time integration using the trapezoidal rule.

Typical use: acceleration → velocity, velocity → displacement.

Real sensor signals contain a small DC bias that grows unboundedly when integrated. detrend_after=True (default) removes a linear trend from the result, which suppresses this drift while preserving the physically meaningful AC content.

Parameters:

Name Type Description Default
x (array_like, shape(N))

Input signal.

 required
fs float

Sampling frequency [Hz].

 required
detrend_after bool

If True, apply detrend(result, order=detrend_order) after integration to remove integration drift.

 True
detrend_order int

Polynomial order for post-integration detrending (default 1 = linear).

 1

Returns:

Type Description
(ndarray, shape(N))

Integrated signal. The first sample is set to zero (initial condition).
Source code in dspkit/utils.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def integrate(
    x: np.ndarray,
    fs: float,
    detrend_after: bool = True,
    detrend_order: int = 1,
) -> np.ndarray:
    """
    Cumulative time integration using the trapezoidal rule.

    Typical use: acceleration → velocity, velocity → displacement.

    Real sensor signals contain a small DC bias that grows unboundedly
    when integrated. ``detrend_after=True`` (default) removes a linear
    trend from the result, which suppresses this drift while preserving
    the physically meaningful AC content.

    Parameters
    ----------
    x : array_like, shape (N,)
        Input signal.
    fs : float
        Sampling frequency [Hz].
    detrend_after : bool
        If ``True``, apply ``detrend(result, order=detrend_order)`` after
        integration to remove integration drift.
    detrend_order : int
        Polynomial order for post-integration detrending (default 1 = linear).

    Returns
    -------
    ndarray, shape (N,)
        Integrated signal. The first sample is set to zero (initial condition).
    """
    x = np.asarray(x, dtype=float)
    result = cumulative_trapezoid(x, dx=1.0 / fs, initial=0.0)
    if detrend_after:
        result = detrend(result, order=detrend_order)
    return result

dspkit.utils.differentiate(x, fs)

Numerical differentiation using central differences (numpy.gradient).

Uses second-order accurate central differences at interior points and first-order forward/backward differences at the edges. The output has the same length as the input.

Typical use: displacement → velocity, velocity → acceleration.

Parameters:

Name Type Description Default
x (array_like, shape(N))

Input signal.

 required
fs float

Sampling frequency [Hz].

 required

Returns:

Type Description
(ndarray, shape(N))

Derivative, in units of [x_units * Hz].
Source code in dspkit/utils.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def differentiate(x: np.ndarray, fs: float) -> np.ndarray:
    """
    Numerical differentiation using central differences (numpy.gradient).

    Uses second-order accurate central differences at interior points and
    first-order forward/backward differences at the edges. The output has
    the same length as the input.

    Typical use: displacement → velocity, velocity → acceleration.

    Parameters
    ----------
    x : array_like, shape (N,)
        Input signal.
    fs : float
        Sampling frequency [Hz].

    Returns
    -------
    ndarray, shape (N,)
        Derivative, in units of [x_units * Hz].
    """
    x = np.asarray(x, dtype=float)
    return np.gradient(x, 1.0 / fs)

Scalar metrics

dspkit.utils.rms(x)

Root mean square of a signal.

For a pure sine of amplitude A, RMS = A / sqrt(2).

Source code in dspkit/utils.py 
56
57
58
59
60
61
62
63
def rms(x: np.ndarray) -> float:
    """
    Root mean square of a signal.

    For a pure sine of amplitude A, RMS = A / sqrt(2).
    """
    x = np.asarray(x, dtype=float)
    return float(np.sqrt(np.mean(x ** 2)))

dspkit.utils.peak(x)

Maximum absolute value of a signal (0-to-peak amplitude).

Source code in dspkit/utils.py 
66
67
68
def peak(x: np.ndarray) -> float:
    """Maximum absolute value of a signal (0-to-peak amplitude)."""
    return float(np.max(np.abs(x)))

dspkit.utils.crest_factor(x)

Crest factor: peak / RMS.

For a pure sine: sqrt(2) ~ 1.414. For white Gaussian noise: typically 3–4. High crest factor indicates impulsive content.

Source code in dspkit/utils.py 
71
72
73
74
75
76
77
78
79
def crest_factor(x: np.ndarray) -> float:
    """
    Crest factor: peak / RMS.

    For a pure sine: sqrt(2) ~ 1.414.
    For white Gaussian noise: typically 3–4.
    High crest factor indicates impulsive content.
    """
    return peak(x) / rms(x)