cedalion.sigproc.physio.global_component_subtract

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

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