conv

conv

Piecewise-linear convolution with analytic integration.

This module implements convolution using piecewise-linear interpolation with analytical integration between time points. This approach is more accurate than FFT-based methods for pharmacokinetic modeling, particularly when time sampling is non-uniform.

References

- dcmri (https://github.com/dcmri/dcmri) utils.conv()
- Sourbron & Buckley (2013). Tracer kinetic modelling in MRI.
  NMR Biomed. 26(8):1034-1048.

conv

conv(f, h, t, *, dt=None)

Convolve two signals using piecewise-linear integration.

Computes the convolution integral: (f * h)(t) = integral_0^t f(u) * h(t - u) du

using piecewise-linear interpolation and analytical integration between time points. This method is accurate for non-uniform time grids and preserves endpoint behavior.

PARAMETER	DESCRIPTION
f	Input signal (e.g., arterial input function). Shape: (n_times,). TYPE: ndarray
h	Impulse response function (e.g., residue function). Shape: (n_times,). TYPE: ndarray
t	Time points in seconds. Shape: (n_times,). Must be monotonically increasing and start at 0. TYPE: ndarray
dt	If provided, assumes uniform time grid with this step size. Enables optimized computation path. TYPE: float DEFAULT: None

RETURNS	DESCRIPTION
ndarray	Convolution result at each time point. Shape: (n_times,).

Notes

The convolution is computed using the trapezoidal rule with piecewise-linear interpolation. For each time point t[i], the integral is computed as:

conv[i] = sum_{j=0}^{i-1} integral_{t[j]}^{t[j+1]} f(u) * h(t[i]-u) du

where the integral within each interval is evaluated analytically assuming linear interpolation of both f and h.

For uniform time grids (when dt is provided), a more efficient algorithm is used.

Examples:

>>> import numpy as np
>>> from osipy.common.convolution import conv
>>> t = np.linspace(0, 10, 101)  # 0 to 10 seconds
>>> aif = np.exp(-t / 2)  # Exponential decay AIF
>>> irf = np.exp(-t / 5)  # Exponential IRF
>>> result = conv(aif, irf, t)

References

.. [1] dcmri library: https://github.com/dcmri/dcmri

uconv

uconv(f, h, dt)

Convolve two signals on a uniform time grid.

Optimized convolution for uniform time sampling using the trapezoidal rule. More efficient than the general non-uniform algorithm when time points are equally spaced.

PARAMETER	DESCRIPTION
f	Input signal. Shape: (n_times,). TYPE: ndarray
h	Impulse response function. Shape: (n_times,). TYPE: ndarray
dt	Time step between samples in seconds. TYPE: float

RETURNS	DESCRIPTION
ndarray	Convolution result. Shape: (n_times,).

Notes

Uses the discrete convolution formula with trapezoidal weighting:

conv[i] = dt * sum_{j=0}^{i} w[j] * f[j] * h[i-j]

where w[j] = 0.5 for j=0 and j=i, and w[j] = 1 otherwise (trapezoidal weights).

Examples:

>>> import numpy as np
>>> from osipy.common.convolution import uconv
>>> dt = 0.1  # 100 ms time step
>>> n = 100
>>> f = np.exp(-np.arange(n) * dt / 2)
>>> h = np.exp(-np.arange(n) * dt / 5)
>>> result = uconv(f, h, dt)