cedalion.sigproc.physio

Algorithms for handling physiogical components in fNIRS data.

Functions

ampd(amplitudes[, chunk_size, step_size])

Automatic Multiscale Peak Detection (AMPD) algorithm.

global_component_subtract(ts[, ts_weights, ...])

Remove global (physiological) components from a time series.
cedalion.sigproc.physio.global_component_subtract(
ts: cdt.NDTimeSeries,
ts_weights: DataArray = None,
k: float = 0,
spatial_dim: str = 'channel',
spectral_dim: str = None,
) → tuple[source]

Remove global (physiological) components from a time series.

Two modes are available: weighted-mean subtraction (k=0) or PCA-based removal (k>0). Returns both the corrected time series and the global component that was subtracted.

Parameters:

  • ts – Input time series. Must have a "time" dimension, one spatial dimension (spatial_dim, default "channel") and one spectral dimension (e.g. "wavelength" or "chromophore").

  • ts_weights – Per-(spatial × spectral) weights, typically 1/variance. If None, all weights are 1 (unweighted). Must share all non-time dimensions with ts.

  • k –

    Component-removal mode.

    • k = 0: weighted-mean subtraction per spectral slice.

    • k >= 1: remove the first int(k) principal components.

    • 0 < k < 1: remove the minimum number of PCs whose cumulative explained variance is >= k.

  • spatial_dim – Name of the spatial dimension (e.g. "channel", "vertex", or "parcel") across which PCA or averaging is performed. If absent from ts, no subtraction is done.

  • spectral_dim – Name of the spectral dimension (e.g. "wavelength" or "chromophore"). If None, inferred as the only dimension in ts.dims that is neither "time" nor spatial_dim.

Returns:

  • corrected (NDTimeSeries): time series with global components removed.

  • global_component (NDTimeSeries): the subtracted signal. For k=0 this is the weighted-mean regressor (dims: "time", spectral_dim); for k>0 it is the backprojected PCA components averaged across channels.

Return type:

Tuple (corrected, global_component)

Initial Contributors:

Alexander von Lühmann | vonluehmann@tu-berlin.de | 2025

cedalion.sigproc.physio.ampd(amplitudes: cdt.NDTimeSeries, chunk_size: int = 500, step_size: int = 200)[source]

Automatic Multiscale Peak Detection (AMPD) algorithm.

This implementation is based on the AMPD algorithm described in Scholkmann et al. [SBW12] which detects peaks in a signal using a multiscale approach and local scalogram matrix.

Parameters:

  • amplitudes – (NDTimeSeries) Input data array containing signal data for each channel and wavelength.

  • chunk_size – int, optional The size of each chunk to be processed (default is 600).

  • step_size – int, optional Step size for overlapping chunks (default is 200).

Returns:

xarray.DataArray

Output DataArray with the same shape as amplitudes where detected peaks are marked with 1, and non-peaks are marked with 0.

Return type:

peaks

References

Original paper: [SBW12]

Initial Contributors:

Isa Musisi | w.musisi@campus.tu-berlin.de | 2024