FIRDeconvolution Package¶

FIRDeconvolution is a python class that performs finite impulse response fitting on time series data, in order to estimate event-related signals. These signals can come from any source, but the most likely source in our experience is some sort of physiological signal such as fMRI voxels, galvanic skin response, (GSR) or pupil size recordings.

The repo for FIRDeconvolution is at https://github.com/tknapen/FIRDeconvolution, and the GitHub FIRDeconvolution website is located at http://tknapen.github.io/FIRDeconvolution/.

class FIRDeconvolution.FIRDeconvolution(signal, events, event_names=[], covariates=None, durations=None, sample_frequency=1.0, deconvolution_interval=[-0.5, 5], deconvolution_frequency=None)¶

Bases: object

Instances of FIRDeconvolution can be used to perform FIR fitting on time-courses. Since many of the computation’s parameters are set in the constructor, it is likely easiest to create new instances for each separate analysis you run.

FIRDeconvolution takes a signal and events in order to perform FIR fitting of the event-related responses in the signal. Most settings for the analysis are set here.

param signal:	input signal.
type signal:	numpy array, (nr_signals x nr_samples)
param events:	event occurrence times.
type events:	list of numpy arrays, (nr_event_types x nr_events_per_type)
param event_names:
	event names.
type events:	list of strings, if empty, event names will be string representations of range(nr_event_types)
param covariates:
	covariates belonging to event_types. If None, covariates with a value of 1 for all events are created and used internally.
type covariates:
	dictionary, with keys “event_type.covariate_name” and values numpy arrays, (nr_events)
param durations:
	durations belonging to event_types. If None, durations with a value of 1 sample for all events are created and used internally.
type durations:	dictionary, with keys “event_type” and values numpy arrays, (nr_events)
param sample_frequency:
	input signal sampling frequency in Hz, standard value: 1.0
type sample_frequency:
	float
param deconvolution_interval:
	interval of time around the events for which FIR fitting is performed.
type deconvolution_interval:
	list: [float, float]
param deconvolution_frequency:
	effective frequency in Hz at which analysis is performed. If None, identical to the sample_frequency.
type deconvolution_frequency:
	float
returns:	Nothing, but the created FIRDeconvolution object.

add_continuous_regressors_to_design_matrix(regressor)¶

add_continuous_regressors_to_design_matrix appends continuously sampled regressors to the existing design matrix. One uses this addition to the design matrix when one expects the data to contain nuisance factors that aren’t tied to the moments of specific events. For instance, in fMRI analysis this allows us to add cardiac / respiratory regressors, as well as tissue and head motion timecourses to the designmatrix.

Parameters:	regressor (numpy array, with shape equal to (nr_regressors, self.resampled_signal.shape[-1])) – the signal to be appended to the design matrix.

betas_for_cov(covariate='0')¶

betas_for_cov returns the beta values (i.e. IRF) associated with a specific covariate.

Parameters:	covariate (string) – name of covariate.

betas_for_events()¶

betas_for_events creates an internal self.betas_per_event_type array, of (nr_covariates x self.devonvolution_interval_size), which holds the outcome betas per event type,in the order generated by self.covariates.keys()

bootstrap_on_residuals(nr_repetitions=1000)¶

bootstrap_on_residuals bootstraps, by shuffling the residuals. bootstrap_on_residuals should only be used on single-channel data, as otherwise the memory load might increase too much. This uses the lstsq backend regression for a single-pass fit across repetitions. Please note that shuffling the residuals may change the autocorrelation of the bootstrap samples relative to that of the original data and that may reduce its validity. Reference: https://en.wikipedia.org/wiki/Bootstrapping_(statistics)#Resampling_residuals

Parameters:	nr_repetitions (int) – number of repetitions for the bootstrap.

calculate_rsq()¶

calculate_rsq calculates coefficient of determination, or r-squared, defined here as 1.0 - SS_res / SS_tot. rsq is only calculated for those timepoints in the data for which the design matrix is non-zero.

create_design_matrix()¶

create_design_matrix calls create_event_regressors for each of the covariates in the self.covariates dict. self.designmatrix is created and is shaped (nr_regressors, self.resampled_signal.shape[-1])

create_event_regressors(event_times_indices, covariates=None, durations=None)¶

create_event_regressors creates the part of the design matrix corresponding to one event type.

Parameters:

event_times_indices (numpy array, (nr_events)) – indices in the resampled data, on which the events occurred. covariates (numpy array, (nr_events)) – covariates belonging to this event type. If None, covariates with a value of 1 for all events are created and used internally. durations (numpy array, (nr_events)) – durations belonging to this event type. If None, durations with a value of 1 sample for all events are created and used internally.

Returns:

This event type’s part of the design matrix.

predict_from_design_matrix(design_matrix)¶

predict_from_design_matrix predicts signals given a design matrix.

Parameters:	design_matrix (numpy array, (nr_samples x betas.shape)) – design matrix from which to predict a signal.
Returns:	predicted signal(s)
Return type:	numpy array (nr_signals x nr_samples)

regress(method='lstsq')¶

regress performs linear least squares regression of the designmatrix on the data.

Parameters:	method (string, one of [‘lstsq’, ‘sm_ols’]) – method, or backend to be used for the regression analysis.
Returns:	instance variables ‘betas’ (nr_betas x nr_signals) and ‘residuals’ (nr_signals x nr_samples) are created.

ridge_regress(cv=20, alphas=None)¶

perform k-folds cross-validated ridge regression on the design_matrix. To be used when the design matrix contains very collinear regressors. For cross-validation and ridge fitting, we use sklearn’s RidgeCV functionality. Note: intercept is not fit, and data are not prenormalized.

Parameters:	cv (int, standard = 20) – cross-validated folds, inherits RidgeCV cv argument’s functionality. alphas (numpy array, from >0 to 1.) – values of penalization parameter to be traversed by the procedure, inherits RidgeCV cv argument’s functionality. Standard value, when parameter is None, is np.logspace(7, 0, 20)
Returns:	instance variables ‘betas’ (nr_betas x nr_signals) and ‘residuals’ (nr_signals x nr_samples) are created.