cedalion.sigproc.physio.global_component_subtract

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