lazyfmri | utility package for fMRI analyses

This package contains utility functions used for routines such as GLMs, deconvolution, and plotting often used in the linescanning-repository. This is separate to make functions more easily available without installing the entire pipeline.

Installation

pip install git+https://github.com/gjheij/lazyfmri

Functionalities

The main functions of this package include plotting, estimation of the hemodynamic response function (HRF) through various methods, and basic preprocessing of 2D fMRI data.

I have been using these functions for several of my publications:

• "A selection and targeting framework of cortical locations for line-scanning fMRI"
• "Quantitative MRI at 7-Tesla reveals novel frontocortical myeloarchitecture anomalies in major depressive disorder

I/O

The Dataset-class can parse several file types typically used in fMRI research:

• Functional files: *.mat, *.nii.gz, or *.gii and outputs a 2D dataframe (time, datapoints) indexed by given (or extracted) subject/run/task IDs. These IDs can either be given or extracted from the filename if the filename follows the BIDS-format.

• Experiment files: this package is designed to work with the *.tsv-output from the exptools package. This is a wrapper around psychopy that divides the experiment in several phases (e.g., ITI and stimulus period), which can be extracted. Similar to the functional files, the output of this is a dataframe indexed by subject/run/task ID:

• Eyetracker files: this package is designed to work with the *.edf-output from EyeLink from SR research. It is required that the system has access to the edf2asc command. The package then uses hedfpy to parse the eyetracking data into a dataframe indexed by subject/run/task/eye.

HRF estimation

The nature of the output makes the output directly compatible with HRF estimation routines including deconvolution, parameter estimation, and epoching. Given that all these different functions output similar dataframes, they are all compatible with the HRFMetrics-class. This extracts a bunch of relevant metrics from your estimated HRF profiles:

Deconvolution

Deconvolution is performed using nideconv. Several basis sets are available:

allowed_basis_sets = [
    "fir",      # most flexible, use "regressors='tr'" to use 1 regressor per TR
    "fourier",  # smooth basis set
    "dct",      # smooth basis set without wobbly patterns near overshoot
    "legendre", # never used, really
    "canonical_hrf",    # standard glover HRF
    "canonical_hrf_with_time_derivative",   # standard+time derivative
    "canonical_hrf_with_time_derivative_dispersion" # standard + time/dispersion derivative
]

Parameter fitting

Similar to pRF, HRFs can be estimated using an optimizing algorithm. Starting from the standard HRF parameters, the optimizers searches for the best combination of parameters. This gives slightly more degrees-of-freedom compared to the canonical HRF (with derivatives) while maintaining smooth functions (FIR can go crazy on noisy data such as line-scanning data). For now, it does the process while trying parameters that generate both a positive and negative HRF, so this can take a long time..

Epoching

The OG of HRF estimation. If you ITIs are long enough, you might be able to extract data from a particular time window around the stimulus onset. The nice thing about this is that it's very close to the data and doesn't rely on any optimizing algorithm. On the other hand, the number of trials are inherently limited as they need to be spaced apart far enough to allow the HRF to return to baseline.

Plotting

This package basically represents a wrapper around seaborn, which is a wrapper around matplotlib. It goes a few steps further regarding cosmetics such as axis/tick thickness, ratio between font size/title size, shading of error measurements, and much more. For now, it includes wrappers for simple line plots, bar plots, and correlation plots. Most notably, it uses pingouin as statistical backend to estimate significance levels in bar plots and draws significance bars based on the outcome. All arguments from pingouin can be passed. It will run non-parametric or parametric tests depending on the variability and spread in your data.

Preprocessing

There are also a bunch of preprocessing functions tailored for the dataframes that are outputted by the Dataset-class. These include highpass (DCT)/lowpass (Savitsky-Golay) filtering, ICA, or power spectra. Most notably, given a dataframe representing and one representing the onsets, you can regress out certain events from the timecourses (such as responses or blinks).