pyntbci.utilities.smoothness_matrix

pyntbci.utilities.smoothness_matrix(lengths: int | list[int] | tuple[int, ...] | NDArray) → NDArray

Make a temporal-smoothness (second-difference / discrete Laplacian) penalty matrix.

The returned matrix L implements a smoothness prior on a temporal filter r via the quadratic penalty r.T @ L @ r, which equals the sum of squared differences between adjacent samples (sum_t (r[t] - r[t-1])^2). Minimizing it favors a smooth r. Each block along the diagonal is the second-difference operator with free (Neumann) boundaries: a tridiagonal matrix with diagonal [1, 2, 2, …, 2, 1] and -1 on the first off-diagonals. When multiple lengths are given, L is block-diagonal with one such block per length, so smoothness is enforced within each block but not across block boundaries (e.g. per event of a reconvolution response, so that the tail of one event’s response and the start of the next are not tied together). L is symmetric positive semi-definite (its null space is the per-block constant vectors, i.e. a constant offset is not penalized).

Parameters:

lengths (int | list[int] | tuple[int, ...] | NDArray) – The length of each block, i.e. the number of samples of each event’s temporal response. A single int is a single block.

Returns:

L – The smoothness penalty matrix of shape (sum(lengths), sum(lengths)).

Return type:

NDArray