Package 'hrf'

(For prewhitening) Use the Akaike information criterion (AIC) to select AR model orders between 0 and ar_order? Default: FALSE.

(For prewhitening) The order of the autoregressive (AR) model to use for prewhitening. If 0, do not prewhiten. Default: 6.

For multi-session modeling, note that a single AR model is used; its coefficients will be the average estimate from each session.

(For prewhitening) The FWHM parameter for spatially smoothing the coefficient estimates for the AR model to use for prewhitening. Recall that $\sigma = \frac{FWHM}{2*sqrt(2*log(2)}$. Set to 0 to not smooth the estimates. Default: 5.

fMRI timeseries data in CIFTI format ("*.dtseries.nii"). For single-session analysis this can be a file path to a CIFTI file or a "xifti" object from the ciftiTools package. For multi-session analysis this can be a vector of file paths or a list of "xifti" objects.

If BOLD is a "xifti" object(s), the surfaces, if any, will be used for the spatial model. However, if surfL and surfR are provided, they will override any surfaces in BOLD.

Character vector indicating which brain structure(s) of BOLD to analyze: "left" cortex; "right" cortex; and/or "subcortical" structures. Or "all" to model all three. Default: c("left","right") (cortex only).

A numeric matrix, or a vector which will be converted to a single-column matrix.

A numeric matrix or data.frame, or a "BayesfMRI_design" object from make_design. Can also be an array where the third dimension is the same length as the number of data locations, to model each location with its own design.

A session-length list of $T \times V$ numeric BOLD data.

Tolerance for mean and variance of each data location. Locations which do not meet these thresholds are masked out of the analysis. Defaults: 1e-6.

Print messages counting how many locations are removed? Default: TRUE.

An $F \times 3$ matrix, where each row contains the vertex indices for a given triangular face in the mesh. $F$ is the number of faces in the mesh.

(Optional) Names of fields represented in design matrix.

Add DCT bases to nuisance to apply a temporal high-pass filter to the data, for detrending? hpf is the filter frequency. Use NULL to skip detrending. Detrending is strongly recommended for fMRI data, to help reduce the autocorrelation in the residuals, so NULL will induce a warning. Use "already" to disable the warning while skipping highpass filtering.

Using at least two DCT bases is as sufficient for detrending as using linear and quadratic drift terms in the nuisance matrix. So if DCT detrending is being used here, there is no need to add linear and quadratic drift terms to nuisance.

time vector (in units of seconds)

0 (default) for the HRF, 1 for the delay derivative of the HRF, or 2 for the dispersion derivative of the HRF.

delay of response. Default: 6

response dispersion. Default: 1

delay of undershoot. Default: 16/6 * a1 * sqrt(b1) = 16

dispersion of undershoot. Default: b1 = 1

scale of undershoot. Default: 1/6

onset of response. Default: 0

time vector (in seconds). Must be equally spaced.

delay of response. Default: 6

response dispersion. Default: 1

delay of undershoot. Default: 16/6*a1 = 16

dispersion of undershoot. Default: b1 = 1

scale of undershoot. Default: 1/6

onset of response (in seconds). Default: 0

time vector

0 (default) for the HRF, 1 for the first derivative of the HRF, or 2 for the second derivative of the HRF.

delay of response. Default: 6

response dispersion. Default: 0.9

delay of undershoot. Default: 12

dispersion of undershoot. Default: 0.9

scale of undershoot. Default: 0.35

The explanatory variables i.e. the task stimulus information, from which a design matrix will be constructed. This is a list where each entry represents a task as a matrix of onsets (first column) and durations (second column) for each stimuli (each row) of the task, in seconds. List names should be the task names. nTime and TR are required.

An example of a properly-formatted EVs is: on_s1 <- list(taskA=cbind(on=c(1,9,17), dr=rep(1,3)), taskB=cbind(on=c(3,27), dr=rep(5,2))). In this example, there are two tasks: the first has three 1s-long stimuli, while the second has two 5s-long stimuli.

the number of timepoints (volumes) in the task fMRI data.

the temporal resolution of the data, in seconds.

Controls the extent of HRF derivatives modeling.

Set to 0 to only model the main HRF regressor (default), and not include its derivatives; set to 1 to model the temporal derivative too; or, set to 2 to model both the temporal and dispersion derivatives. If dHRF==0, there is one design column (field) per task. If dHRF==1, there are two fields per task. And if dHRF==2, there are three fields per task.

If there are several tasks and dHRF>0, the total number of design matrix columns may exceed five, which may require large computation times with INLA. The analysis can be adjusted by modeling the derivatives as nuisance signals rather than as fields. To do so, move the corresponding columns from the design matrix to the nuisance argument for BayesGLM.

Upsample factor for convolving stimulus boxcar or stick function with canonical HRF. Default: 100.

Add task regressors indicating the onset and/or offset of each event block? Provide the names of the tasks as a character vector. All onsets (or offsets) across the specified tasks will be represented by one additional column in the design matrix. The task names must match the names of EVs. Can also be "all" to use all tasks.

Onsets/offset modeling is only compatible with a block design experiment. An error will be raised if the events in EVs do not have duration greater than one second.

Scale the columns of the design matrix? Default: TRUE.

Model the onsets (onsets_sep) or offsets (offsets_sep) separately for each task? Default: FALSE, to model all onsets together, or all offsets together, as a single field in the design.

Print diagnostic messages? Default: TRUE.

Additional arguments to HRF_calc.

A length $V$ logical vector indicating if each vertex is within the input mask.

Tolerance for mean and variance of each data location. Locations which do not meet these thresholds are masked out of the analysis. Default: 1e-6 for both.

fMRI timeseries data in CIFTI format ("*.dtseries.nii"). For single-session analysis this can be a file path to a CIFTI file or a "xifti" object from the ciftiTools package. For multi-session analysis this can be a vector of file paths or a list of "xifti" objects.

If BOLD is a "xifti" object(s), the surfaces, if any, will be used for the spatial model. However, if surfL and surfR are provided, they will override any surfaces in BOLD.

A 3D numeric array that is locations by fields by designs.

Character vector indicating which brain structure(s) of BOLD to analyze: "left" cortex; "right" cortex; and/or "subcortical" structures. Or "all" to model all three. Default: c("left","right") (cortex only).

Temporal resolution of the data, in seconds.

For cortex spatial model. The number of vertices to which each cortical surface should be resampled, or NULL to not resample.

For computational feasibility, a value of 10000 (default) or lower is recommended for Bayesian spatial modeling. If Bayes=FALSE, resamp_res can be set to NULL for full-resolution classical modeling.

Add DCT bases to nuisance to apply a temporal high-pass filter to the data, for detrending? hpf is the filter frequency. Use NULL to skip detrending. Detrending is strongly recommended for fMRI data, to help reduce the autocorrelation in the residuals, so NULL will induce a warning. Use "already" to disable the warning while skipping highpass filtering.

Using at least two DCT bases is as sufficient for detrending as using linear and quadratic drift terms in the nuisance matrix. So if DCT detrending is being used here, there is no need to add linear and quadratic drift terms to nuisance.

(Optional) A $T \times N_{nuis}$ matrix of nuisance signals, where $T$ is the number of timepoints and $N$ is the number of nuisance signals, or a list of these for multi-session analysis. Nuisance signals are regressed from the fMRI data and design matrix prior to GLM computation. Nuisance signals can include motion regressors, HRF derivatives not being modeled as tasks, and other sources of noise.

Detrending/high-pass filtering is accomplished by adding DCT bases to the nuisance matrix; see the parameters hpf and DCT.

Do not add spike regressors for scrubbing to the nuisance matrix. Rather, provide these in scrub so that their corresponding timepoints are also removed from the BOLD data after nuisance regression.

TO DO

1 (default) to print occasional updates during model computation; 2 for occasional updates as well as running INLA in verbose mode (if Bayes), or 0 for no printed updates.

Tolerance for mean and variance of each data location. Locations which do not meet these thresholds are masked out of the analysis. Default: 1e-6 for both.

Session-length list of numeric matrices/arrays, each with volumes along the first dimension.

TO DO

1 (default) to print occasional updates during model computation; 2 for occasional updates as well as running INLA in verbose mode (if Bayes), or 0 for no printed updates.

Tolerance for mean, variance and SNR of each data location. Locations which do not meet these thresholds are masked out of the analysis. Default: 1e-6 for mean and variance, 50 for SNR.

(Optional) A $T \times N_{nuis}$ matrix of nuisance signals, where $T$ is the number of timepoints and $N$ is the number of nuisance signals, or a list of these for multi-session analysis. Nuisance signals are regressed from the fMRI data and design matrix prior to GLM computation. Nuisance signals can include motion regressors, HRF derivatives not being modeled as tasks, and other sources of noise.

Detrending/high-pass filtering is accomplished by adding DCT bases to the nuisance matrix; see the parameters hpf and DCT.

Do not add spike regressors for scrubbing to the nuisance matrix. Rather, provide these in scrub so that their corresponding timepoints are also removed from the BOLD data after nuisance regression.

The timepoints by fields design matrix or data.frame.

"lineplot" (default) or "imageplot".

Additional arguments to plot_design_line or plot_design_image.

The name of a ColorBrewer palette (see RColorBrewer::brewer.pal.info and colorbrewer2.org), the name of a viridisLite palette, or a character vector of colors. Default: "Set1".

Parameters for ggplot2::geom_line. Defaults: "solid" linetype, 0.7 linewidth and 0.8 alpha. linetype can also be a vector of options with length matching the number of fields in design.

An object of class "BfMRI_design".

Additional arguments to plot_design.

For cortex spatial model. The number of vertices to which each cortical surface should be resampled, or NULL to not resample.

For computational feasibility, a value of 10000 (default) or lower is recommended for Bayesian spatial modeling. If Bayes=FALSE, resamp_res can be set to NULL for full-resolution classical modeling.

Controls scaling the BOLD response at each location.

"mean":

Scale the data to percent local signal change.

"sd":

Scale the data by local standard deviation.

"none":

Center the data but do not scale it.

(Optional) A $T \times N_{scrub}$ matrix of spike regressors (one 1 value at the timepoint to scrub, and 0 for all other values), or a logical vector indicating the timepoints to scrub (TRUE to scrub, and FALSE to keep). For multi-session data, a session-length list of such matrices or logical vectors.

The spike regressors will be included in the nuisance regression, and afterwards the timepoints indicated in scrub will be removed from the BOLD data and design matrix.

The names of the task-fMRI BOLD sessions, for multi-session analysis. If not provided here, will be inferred from names(BOLD), inferred from names(design), or generated automatically, in that order.

Object of class "BfMRI_design".

further arguments passed to or from other methods.

Object of class "summary.BfMRI_design".

For cortex spatial model. Left and right cortex surface geometry in GIFTI format ("*.surf.gii"). These can be a file path to a GIFTI file or a "surf" object from ciftiTools.

Surfaces can alternatively be provided through the $surf metadata in BOLD if it is "xifti" data. If neither are provided, by default the HCP group-average fs_LR inflated surfaces included in ciftiTools will be used for the cortex spatial model.

Temporal resolution of the data, in seconds.

1 (default) to print occasional updates during model computation; 2 for occasional updates as well as running INLA in verbose mode (if Bayes), or 0 for no printed updates.