Package {fMRItools}

Wide numeric data matrix (T observations by V variables, T << V). For example, if X represents an fMRI run, T should be the number of timepoints and V should be the number of brainordinate vertices/voxels.

Or, a 4D array or NIFTI or file path to a NIFTI (I by J by K by T observations), in which case ROI_data must be provided. (The vectorized data will be T timepoints by V_{in-mask} voxels)

Or, a ciftiTools "xifti" object or a file path to a CIFTI (The vectorized data will be T timepoints by V_{left+right+sub} grayordinates).

Indicates the data ROI. Allowed arguments depend on X:

If X is a matrix, this must be a length V logical vector, where the data ROI is indicated by TRUE values. If "infer" (default), all columns of X will be included in the data ROI (rep(TRUE, V)).

If X is an array or NIFTI, this must be either a vector of values to expect for out-of-mask voxels in X, or a (file path to a) 3D NIFTI. In the latter case, each of the volume dimensions should match the first three dimensions of X. Voxels in the data ROI should be indicated by TRUE and all other voxels by FALSE. If "infer" (default), will be set to c(0, NA, NaN) (include all voxels which are not constant 0, NA, or NaN).

If X is a "xifti" this must be the brainstructures argument to ciftiTools::read_cifti. If "infer" (default), brainstructures will be set to "all" (use both left and right cortex vertices, and subcortical voxels).

If NULL, the data ROI will be empty. This is useful for obtaining just the noise ROI, if the data and noise are located in separate files.

Indicates the noise ROIs for aCompCor. Should be a list where each entry corresponds to a distinct noise ROI. The names of the list should be the ROI names, e.g. "white_matter" and "csf". The expected formats of the list entries depends on X:

For all types of X, ROI_noise entries can be a matrix of noise ROI data. The matrix should have T rows, with each column being a data location's timeseries.

If X is a matrix, entries can also indicate a noise ROI within X. These entries must be a length V logical vector with TRUE values indicating locations in X within that noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

If X is an array or NIFTI, entries can also indicate a noise ROI within X. These entries must be a logical array or (file path to) a 3D NIFTI with the same spatial dimensions as X, and with TRUE values indicating voxels inside the noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

(If X is a "xifti", entries must be data matrices, since no grayordinate locations in X are appropriate noise ROIs).

The number of principal components to compute for each noise ROI. Alternatively, values between 0 and 1, in which case they will represent the minimum proportion of variance explained by the PCs used for each noise ROI. The smallest number of PCs will be used to achieve this proportion of variance explained.

Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: 5 (compute the top 5 PCs for each noise ROI).

The number of voxel layers to erode the noise ROIs by. Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: NULL, which will use a value of 0 (do not erode the noise ROIs). Note that noise erosion can only be performed if the noise ROIs are volumetric.

Center the columns of the noise ROI data by their medians, and scale by their MADs? Default: TRUE for both. Note that this argument affects the noise ROI data and not the data that is being cleaned with aCompCor. Centering and scaling of the data being cleaned can be done after this function call.

Nuisance signals to regress from the noise ROIs before computing the PCs. Should be a T by P numeric matrix where P represents the number of preliminary nuisance signals. Default: NULL (do not do any preliminary nuisance regression).

Nuisance signals to regress from each data column in addition to the noise ROI PCs. Should be a T by N numeric matrix where N represents the number of nuisance signals. To not perform any nuisance regression set this argument to NULL, 0, or FALSE. Default: NULL.

"xifti" (or file path to the CIFTI) from which the noise ROI components will be regressed. In the HCP, the corresponding file is e.g. "../Results/rfMRI_REST1_LR/rfMRI_REST1_LR_Atlas_MSMAll.dtseries.nii".

The noise components, as returned by CompCor_HCP_calc for a single idx (i.e. a list with an entry named "PCs").

A numeric vector indicating the timepoints of cii to use, or NULL (default) to use all timepoints. This should match the timepoints used to compute noise.

Choose among "left", "right", and "subcortical". Only used if cii is a file path. Default: c("left", "right") (cortical data only)

Add DCT bases to the nuisance regression? Use an integer to indicate the number of cosine bases. Use 0 (default) to forgo detrending.

An intercept is always included in the regression, so the data does not need to be centered.

A matrix of nuisance signals to add to the nuisance regression. Should have T rows. NULL to not add additional nuisance regressors (default).

Should occasional updates be printed? Default: FALSE.

I by J by K by T NIFTI object or array (or file path to the NIFTI) which contains whole-brain data, including the noise ROIs. In the HCP, the corresponding file is e.g. "../Results/rfMRI_REST1_LR/rfMRI_REST1_LR.nii.gz"

I by J by K NIFTI object or array (or file path to the NIFTI) which contains the corresponding labels to each voxel in nii. Values should be according to this table: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT In the HCP, the corresponding file is "ROIs/Atlas_wmparc.2.nii.gz".

A list of numeric vectors. Each entry should represent labels in nii_labels belonging to a single noise ROI, named by that entry's name. Or, this can be a character vector of at least one of the following: "wm_cort" (cortical white matter), "wm_cblm" (cerebellar white matter), "csf" (cerebrospinal fluid). In the latter case, these labels will be used:

"wm_cort"

c(3000:4035, 5001, 5002)

"wm_cblm"

c(7, 46)

"csf"

c(4, 5, 14, 15, 24, 31, 43, 44, 63, 250, 251, 252, 253, 254, 255))

These default ROIs are based on this forum post: https://www.mail-archive.com/hcp-users@humanconnectome.org/msg00931.html

Default: c("wm_cort", "csf")

The number of principal components to compute for each noise ROI. Alternatively, values between 0 and 1, in which case they will represent the minimum proportion of variance explained by the PCs used for each noise ROI. The smallest number of PCs will be used to achieve this proportion of variance explained.

Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: 5 (compute the top 5 PCs for each noise ROI).

The number of voxel layers to erode the noise ROIs by. Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: NULL, which will use a value of 0 (do not erode the noise ROIs).

A numeric vector indicating the timepoints to use, or NULL (default) to use all timepoints. (Indexing begins with 1, so the first timepoint has index 1 and the last has the same index as the length of the scan.)

Center the columns of the noise ROI data by median, and scale the columns of the noise ROI data by MAD? Default: TRUE for both.

Nuisance signals to regress from the noise ROIs before computing the PCs (see CompCor). A T by P numeric matrix, where T is the number of timepoints in idx. Default: NULL (do not do any preliminary nuisance regression).

Should occasional updates be printed? Default: FALSE.

The T \times V or V \times T data matrix, where T is the number of timepoints. (If square, it is assumed to be T \times V.) The data does not need to be centered, since an intercept is always included in the regression.

The noise PCs: a list with an entry named "PCs" which is a list of T by Q_i matrices, one for each noise ROI. For example, the result of CompCor_HCP_calc or the "noise" entry of the result of CompCor.

Add DCT bases to the nuisance regression? Use an integer to indicate the number of cosine bases. Use 0 (default) to forgo detrending.

Nuisance signals to regress from each data column in addition to the noise ROI PCs. Should be a T by N numeric matrix where N represents the number of nuisance signals. To not perform any additional nuisance regression set this argument to NULL, 0, or FALSE. Default: NULL.

The data vector

The tall numeric matrix for which to compute the PCA. For fMRI data, X should be V brain locations by T timepoints.

Center the columns of X? Default: TRUE. Set to FALSE if already centered. Centered data is required to compute PCA.

Number of latent dimensions to estimate. If NULL (default), estimated using PESEL (Sobczyka et al. 2020).

Maximal number of principal components for automatic dimensionality selection with PESEL. Default: 100.

Number of principal directions to obtain. Default: 0. Can also be "Q" to set equal to the value of Q. Note that setting this value less than Q does not speed up computation time, but does save on memory. Note that the directions will be with respect to X, not its covariance matrix.

A vector of values for the upper triangular elements of the desired square matrix.

The values to put on the diagonal, or "x" (default) if x includes the diagonal values.

The values to put on the lower triangle, or "x" (default) to use the upper triangular values such that the result is symmetric. (LT should not contain the diagonal values, which are provided with diag or x).

The data vector or matrix

Is a logical vector or matrix also acceptable? Default: TRUE.

The data vector or matrix

The object to coerce to a matrix

Return metadata too? Default: FALSE.

For CIFTI format input only. Sort subcortex by labels? Default: FALSE (sort by array index).

Return the data matrix in T \times V form? Default: TRUE. If FALSE, return in V \times T form instead. Using this argument may be faster than transposing after the function call.

Print updates? Default: FALSE.

If x is a file path, additional arguments to the function used to read in x can be specified here. For example, if x is a path to a CIFTI file, ... might specify which idx and brainstructures to read in.

A numeric matrix, with each column being a timeseries to apply the stopband filter. For fMRI data, X should be T timepoints by V brain locations.

The time step between adjacent rows of x, in seconds

The frequency limits for the filter, in Hz. f1 < f2

The amount of attenuation of the stopband ripple, in dB

The T \times V numeric data matrix, or a "xifti" object. In the plot, the T index will increase from left to right, and the V will increase from top to bottom.

Sets blackpoint at the qcut quantile, and the whitepoint at the 1-qcut quantile. Default: .1. This is equivalent to setting the color range between the 10% and 90% quantiles. The quantiles are computed across the entire data matrix after any centering or scaling.

Must be between 0 and .49. If 0 or NULL (default), do not clamp the data values.

A .pdf (highly recommended) or .png file path to write the carpetplot to. If NULL (default), return the plot directly instead of writing a file.

Center and scale the data? If x is fMRI data which has not otherwise been centered or scaled, it is recommended to center but not scale it (default).

"gray255" (default) will use a grayscale color ramp from black to white. Otherwise, this should be a character vector of color names to use.

Colors will be assigned from the lowest to the highest data value, after any clamping of the data values by qcut.

If x is a "xifti" object with subcortical data, should the voxels be sorted by structure alphabetically? Default: TRUE.

Additional arguments to pdf or png, such as width and height.

List of data matrices

Center and scale the data? If x is fMRI data which has not otherwise been centered or scaled, it is recommended to center but not scale it (default).

Sets blackpoint at the qcut quantile, and the whitepoint at the 1-qcut quantile. Default: .1. This is equivalent to setting the color range between the 10% and 90% quantiles. The quantiles are computed across the entire data matrix after any centering or scaling.

Must be between 0 and .49. If 0 or NULL (default), do not clamp the data values.

Match the scales of the carpetplots? Default: TRUE.

Equivalent number of data locations for size of gap between carpetplots. Default: zero (no gap).

Additional arguments to carpetplot

The data FORMAT

The data matrix. Its columns will be centered.

"Beach" (default; blue to white to red), "Sand" (white to red), or "Water" (white to blue).

The sparse coordinate list. Should be a "data.frame" or matrix with voxels along the rows and three or four columns. The first three columns should be integers indicating the spatial coordinates of the voxel. If the fourth column is present, it will be the value used for that voxel. If it is absent, the value will be TRUE or 1 if fill is not one of those values, and FALSE or 0 if fill is. The data type will be the same as that of fill. The fourth column must be logical or numeric.

Logical or numeric fill value for the volume. Default: FALSE.

The vectorized upper triangular correlation matrix.

The value to put on the diagonals of the correlation matrix. Default: NA.

(Optional) row/column names.

(Optional) new index order.

Set the upper triangle to NA? Default: FALSE.

The numeric 3D array to crop.

Wide numeric data matrix (T observations by V variables, T << V). For example, if X represents an fMRI run, T should be the number of timepoints and V should be the number of brainordinate vertices/voxels.

Or, a 4D array or NIFTI or file path to a NIFTI (I by J by K by T observations), in which case ROI_data must be provided. (The vectorized data will be T timepoints by V_{in-mask} voxels)

Or, a ciftiTools "xifti" object or a file path to a CIFTI (The vectorized data will be T timepoints by V_{left+right+sub} grayordinates).

Indicates the data ROI. Allowed arguments depend on X:

If X is a matrix, this must be a length V logical vector, where the data ROI is indicated by TRUE values. If "infer" (default), all columns of X will be included in the data ROI (rep(TRUE, V)).

If X is an array or NIFTI, this must be either a vector of values to expect for out-of-mask voxels in X, or a (file path to a) 3D NIFTI. In the latter case, each of the volume dimensions should match the first three dimensions of X. Voxels in the data ROI should be indicated by TRUE and all other voxels by FALSE. If "infer" (default), will be set to c(0, NA, NaN) (include all voxels which are not constant 0, NA, or NaN).

If X is a "xifti" this must be the brainstructures argument to ciftiTools::read_cifti. If "infer" (default), brainstructures will be set to "all" (use both left and right cortex vertices, and subcortical voxels).

If NULL, the data ROI will be empty. This is useful for obtaining just the noise ROI, if the data and noise are located in separate files.

Indicates the noise ROIs for aCompCor. Should be a list where each entry corresponds to a distinct noise ROI. The names of the list should be the ROI names, e.g. "white_matter" and "csf". The expected formats of the list entries depends on X:

For all types of X, ROI_noise entries can be a matrix of noise ROI data. The matrix should have T rows, with each column being a data location's timeseries.

If X is a matrix, entries can also indicate a noise ROI within X. These entries must be a length V logical vector with TRUE values indicating locations in X within that noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

If X is an array or NIFTI, entries can also indicate a noise ROI within X. These entries must be a logical array or (file path to) a 3D NIFTI with the same spatial dimensions as X, and with TRUE values indicating voxels inside the noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

(If X is a "xifti", entries must be data matrices, since no grayordinate locations in X are appropriate noise ROIs).

Length of timeseries

Number of cosine bases (indices 1:n). Ignored if idx is provided.

Optional integer vector of specific basis indices to compute (each in 1:T_). Avoids building the full T \times T matrix.

Length of timeseries (number of timepoints)

TR of the fMRI scan, in seconds (the time between timepoints)

Number of cosine bases

Hz of highpass filter

The data vector (at least 15 time points).

spike threshold (AFNI's -cut). Default: 2.5. Must be at least 1.

upper range of the acceptable deviation from the fit. Default: 4. Must be at least c1 + 0.5.

Optional precomputed despike_3D.basis, to avoid recomputing it for many data vectors of equal length.

How to fit the curve: "OLD" for the L1 fit (requires the quantreg package), "NEW" for the faster least-squares fit after a simple outlier removal (the results are similar, not identical), or "auto" (default) to use "NEW" if there are more than 500 time points and "OLD" otherwise, as AFNI does.

Use AFNI's -localedit method to replace spikes? Default: FALSE.

The number of sine/cosine pairs in the curve (AFNI's -corder). Default: NULL to use round(length(Yt)/30) (at most 50 for the "OLD" method). Ignored if basis is provided.

The number of timepoints.

The number of sine/cosine pairs. Default: round(nT/30), as in AFNI.

The data vector.

The despike_3D.basis.

The data vector.

The fitted values.

spike threshold. Default: 2.5.

upper range of the acceptable deviation from the fit. Default: 4.

Instead, replace each value with |s| >= c2 with the average of the nearest values on each side with |s| < c2. (c1 is not used.) Default: FALSE.

The data vector.

Optional precomputed despike_3D.basis. Supply this when despiking many data vectors of equal length.

Numeric vectors, or matrices with locations along the rows and networks along the columns. Dice coefficients will be calculated between each pair of networks between X and Y; if Y is not provided, X will be used for Y.

The 3D array to dilate. The mask to dilate is defined by all values not in out_of_mask_val.

The number of layers to dilate the mask by. Default: 1.

A voxel is not included in the mask if and only if its value is in this vector. Default: NA. If vol is simply a logical array with TRUE values for in-mask voxels, use out_of_mask_val=FALSE.

Value for voxels newly added to the mask. Default: 1. If vol is simply a logical array with TRUE values for in-mask voxels, use new_val=1.

Subject-level fMRI data matrix (V \times T). Rows will be centered.

Group-level independent components (V \times Q)

(Optional) Number of volumes to drop from the start of each BOLD session. Default: 0.

(Optional) Nuisance matrix to regress from the BOLD data.

Nuisance regression is performed in a simultaneous regression with any spike regressors from scrub and DCT bases from hpf.

Note that the nuisance matrix should be provided with timepoints matching the original BOLD irregardless of drop_first. Nuisance matrices will be truncated automatically if drop_first>0.

(Optional) Numeric vector of integers giving the indices of volumes to scrub from the BOLD data. (List the volumes to remove, not the ones to keep.)

Scrubbing is performed within a nuisance regression by adding a spike regressor to the nuisance design matrix for each volume to scrub.

Note that indices are counted beginning with the first index in the BOLD session irregardless of drop_first. The indices will be adjusted automatically if drop_first>0.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

The frequencies at which to apply temporal filtering to the data during pre-processing, in Hertz. Set either to NULL to disable. Default: 0.01 Hz highpass filter, and NULL for the lowpass filter (disabled). Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases. Lowpass filtering is accomplished by a non-linear filter: fsl_bptf.

Note the TR argument is required for temporal filtering. If TR is not provided, an error is raised if hpf and lpf have been set.

Scale the BOLD at each voxel based on either its "mean" (default), its "sd", or do not scale ("none"). Mean scaling cannot be used if the BOLD have already been de-meaned.

Full width at half maximum (FWHM) for smoothing the estimates of scale across brain locations (see scale_by), to reduce the variance of the estimates. Set to 0 to disable smoothing, or Inf for "global" smoothing (estimate and use one measure of scale across the entire brain). Otherwise, for "local" smoothing, this should be a positive number. Default: 4.

Required only for "local" smoothing of the scale estimates with CIFTI data (see scale_sm_FWHM). To smooth the scale estimates, provide a "xifti" object aligned with BOLD. If no "xifti" object is provided (default) smoothing must be skipped.

If scale_by is "FUN", this function is used to compute the scaling measure from BOLD, after it has been centered (and so after dropping any volumes, and applying nuisance regression, scrubbing, and temporal filtering). Otherwise, ignored.

Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.

fMRI numeric data matrix (V \times T)

The parcellation as an integer vector.

The parcel values (keys) in desired order, e.g. sort(unique(parc)).

(Optional) Number of volumes to drop from the start of each BOLD session. Default: 0.

(Optional) Nuisance matrix to regress from the BOLD data.

Nuisance regression is performed in a simultaneous regression with any spike regressors from scrub and DCT bases from hpf.

Note that the nuisance matrix should be provided with timepoints matching the original BOLD irregardless of drop_first. Nuisance matrices will be truncated automatically if drop_first>0.

(Optional) Numeric vector of integers giving the indices of volumes to scrub from the BOLD data. (List the volumes to remove, not the ones to keep.)

Scrubbing is performed within a nuisance regression by adding a spike regressor to the nuisance design matrix for each volume to scrub.

Note that indices are counted beginning with the first index in the BOLD session irregardless of drop_first. The indices will be adjusted automatically if drop_first>0.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

The frequencies at which to apply temporal filtering to the data during pre-processing, in Hertz. Set either to NULL to disable. Default: 0.01 Hz highpass filter, and NULL for the lowpass filter (disabled). Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases. Lowpass filtering is accomplished by a non-linear filter: fsl_bptf.

Note the TR argument is required for temporal filtering. If TR is not provided, an error is raised if hpf and lpf have been set.

Scale the BOLD at each voxel based on either its "mean" (default), its "sd", or do not scale ("none"). Mean scaling cannot be used if the BOLD have already been de-meaned.

Full width at half maximum (FWHM) for smoothing the estimates of scale across brain locations (see scale_by), to reduce the variance of the estimates. Set to 0 to disable smoothing, or Inf for "global" smoothing (estimate and use one measure of scale across the entire brain). Otherwise, for "local" smoothing, this should be a positive number. Default: 4.

Required only for "local" smoothing of the scale estimates with CIFTI data (see scale_sm_FWHM). To smooth the scale estimates, provide a "xifti" object aligned with BOLD. If no "xifti" object is provided (default) smoothing must be skipped.

If scale_by is "FUN", this function is used to compute the scaling measure from BOLD, after it has been centered (and so after dropping any volumes, and applying nuisance regression, scrubbing, and temporal filtering). Otherwise, ignored.

Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.

The 3D array to erode. The mask to erode is defined by all values not in out_of_mask_val.

The number of layers to erode the mask by. Default: 1.

A voxel is not included in the mask if and only if its value is in this vector. The first value of this vector will be used to replace eroded voxels. Default: NA. If vol is simply a logical array with TRUE values for in-mask voxels, use out_of_mask_val=FALSE.

A T \times N numeric matrix, where T is the number of timepoints and N is the number of RPs (typically six) to expand.

T \times V numeric matrix. Each column is a voxel or vertex time series.

Number of low-frequency FFT entries to remove (the mean through N-1 cycles per scan), along with their conjugate entries.

Numeric vector of integers indicating the indices of the flagged volumes. Or, a logical vector of length n_time where TRUE values indicate the flagged volumes.

The length of the vectors to obtain. For nuisance regression, this is the length of the BOLD data. The highest index in flags should not exceed n_time.

The data matrix to multiply.

The filter matrix to multiply with. The first and second dimensions match the number of indices in dat.

Is dat indices by variables?

Should the result be indices by variables?

description

description

The number of principal components to compute for each noise ROI. Alternatively, values between 0 and 1, in which case they will represent the minimum proportion of variance explained by the PCs used for each noise ROI. The smallest number of PCs will be used to achieve this proportion of variance explained.

Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: 5 (compute the top 5 PCs for each noise ROI).

The number of voxel layers to erode the noise ROIs by. Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: NULL, which will use a value of 0 (do not erode the noise ROIs).

The path to normalize.

(Optional) the directory to append to the beginning of the path. NULL (default) to not append any directory, leaving path unchanged.

The mode for file.access to verify existence, writing permission, or reading permission. Use NA (default) to not perform any is.

A numeric matrix of time-series data.

Numeric. The standard deviation of the Gaussian kernel for the high-pass filter, in time points. Default: NULL (no high-pass filtering). sigma = 0.5 * cutoff_sec / TR

Numeric. The standard deviation of the Gaussian kernel for the low-pass filter, in time points. Default: NULL (no low-pass filtering).

Is dat indices (timepoints) by variables? Default: TRUE.

Should the result be indices (timepoints) by variables?

The number of time points in the data.

The standard deviation of the Gaussian kernel in time points.

The number of time points in the data.

The standard deviation of the Gaussian kernel in time points.

the file format

I by J by K NIFTI object or array (or file path to the NIFTI) which contains the corresponding labels to each voxel in nii. Values should be according to this table: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT In the HCP, the corresponding file is "ROIs/Atlas_wmparc.2.nii.gz".

A list of numeric vectors. Each entry should represent labels in nii_labels belonging to a single noise ROI, named by that entry's name. Or, this can be a character vector of at least one of the following: "wm_cort" (cortical white matter), "wm_cblm" (cerebellar white matter), "csf" (cerebrospinal fluid). In the latter case, these labels will be used:

"wm_cort"

c(3000:4035, 5001, 5002)

"wm_cblm"

c(7, 46)

"csf"

c(4, 5, 14, 15, 24, 31, 43, 44, 63, 250, 251, 252, 253, 254, 255))

These default ROIs are based on this forum post: https://www.mail-archive.com/hcp-users@humanconnectome.org/msg00931.html

Default: c("wm_cort", "csf")

The function to get the argument names for.

The T by Q design matrix

The T by Q design matrix

The arguments.

The fMRI data

Print the format? Default: FALSE.

The vector of fMRI data, expected to be of one format

Print the format? Default: FALSE.

The potential file name

The value to check

The data type. Default: "numeric". Also can be "logical" or "character"

The numeric vector

minimum range of x to be considered non-constant. Default: 1e-8

The putative integer

Require x>=0 (non-negative) too?

The value to check

Is a value of zero ok?

A V \times T numeric matrix. Each row is a location.

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

Print messages counting how many locations are removed?

A square matrix

Get the diagonal values too? Default: FALSE

Character vector of user input.

Character vector of expected/allowed values.

If any value in user could not be matched, or repeated matches occurred, what should happen? Possible values are "message" (default), "warning", "stop", and "nothing".

Character vector of user input. These will be matched to expected using match.arg.

Character vector of expected/allowed values.

If any value in user could not be matched, or repeated matches occurred, what should happen? Possible values are "stop" (default; raises an error), "warning", and "nothing".

How to refer to the user input in a stop or warning message. If NULL, no label is used.

The networks to find matches for. Can be a CIFTI file path, a "xifti" object, a numeric matrix (locations by networks, and can be continuous or binary), or a locations-length vector giving the network index each location belongs to.

The networks to match to. Can be a CIFTI file path, a "xifti" object, a numeric matrix (locations by networks, and can be continuous or binary), a locations-length vector giving the network index each location belongs to, or the name of a parcellation included in ciftiTools. Default: "Yeo_7".

If B is a parcellation (i.e. a vector of network indices), and the lowest parcel index is 0, drop that level? Sometimes the zero-valued parcel is used for the medial wall or other invalid locations. Default: TRUE. If FALSE, treat it as a candidate for matching just like all the other parcels.

The brainstructures to use, if A and/or B are CIFTI data. Default: "existing" to use the brainstructures present in A (or in B if A is a matrix).

The variance decomposition

The first list of kwargs.

The second list of kwargs. If duplicates are present, the default message recommends the user to remove the kwarg here in favor of placing the correct one in kwargsA.

(Optional) Descriptor of kwargsA for error statement. Default "first kwarg(s)".

(Optional) Descriptor of kwargsB for error statement. Default "second kwarg(s)".

(Optional) Extra text for error statement. "[DEFAULT]" (default) will use this message: "Note that a kwarg only has to be provided to one of these. Place the correct value in the first location and remove the kwarg from the second location".

The noise PC scores, their variances, and the noise ROI masks (after erosion), each a list with one entry per noise ROI.

A list of the noise ROIs data. Each entry is a T by V matrix (timepoints by voxels), with V possibly differing across ROIs.

Center the columns of the noise ROI data by their medians, and scale by their MADs? Default: TRUE for both.

The number of PCs to compute for each noise ROI: a single number, or a list or vector with one entry per ROI. Values between 0 and 1 represent the minimum proportion of variance explained by the PCs used for each noise ROI. Default: 5.

Nuisance signals to regress from the noise ROIs before computing the PCs. A T by P numeric matrix. Default: NULL (do not do any preliminary nuisance regression).

The number of principal components to compute for each noise ROI. Alternatively, values between 0 and 1, in which case they will represent the minimum proportion of variance explained by the PCs used for each noise ROI. The smallest number of PCs will be used to achieve this proportion of variance explained.

Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: 5 (compute the top 5 PCs for each noise ROI).

The number of voxel layers to erode the noise ROIs by. Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: NULL, which will use a value of 0 (do not erode the noise ROIs). Note that noise erosion can only be performed if the noise ROIs are volumetric.

fMRI numeric data matrix (V \times T)

(Optional) Number of volumes to drop from the start of each BOLD session. Default: 0.

(Optional) Nuisance matrix to regress from the BOLD data.

Nuisance regression is performed in a simultaneous regression with any spike regressors from scrub and DCT bases from hpf.

Note that the nuisance matrix should be provided with timepoints matching the original BOLD irregardless of drop_first. Nuisance matrices will be truncated automatically if drop_first>0.

(Optional) Numeric vector of integers giving the indices of volumes to scrub from the BOLD data. (List the volumes to remove, not the ones to keep.)

Scrubbing is performed within a nuisance regression by adding a spike regressor to the nuisance design matrix for each volume to scrub.

Note that indices are counted beginning with the first index in the BOLD session irregardless of drop_first. The indices will be adjusted automatically if drop_first>0.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

The frequencies at which to apply temporal filtering to the data during pre-processing, in Hertz. Set either to NULL to disable. Default: 0.01 Hz highpass filter, and NULL for the lowpass filter (disabled). Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases. Lowpass filtering is accomplished by a non-linear filter: fsl_bptf.

Note the TR argument is required for temporal filtering. If TR is not provided, an error is raised if hpf and lpf have been set.

Center BOLD data across rows (each data location's time series) or columns (each time point's image)? Default: TRUE for row centering, and FALSE for column centering.

Scale the BOLD at each voxel based on either its "mean" (default), its "sd", or do not scale ("none"). Mean scaling cannot be used if the BOLD have already been de-meaned.

Full width at half maximum (FWHM) for smoothing the estimates of scale across brain locations (see scale_by), to reduce the variance of the estimates. Set to 0 to disable smoothing, or Inf for "global" smoothing (estimate and use one measure of scale across the entire brain). Otherwise, for "local" smoothing, this should be a positive number. Default: 4.

Required only for "local" smoothing of the scale estimates with CIFTI data (see scale_sm_FWHM). To smooth the scale estimates, provide a "xifti" object aligned with BOLD. If no "xifti" object is provided (default) smoothing must be skipped.

For local smoothing of scale estimates, the data must be unmasked to be mapped back to the surface. So if the data are masked, provide the mask here.

If scale_by is "FUN", this function is used to compute the scaling measure from BOLD, after it has been centered (and so after dropping any volumes, and applying nuisance regression, scrubbing, and temporal filtering). Otherwise, ignored.

Return the intercept, residual SD estimates, and full design matrix from the nuisance regression? Default: FALSE

The T \times V or V \times T data.

The T \times Q matrix of nuisance regressors.

A 3D array, e.g. unvec_vol(xifti$data$subcort, xifti$meta$subcort$mask).

A 3 \times 2 matrix indicating the number of slices to add at the beginning (first column) and end (second column) of each of dimension, e.g. xifti$meta$subcort$mask_padding.

Value to pad with. Default: NA.

a T by N numeric matrix. The columns will be normalized to percent signal.

A function that computes the center of a numeric vector. Default: median. Other common options include mean and mode.

Should the center be measured individually for each "column" (default), or should the center be the same across "all" columns?

The functional connectivity matrix, a square numeric matrix with values between -1 and 1.

The minimum and maximum range of the color scale. Default: c(-1, 1). If in descending order, the color scale will be reversed.

Set to NA for white, 1, or NULL (default) to not modify the diagonal values in FC.

(Optional) Plot title.

Character vector of colors for the color scale. Default: color_palette("Beach").

Spacing between ticks on the color legend. Default: range(zlim)/2.

How many decimal digits for the color legend. Default: NULL to set automatically.

A character vector of length length(lines)+1, giving row/column labels for the submatrices divided by lines. If NULL (default), do not add labels.

Add lines to divide the FC matrix into submatrices? Default: NULL (do not draw lines). Set to "all" to delineate each individual row and column.

Color and line width of the lines. Default: black lines of width 1.

Text size. Default: 0.8.

The FC matrix

A scale_fill function. If NULL, use a red-blue diverging palette if there are negative values in mat, and viridis' inferno sequential palette otherwise.

The plot title. Default: "FC Matrix".

The legend title. Default: "".

Split the FC matrix into groups of contiguous rows/columns? Use group_divs to indicate the index of the first element in each group. For example, if the groups are 1-8, 9-15, and 16 to 25, set group_divs=c(1, 9, 16). Groups will be indicated by a color bar along the left and top sides of the plot. Use group_cols to change the colors. By default, group_divs is NULL (no groups).

Labels to place along the y-axis? If is.null(group_divs), this should be a character vector labeling each row of mat, or a dot dot dot. If !is.null(group_divs), this may alternatively be a character vector labeling each group.

Use the upper triangle of the FC matrix to show the mean of each group indicated by group_divs? Default: TRUE. Has no effect if group_divs is NULL.

Color of group dividers and outline of the FC matrix. Default: "black".

Length-two numeric vector indicating the limits for the color bar. Values beyond lim will be clipped. If NULL, the limits will be set based on the largest magnitude value in mat (no clipping). If length-one, the left limit will be 0 if there are no negative values, or -lim if there are. Default: .5.

On-diagonal values will be set to this value. (uppertri_means are calculated before diagVal is used.)

Margin value for labels. For the y-axis, a value of NULL (default) will set the margin value adaptively depending on the size of the FC matrix such that the labels are almost flush with the y-axis. The default for the x-axis is 0, which also results in labels almost flush with the x-axis.

The file name of the NIFTI.

The data matrix

Ignore NA values? Default: FALSE

A T \times K numeric matrix. In the context of a design matrix for a GLM analysis of task fMRI, T is the number of time points and K is the number of task covariates.

Scale the rows instead? Default: FALSE.

A numeric matrix. Its columns will be centered and scaled.

Columns with MAD below this value will be considered constant. Default: 1e-8

Drop constant columns? Default: TRUE. If FALSE, set to NA instead.

Center and scale the rows instead? Default: FALSE.

fMRI data as a locations by time (V \times T) numeric matrix.

Option for scaling the BOLD response.

\code{"auto"} (default) will use \code{"mean"} scaling except if demeaned 

data is detected (if any mean is less than one), in which case "sd" scaling will be used instead.

\code{"mean"} scaling will scale the data to percent local signal change.

\code{"sd"} scaling will scale the data by local standard deviation.

\code{"none"} will only center the data, not scale it.

Transpose BOLD if there are more columns than rows? (Because we usually expect the number of voxels to exceed the number of time points.) Default: TRUE.

The ICA results: a list with entries "S" and "M"

The numeric vector for which to calculate the skew. Can also be a matrix, in which case the skew of each column will be calculated.

The 3D array.

In order to compute the sum, the array is temporarily padded along each edge with the value of pad. 0 (default) will mean that edge voxels reflect the sum of 3-5 neighbors whereas non-edge voxels reflect the sum of 6 neighbors. An alternative is to use a value of NA so that edge voxels are NA-valued because they did not have a complete set of six neighbors. Perhaps another option is to use mean(arr).

The name of the file. It should be properly formatted: if it exists, file.exists(R_path) should be TRUE.

A numeric matrix, with each column being a timeseries to filter For fMRI data, X should be T timepoints by V brain locations.

Alternatively, a single integer giving the number of timepoints in data. The return value will be the suitable set of DCT bases. Only works with method == "DCT".

The time step between adjacent rows of X, in seconds.

The frequency of the highpass filter, in Hertz. Default: .008.

The frequency of the lowpass filter, in Hertz. Default: NULL (skip lowpass filtering). If both are provided, lpf > hpf must be true.

"DCT" (default) or "FFT". FFT is not compatible with lpf yet.

Print messages? Default: FALSE.

The data matrix to unmask.

The logical mask: the number of TRUE values should match the size of the (mask_dim)th dimension in dat.

Rows, 1 (default), or columns, 2.

The fill value for the inserted rows/columns. Default: NA.

v \times p matrix, where v is the number of voxels within a mask and p is the number of vectors to transform into matrix images.

m \times n logical matrix in which v entries are TRUE and the rest are FALSE.

Out-of-mask value in the output image. Default: NA.

Data matrix with locations along the rows and measurements along the columns. If only one set of measurements were made, this may be a vector.

Volumetric binary mask. TRUE indicates voxels inside the mask.

The value for locations outside the mask. Default: NA.

The design matrix

the expected number of rows in design. Default: NULL (no expected value to validate).

The data as a 3D array: measurements by subjects by variables. (Alternatively, a matrix that is measurements by subjects, if only one variable exists.)

If TRUE, display progress of algorithm. Default: FALSE.

3D logical mask

Transformation matrix from array indices to spatial coordinates.

Units for the spatial coordinates (optional).