Package 'autohrf' reference manual

Title:	Automated Generation of Data-Informed GLM Models in Task-Based fMRI Data Analysis
Description:	Analysis of task-related functional magnetic resonance imaging (fMRI) activity at the level of individual participants is commonly based on general linear modelling (GLM) that allows us to estimate to what extent the blood oxygenation level dependent (BOLD) signal can be explained by task response predictors specified in the GLM model. The predictors are constructed by convolving the hypothesised timecourse of neural activity with an assumed hemodynamic response function (HRF). To get valid and precise estimates of task response, it is important to construct a model of neural activity that best matches actual neuronal activity. The construction of models is most often driven by predefined assumptions on the components of brain activity and their duration based on the task design and specific aims of the study. However, our assumptions about the onset and duration of component processes might be wrong and can also differ across brain regions. This can result in inappropriate or suboptimal models, bad fitting of the model to the actual data and invalid estimations of brain activity. Here we present an approach in which theoretically driven models of task response are used to define constraints based on which the final model is derived computationally using the actual data. Specifically, we developed 'autohrf' — a package for the 'R' programming language that allows for data-driven estimation of HRF models. The package uses genetic algorithms to efficiently search for models that fit the underlying data well. The package uses automated parameter search to find the onset and duration of task predictors which result in the highest fitness of the resulting GLM based on the fMRI signal under predefined restrictions. We evaluate the usefulness of the 'autohrf' package on publicly available datasets of task-related fMRI activity. Our results suggest that by using 'autohrf' users can find better task related brain activity models in a quick and efficient manner.
Authors:	Jure Demšar [cre, aut], Nina Purg [aut], Grega Repovš [aut]
Maintainer:	Jure Demšar <[email protected]>
License:	GPL (>=3)
Version:	1.1.3
Built:	2025-02-15 04:40:45 UTC
Source:	https://github.com/demsarjure/autohrf

autohrf

Description

A function that automatically finds the parameters of model's that best match the underlying data.

Usage

autohrf(
  d,
  model_constraints,
  tr,
  roi_weights = NULL,
  allow_overlap = FALSE,
  population = 100,
  iter = 100,
  mutation_rate = 0.1,
  mutation_factor = 0.05,
  elitism = 0.1,
  hrf = "spm",
  t = 32,
  p_boynton = c(2.25, 1.25, 2),
  p_spm = c(6, 16, 1, 1, 6, 0),
  f = 100,
  cores = NULL,
  autohrf = NULL,
  verbose = TRUE
)
autohrf(
  d,
  model_constraints,
  tr,
  roi_weights = NULL,
  allow_overlap = FALSE,
  population = 100,
  iter = 100,
  mutation_rate = 0.1,
  mutation_factor = 0.05,
  elitism = 0.1,
  hrf = "spm",
  t = 32,
  p_boynton = c(2.25, 1.25, 2),
  p_spm = c(6, 16, 1, 1, 6, 0),
  f = 100,
  cores = NULL,
  autohrf = NULL,
  verbose = TRUE
)

Arguments

`d`	A dataframe with the signal data: roi, t and y. ROI is the name of the region, t is the timestamp and y the value of the signal.
`model_constraints`	A list of model specifications to use for fitting. Each specification is represented as a data frame containing information about it (event, start_time, end_time, min_duration and max_duration).
`tr`	MRI's repetition time.
`roi_weights`	A data frame with ROI weights: roi, weight. ROI is the name of the region, weight a number that defines the importance of that roi, the default weight for a ROI is 1. If set to 2 for a particular ROI that ROI will be twice as important.
`allow_overlap`	Whether to allow overlap between events.
`population`	The size of the population in the genetic algorithm.
`iter`	Number of iterations in the genetic algorithm.
`mutation_rate`	The mutation rate in the genetic algorithm.
`mutation_factor`	The mutation factor in the genetic algorithm.
`elitism`	The degree of elitism (promote a percentage of the best solutions) in the genetic algorithm.
`hrf`	Method to use for HRF generation.
`t`	The t parameter for Boynton or SPM HRF generation.
`p_boynton`	Parameters for the Boynton's HRF.
`p_spm`	Parameters for the SPM HRF.
`f`	Upsampling factor.
`cores`	Number of cores to use for parallel processing. Set to the number of provided model constraints by default.
`autohrf`	Results of a previous autohrf run to continue.
`verbose`	Whether to print progress of the fitting process.

Value

A list containing model fits for each of the provided model specifications.

Examples

# prepare model specs
model3 <- data.frame(
  event        = c("encoding", "delay", "response"),
  start_time   = c(0,          2.65,     12.5),
  end_time     = c(3,          12.5,     16)
)

model4 <- data.frame(
  event        = c("fixation", "target", "delay", "response"),
  start_time   = c(0,          2.5,      2.65,    12.5),
  end_time     = c(2.5,        3,        12.5,    15.5)
)

model_constraints <- list(model3, model4)

# run autohrf
df <- flanker
autofit <- autohrf(df, model_constraints, tr = 2.5,
                   population = 2, iter = 2, cores = 1)

# prepare model specs
model3 <- data.frame(
  event        = c("encoding", "delay", "response"),
  start_time   = c(0,          2.65,     12.5),
  end_time     = c(3,          12.5,     16)
)

model4 <- data.frame(
  event        = c("fixation", "target", "delay", "response"),
  start_time   = c(0,          2.5,      2.65,    12.5),
  end_time     = c(2.5,        3,        12.5,    15.5)
)

model_constraints <- list(model3, model4)

# run autohrf
df <- flanker
autofit <- autohrf(df, model_constraints, tr = 2.5,
                   population = 2, iter = 2, cores = 1)

Datasets for autohrf examples Example datasets for use in autohrf examples and vignettes. The datasets were extracted from the internal Mind and Brain Lab's (MBLab, http://www.mblab.si repository. MBLab is a research lab at the Faculty of Arts, Department of Psychology, University of Ljubljana, Slovenia.

Description

Datasets for autohrf examples Example datasets for use in autohrf examples and vignettes. The datasets were extracted from the internal Mind and Brain Lab's (MBLab, http://www.mblab.si repository. MBLab is a research lab at the Faculty of Arts, Department of Psychology, University of Ljubljana, Slovenia.