cedalion.models.glm package

Submodules

cedalion.models.glm.basis_functions module

Temporal basis functions for the GLM.

class cedalion.models.glm.basis_functions.TemporalBasisFunction(convolve_over_duration: bool)[source]

Bases: ABC

class cedalion.models.glm.basis_functions.GaussianKernelsWithTails(
t_pre: cdt.QTime,
t_post: cdt.QTime,
t_delta: cdt.QTime,
t_std: cdt.QTime,
)[source]

Bases: TemporalBasisFunction

A consecutive sequence of gaussian functions.

The basis functions have the form:

\[f(t) = \exp( -(t-\mu)^2/t_{std}^2)\]

The user specifies a time interval around the stimuls onset via the parameters t_pre and t_post. Over this time interval a series of gaussian basis functions is distributed:

  • between the gaussian centers there is time gap of t_delta

  • the width of the each gaussian is specified by t_std

  • the gaussians are centered in the time interval with a margin of 3 x t_std left and right.

The number of gaussians is derived automatically from these constraints.

Parameters:

  • t_pre (Quantity, [time]) – time before trial onset

  • t_post (Quantity, [time]) – time after trial onset

  • t_delta (Quantity, [time]) – the temporal spacing between consecutive gaussians

  • t_std (Quantity, [time]) – time width of the gaussians

class cedalion.models.glm.basis_functions.GaussianKernels(
t_pre: cdt.QTime,
t_post: cdt.QTime,
t_delta: cdt.QTime,
t_std: cdt.QTime,
)[source]

Bases: TemporalBasisFunction

A consecutive sequence of gaussian functions.

The basis functions have the form:

\[f(t) = \exp( -(t-\mu)^2/t_{std}^2)\]

The user specifies a time interval around the stimuls onset via the parameters t_pre and t_post. Over this time interval a series of gaussian basis functions is distributed:

  • between the gaussian centers there is time gap of t_delta

  • the width of the each gaussian is specified by t_std

  • the first gaussian is centered at trial onset - t_pre.

  • the model function extends strictly from -t_pre to t_post with a hard cutoff.

The number of gaussians is derived automatically from these constraints.

Parameters:

  • t_pre (Quantity, [time]) – time before trial onset

  • t_post (Quantity, [time]) – time after trial onset

  • t_delta (Quantity, [time]) – the temporal spacing between consecutive gaussians

  • t_std (Quantity, [time]) – time width of the gaussians

class cedalion.models.glm.basis_functions.Gamma(
tau: cdt.QTime | dict[str, cdt.QTime],
sigma: cdt.QTime | dict[str, cdt.QTime],
T: cdt.QTime | dict[str, cdt.QTime],
)[source]

Bases: TemporalBasisFunction

Modified gamma function, optionally convolved with a square-wave.

The basis function has the form:

\[f(t) \sim \frac{t-\tau}{\sigma} \exp \left(-\left(\frac{t - \tau}{\sigma}\right)^2\right)\]
Parameters:

  • tau – Specifies a delay of the response with respect ot stimulus onset time.

  • sigma – Specifies the width of the hemodynamic reponse.

  • T – If > 0, the response is additionally convoluted by a square wave of this width.

class cedalion.models.glm.basis_functions.GammaDeriv(
tau: cdt.QTime | dict[str, cdt.QTime],
sigma: cdt.QTime | dict[str, cdt.QTime],
T: cdt.QTime | dict[str, cdt.QTime],
)[source]

Bases: TemporalBasisFunction

Modified gamma func. and its derivative, optionally convolved with a square-wave.

Parameters:

  • tau – onset time

  • sigma – width of the HRF

  • T – convolution width

class cedalion.models.glm.basis_functions.AFNIGamma(
p: float | dict[str, float],
q: cdt.QTime | dict[str, cdt.QTime],
T: cdt.QTime | dict[str, cdt.QTime],
)[source]

Bases: TemporalBasisFunction

AFNI gamma basis function, optionally convolved with a square-wave.

Parameters:

  • p – shape parameter

  • q – scale parameter

  • T – convolution width

class cedalion.models.glm.basis_functions.DiracDelta[source]

Bases: TemporalBasisFunction

Convoluted with the stim duration this basis function yields a square wave.

cedalion.models.glm.design_matrix module

Functions to create the design matrix for the GLM.

class cedalion.models.glm.design_matrix.DesignMatrix(
common: 'xr.DataArray | None' = None,
channel_wise: 'list[xr.DataArray]' = <factory>,
)[source]

Bases: object

common: DataArray | None = None[source]
channel_wise: list[DataArray][source]
property regressors[source]
iter_computational_groups(
ts: cdt.NDTimeSeries,
channel_groups: list[int] | None = None,
)[source]

Combine universal and channel-wise regressors and yield a DM for each group.

Parameters:

  • ts – The time series to be modeled.

  • channel_groups – Optional list of channel groups.

Yields:

A tuple containing – - dim3 (str): The third dimension name. - group_y (cdt.NDTimeSeries): The grouped time series. - group_design_matrix (xr.DataArray): The grouped design matrix.

cedalion.models.glm.design_matrix.hrf_regressors(
ts: cdt.NDTimeSeries,
stim: DataFrame,
basis_function: TemporalBasisFunction,
) → DesignMatrix[source]

Create regressors modelling the hemodynamic response to stimuli.

Parameters:

  • ts (NDTimeSeries) – Time series data.

  • stim (pd.DataFrame) – Stimulus DataFrame.

  • basis_function (TemporalBasisFunction) – TemporalBasisFunction object defining the HRF.

Returns:

A DataArray containing the regressors.

Return type:

regressors (xr.DataArray)

cedalion.models.glm.design_matrix.drift_regressors(
ts: cdt.NDTimeSeries,
drift_order,
) → DesignMatrix[source]

Create drift regressors.

Parameters:

  • ts (cdt.NDTimeSeries) – Time series data.

  • drift_order (int) – The highest polynomial order of the drift terms.

Returns:

A DataArray containing the drift regressors.

Return type:

xr.DataArray

cedalion.models.glm.design_matrix.build_stim_array(
time: ArrayLike,
onsets: ArrayLike,
durations: None | ArrayLike,
values: ArrayLike,
) → np.ndarray[source]

Build an array indicating active stimulus periods.

The resuting array values are set from values between onset and onset+duration and zero everywhere else.

Parameters:

  • time – the time axis

  • onsets – times of stimulus onsets

  • durations – either durations of each stimulus or None, in which case the stimulus duration is set to one sample.

  • values – Stimulus values.

Returns:

The array denoting

cedalion.models.glm.design_matrix.closest_short_channel_regressor(
ts_long: cdt.NDTimeSeries,
ts_short: cdt.NDTimeSeries,
geo3d: cdt.LabeledPointCloud,
)[source]

Create channel-wise regressors using the closest nearby short channel.

Parameters:

  • ts_long (NDTimeSeries) – Time series of long channels

  • ts_short (NDTimeSeries) – Time series of short channels

  • geo3d (LabeledPointCloud) – Probe geometry

Returns:

Channel-wise regressor

Return type:

regressors (xr.DataArray)

cedalion.models.glm.design_matrix.max_corr_short_channel_regressor(ts_long: cdt.NDTimeSeries, ts_short: cdt.NDTimeSeries)[source]

Create channel-wise regressors using the most correlated short channels.

For each long channel the short channel is selected that has the highest correleation coefficient in any wavelength or chromophore.

Parameters:

  • ts_long (NDTimeSeries) – time series of long channels

  • ts_short (NDTimeSeries) – time series of short channels

Returns:

channel-wise regressors

Return type:

xr.DataArray

cedalion.models.glm.design_matrix.average_short_channel_regressor(ts_short: cdt.NDTimeSeries)[source]

Create a regressor by averaging all short channels.

Parameters:

ts_short (NDTimeSeries) – time series of short channels

Returns:

regressors

Return type:

xr.DataArray

cedalion.models.glm.solve module

Solve the GLM model.

cedalion.models.glm.solve.fit(
ts: cdt.NDTimeSeries,
design_matrix: DesignMatrix,
noise_model: str = 'ols',
ar_order: int = 30,
max_jobs: int = -1,
verbose: bool = False,
)[source]

Fit design matrix to data.

Parameters:

  • ts – the time series to be modeled

  • design_matrix – DataArray with dims time, regressor, chromo

  • noise_model –

    specifies the linear regression model

    • ols: ordinary least squares

    • rls: recursive least squares

    • wls: weighted least squares

    • ar_irls: autoregressive iteratively reweighted least squares (Barker et al. [BAH13])

    • gls: generalized least squares

    • glsar: generalized least squares with autoregressive covariance structure

  • ar_order – order of the autoregressive model

  • max_jobs – controls the number of jobs in parallel execution. Set to -1 for all available cores. Set it to 1 to disable parallel execution.

  • verbose – display progress information if True.

Returns:

thetas as a DataArray

cedalion.models.glm.solve.predict(
ts: cdt.NDTimeSeries,
thetas: DataArray,
design_matrix: DesignMatrix,
) → cdt.NDTimeSeries[source]

Predict time series from design matrix and thetas.

Parameters:

  • ts (cdt.NDTimeSeries) – The time series to be modeled.

  • thetas (xr.DataArray) – The estimated parameters.

  • design_matrix (xr.DataArray) – DataArray with dims time, regressor, chromo

  • channel_wise_regressors (list[xr.DataArray]) – Optional list of design matrices,

  • dimension. (with additional channel)

Returns:

The predicted time series.

Return type:

prediction (xr.DataArray)

Module contents

Tools for describing fNIRS data with general linear models.