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.

cedalion.models.glm.design_matrix.make_design_matrix( ts_long: cdt.NDTimeSeries, ts_short: cdt.NDTimeSeries | None, stim: pd.DataFrame, geo3d: cdt.LabeledPointCloud, basis_function: TemporalBasisFunction, drift_order: int | None, short_channel_method: str | None, )[source]

Generate the design matrix for the GLM.

Parameters:

ts_long (cdt.NDTimeSeries) – Time series of long distance channels.
ts_short (cdt.NDTimeSeries) – Time series of short distance channels.
stim (DataFrame) – Stimulus DataFrame
geo3d (cdt.LabeledPointCloud) – Probe geometry
basis_function (TemporalBasisFunction) – the temporal basis function(s) to model the HRF.
drift_order (int) – If not None specify the highest polynomial order of the drift terms.
short_channel_method (str) –
Specifies the method to add short channel information to the design matrix Options:

’closest’: Use the closest short channel ‘max_corr’: Use the short channel with the highest correlation ‘mean’: Use the average of all short channels.

Returns:

A tuple containing the global design_matrix and a list of channel-wise regressors.

cedalion.models.glm.design_matrix.make_drift_regressors( ts: cdt.NDTimeSeries, drift_order, ) → DataArray[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.pad_time_axis(time: ArrayLike, onsets: ArrayLike)[source]

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.make_hrf_regressors( ts: cdt.NDTimeSeries, stim: DataFrame, basis_function: TemporalBasisFunction, )[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.closest_short_channel( ts_long: cdt.NDTimeSeries, ts_short: cdt.NDTimeSeries, geo3d: cdt.LabeledPointCloud, )[source]

Create channel-wise regressors use 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(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(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: DataArray, channel_wise_regressors: list[DataArray] | None = None, noise_model='ols', )[source]

Fit design matrix to data.

Parameters:

ts – the time series to be modeled
design_matrix – DataArray with dims time, regressor, chromo
channel_wise_regressors – optional list of design matrices, with additional channel dimension
noise_model – must be ‘ols’ for the moment

Returns:

thetas as a DataArray

cedalion.models.glm.solve.predict( ts: cdt.NDTimeSeries, thetas: DataArray, design_matrix: DataArray, channel_wise_regressors: list[DataArray] | None = None, ) → 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)

cedalion.models.glm.solve.iter_design_matrix( ts: cdt.NDTimeSeries, design_matrix: DataArray, channel_wise_regressors: list[DataArray] | None = None, channel_groups: list[int] | None = None, )[source]

Iterate over the design matrix and yield the design matrix for each group.

Parameters:

ts (cdt.NDTimeSeries) – The time series to be modeled.
design_matrix (xr.DataArray) – DataArray with dims time, regressor, chromo.
channel_wise_regressors (list[xr.DataArray] | None, optional) – Optional list of design matrices, with additional channel dimension.
channel_groups (list[int] | None, optional) – Optional list of channel groups.

Yields:

tuple –

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.

Module contents

Tools for describing fNIRS data with general linear models.