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 by either weighted‐mean subtraction (if k=0) or PCA (if k>0).
cedalion.sigproc.physio.global_component_subtract(
ts: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
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 by either weighted‐mean subtraction (if k=0) or PCA (if k>0).

Returns both the corrected time series and the global component that was removed: the weighted‐mean regressor if k=0, or the average of backprojected principal component time series if k>0.

Parameters:

  • ts – amplitudes (NDTimeSeries): Input DataArray. Must have a “time” dimension, one dimension for space (“spatial_dim”) (default is “channel”, can be “vertex” or “parcel”) and one for spectral info (“wavelength” or “chromophore”).

  • ts_weights – xr.DataArray, optional A DataArray of per‐(spatial_dim × spectral_dim) weigths. This is typically 1/(channel variance). If None, all weights = 1 (no weighting). Must have same non-time dims as ts.

  • k – float, default=0 • k = 0: perform weighted‐mean subtraction (per spectral dim, e.g. HbX or wavelength). • k ≥ 1: remove the first int(k) principal components per spectral dimension. • 0 < k < 1: remove the minimum number of PCs whose cumulative explained variance ≥ k.

  • spatial_dim – str, default “channel” Name of the spatial dimension, like channel, vertex or parcel, across PCA or averaging is performed. If absent, no subtraction is done.

  • spectral_dim – str, optional Name of the spectral dimension (e.g. “wavelength” or “chromophore”). If None, inferred as the dimension in ts.dims that is neither “time” nor spatial_dim. #FIXME for more dimensions

Returns:

(NDTimeSeries):

The time series with global (physiological) components removed.

global_component(NDTimeSeries):

If k=0: the weighted‐mean regressor (dims: “time”, spectral_dim). If k>0: the reconstructed PCA component(s) averaged across all channels (dims: “time”, spectral_dim).

Return type:

corrected

Initial Contributors:

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

cedalion.sigproc.physio.ampd(
amplitudes: Annotated[DataArray, DataArraySchema(dims='time', coords='time', 'time', 'samples')],
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

Initial Contributors:

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