- qx_mri.fc.fc_preprocess(sessionf, bold, omit, doIt, rgss, task, efile, tr, eventstring, variant, overwrite, tail, scrub, ignores, options)#
fc_preprocess(sessionf, bold, omit, doIt, rgss, task, efile, tr, eventstring, variant, overwrite, tail, scrub, ignores, options)
A command for running single BOLD file based functional connectivity preprocessing.
- --sessionf (str):
The session’s folder with images and data.
- --bold (int):
The number of the bold file to process.
- --omit (int, default ''):
The number of frames to omit at the start of each bold.
- --doIt (str, default 's,h,r,c,l'):
A string specifying, which steps to perform and in what order:
s - spatial smoothing
h - highpass temporal filter
r - regression of nuisance signal
c - save coefficients in _coeff file [deprecated -> see glm_results options]
l - lowpass temporal filtering
m - motion scrubbing.
- --rgss (str, default 'm,V,WM,WB,1d'):
What to regress in the regression step, a comma separated list of possibilities:
m - motion
m1d - first derivate for movement regressors
mSq - squared motion parameters
m1dSq - squared motion derivatives
V - ventricles
WM - white matter
WB - whole brain
mWB - masked whole brain
n1d - first derivative for nuisance signal regressors
1d - first derivative of specified regressors (movement or nuisance)
t - task
e - event.
- --task (matrix, default ''):
A matrix of custom regressors to be entered in GLM.
- --efile (str, default ''):
An event (fidl) file to be used for removing task structure.
- --tr (float, default 2.5):
TR of the data, in seconds.
- --eventstring (str, default ''):
A string specifying the events to regress and the regressors to use.
- --variant (str, default ''):
A string to be prepended to files.
- --overwrite (bool, default false):
Whether old files should be overwritten.
- --tail (str, default '.nii.gz'):
What file extension to expect and use for images.
- --scrub (str, default Existing scrubbing data):
The description of how to compute scrubbing - a string in 'param:value|param:value' format.
head radius in mm (default 50)
frame displacement threshold
how many frames after the bad one to reject
how many frames before the bad one to reject
which criteria to use for rejection (mov, dvars, dvarsme, idvars, udvars ...)
If empty, the existing scrubbing data is used.
- --ignores (str, default 'hipass꞉keep|regress꞉keep|lopass꞉keep'):
How to deal with the frames marked as not used in filering and regression steps specified in a single string, separated with pipes:
hipass - keep / linear / spline
regress - keep / ignore / mark / linear / spline
lopass - keep / linear /spline.
The colon symbols used above to denote:
are of the Unicode modifier colon variety (U+A789) and are not equivalent to the usual colon (U+003A) that should be used when running the command. Copying the above line containing modifier colons will result in an error - use normal colons with the command instead.
- --options (str, default ''):
Additional options that can be set using the key=value|key=value string:
- surface_smooth : 2 - volume_smooth : 2 - voxel_smooth : 1 - hipass_filter : [0.009] - lopass_filter : [0.08] - hipass_do : ['nuisance'] - lopass_do : ['nuisance, movement, events, task'] - framework_path : - wb_command_path : - omp_threads : 0 - smooth_mask : false - dilate_mask : false - boldname : bold - bold_tail : - bold_variant : - img_suffix : - glm_matrix : none ('none' / 'text' / 'image' / 'both') - glm_residuals : save [deprectated -> see glm_results] - glm_results : 'c,r' ('c', 'z', 'p', 'se', 'r', 'all') - glm_name :
fc_preprocess is a complex function initially used to prepare BOLD files for further functional connectivity analysis. The function enables the following actions:
spatial smoothing (3D or 2D for cifti files)
temporal filtering (high-pass, low-pass)
removal of nuisance signal and task structure.
Basics specify the files to use for processing and what to do. The relevant parameters are:
Specifies the sessions’s base folder in which the function will look for all the other relevant files.
The number of the bold file to process
The actions to be performed.
Whether to overwrite the existing data or not.
A string to prepend to the list of steps done in the resulting files saved.
The file (format) extension (e.g. '.nii.gz').
The event (fidl) filename.
Important are also the following optional keys in the options parameter:
Specifies, how the BOLD files are named in the images/functional folder.
Specifies the additional tail that the bold name might have (see below).
Specifies a possible extension for the images/functional and images/segmentation/boldmasks folders.
Specifies a possible extension for the images folder name enabling processing of multiple parallel workflows.
The actions performed are denoted by a single letter, and they will be executed in the sequence listed. The possible actions are:
Regression (nuisance and/or task) with an optional number 0, 1, or 2 specifying the type of regression to use (see REGRESSION below).
Saving of resulting beta coefficients (always to follow 'r').
So the default 's,h,r,c,l' do input parameter would lead to the files first being smoothed, then high-pass filtered. Next a regression step would follow in which nuisance signal and/or task related signal would be estimated and regressed out, then the related beta estimates would be saved. Lastly the BOLDs would be also low-pass filtered.
The command either makes use of scrubbing information or performs scrubbing comuputation on its own (when 'm' is part of the command). In the latter case, all the scrubbing parameters need to be specified in the scrub string:
Estimated head radius (in mm) for computing frame displacement statistics. Defaults to 50.
Frame displacement threshold (in mm) to use for identifying bad frames. Defaults to 0.5.
The (mean normalized) dvars threshold to use for identifying bad frames. Defaults to 3.0.
The (median normalized) dvarsm threshold to use for identifying bad frames. Defaults to 1.5.
How many frames after each frame identified as bad to also exclude from further processing and analysis. Defaults to 0.
How many frames before each frame identified as bad to also exclude from further processing and analysis. Defaults to 0.
Which criteria to use for identification of bad frames. Defaults to 'udvarsme'.
In any case, if scrubbing was done beforehand or as a part of this commmand, one can specify, how the scrubbing information is used in ignores string:
'hipass:<filtering opt.>|regress:<regression opt.>|lopass:<filtering opt.>'
Filtering options are:
Keep all the bad frames unchanged.
Replace bad frames with linear interpolated values based on neighbouring good frames.
Replace bad frames with spline interpolated values based on neighouring good frames
To prevent artefacts present in bad frames to be temporaly spread, use either 'linear' or 'spline' options.
Regression options are:
Keep the bad frames and use them in the regression.
Exclude bad frames from regression and keep the original values in their place.
Exclude bad frames from regression and mark the bad frames as NaN.
Exclude bad frames from regression and replace them with linear interpolation after regression.
Exclude bad frames from regression and replace them with spline interpolation after regression.
Please note that when the bad frames are ignored, the original values will be retained in the residual signal. In this case they have to be excluded or ignored also in all following analyses, otherwise they can be a significant source of artefacts.
- Spatial smoothing:
- Volume smoothing:
For volume formats the images will be smoothed using the img_smooth_3d nimage method. For cifti format the smooting will be done by calling the relevant wb_command command. The smoothing parameters can be set in the options string:
Gaussian smoothing FWHM in voxels. Defaults to 1.
Whether to smooth only within a mask, and what mask to use (nonzero/brainsignal/brainmask/<filename>). Defaults to false.
Whether to dilate the image after masked smoothing and what mask to use (nonzero/brainsignal/brainmask/same/<filename>). Defaults to false.
If a smoothing mask is set, only the signal within the specified mask will be used in the smoothing. If a dilation mask is set, after smoothing within a mask, the resulting signal will be constrained / dilated to the specified dilation mask.
For both optional string values the possibilities are:
Mask will consist of all the nonzero voxels of the first BOLD frame.
Mask will consist of all the voxels that are of value 300 or higher in the first BOLD frame (this gave a good coarse brain mask for images intensity normalized to mode 1000 in the NIL preprocessing stream).
Mask will be the actual bet extracted brain mask based on the first BOLD frame (generated using the create_bold_brain_masks command).
All the non-zero voxels in a specified volume file will be used as a mask.
No mask will be used.
Only for dilate_mask, the mask used will be the same as smooting mask.
- Cifti smoothing:
For cifti format images, smoothing will be run using wb_command. The following parameters can be set in the options parameter:
FWHM for gaussian surface smooting in mm. Defaults to 2.0.
FWHM for gaussian volume smooting in mm. Defaults to 2.0.
The path to framework libraries on the Mac system. No need to use it currently if installed correctly.
The path to the wb_command executive. No need to use it currently if installed correctly.
The resulting smoothed files are saved with '_s' added to the BOLD root filename.
- Temporal filtering:
Temporal filtering is accomplished using img_filter nimage method. The code is adopted from the FSL C++ code enabling appropriate handling of bad frames (as described above - see SCRUBBING). The filtering settings can be set in the options parameter:
The frequency for high-pass filtering in Hz. Defaults to 0.008.
The frequency for low-pass filtering in Hz Defaults to 0.09.
Please note that the values finaly passed to img_filter method are the respective sigma values computed from the specified frequencies and TR.
Filtering of nuisance signal, movement, task, and events Besides data, nuisance signal, motion parameters, and event regressors can be filtered as well. What to filter beside data can be specified by a comma separated list using the following parameters:
What to high-pass filter besides data – options are: nuisance, movement, events, task. Default is 'nuisance'.
What to lo-pass filter besides data – options are: nuisance, movement, events, task. Default is 'nuisance, movement, task, events'.
Note that 'events' refers to regressors created based on events as specified in the fidl file, whereas 'task' refers to a task matrix that is passed directy in the matlab function call.
The resulting filtered files are saved with '_hpss' or '_bpss' added to the BOLD root filename for high-pass and low-pass filtering, respectively.
Regression is a complex step in which GLM is used to estimate the beta weights for the specified nuisance regressors and events. The resulting beta weights are then stored in a GLM file (a regular file with additional information on the design used) and residuals are stored in a separate file. This step can therefore be used for two puposes:
to remove nuisance signal and event structure from BOLD files, removing unwanted potential sources of correlation for further functional connectivity analyses, and
to get task beta estimates for further activational analyses. The following parameters are used in this step:
A comma separated list of regressors to include in GLM. Possible values are:
first derivative for movement regressors
squared motion parameters
squared motion derivatives
white matter signal
whole brain signal
first derivative of requested above nuisance signals (V, WM, WB)
first derivative of specified regressors, movement and nuisance signals (V, WM, WB)
events listed in the provided fidl files (see above), modeled as specified in the event_string parameter.
Defaults to 'm,V,WM,WB,1d'.
A string describing, how to model the events listed in the provided fidl files. Defaults to .
Additionally, the following options can be set using the options string:
Whether to save the GLM matrix as a text file ('text'), a png image file ('image'), both ('both') or not ('none'). Defaults to 'none'.
Whether to save the residuals after GLM regression ('save') or not ('none'). Defaults to 'save'.
An additional name to add to the residuals and GLM files to distinguish between different possible models used.
- GLM modeling:
The exact GLM model used to estimate nuisance and task beta coefficients and regress them from the signal is defined by the event string provided by the eventstring parameter. The event string is a pipe ('|') separated list of regressor specifications. The possibilities are:
- Unassumed Modelling:
<fidl code>:<length in frames>
where <fidl code> is the code for the event used in the fidl file, and <length in frames> specifies, for how many frames ofthe bold run (since the onset of the event) the event should be modeled.
- Assumed Modelling:
where <fidl code> is the same as above, <hrf> is the type of the hemodynamic response function to use, and <normalize> and <length> are optional parameters, with their values dependent on the model used. The allowed <hrf> are:
boynton ... uses the Boynton HRF
SPM ... uses the SPM double gaussian HRF
u ... unassumed (see above)
block ... block response
For the first two, <normalize> can be either 'run' or 'uni'. 'run' (e.g. 'SPM-run' or abbreviated 'SPM-r') specifies that the assumed regressor should be scaled to amplitude of 1 within each BOLD run, and 'uni' (e.g. 'SPM-uni' or abbreviated 'SPM-u') specifies that the regresor should be universaly scaled to HRF area-under-the-curve = 1. If no <normalize> parameter is specified, 'uni' is assumed by default. The default behavior has changed with QuNex version 0.93.4, which can result in different assumed HRF regressor scaling and the resulting GLM beta estimates.
Parameter <length> is also optional in case of 'SPM' and 'boynton' assumed HRF modelling, and it overrides the event duration information provided in the fidl file. For 'u' the length is the same as in previous section: the number of frames to model. For 'block' length should be two numbers separated by a colon (e.g. 2:9) that specify the start and end offset (from the event onset) to model as a block.
- Naming And Behavioral Regressors:
Each of the above (unassumed and assumed modelling specification) can be followed by a ">" (greater-than character), which signifies additional information in the form:
<name>[:<column>[:<normalization span>[:<normalization method>]]]
The name of the resulting regressor.
The number of the additional behavioral regressor column in the fidl file (1-based) to use as a weight for the regressor.
- normalization span
Whether to normalize the behavioral weight within a specific event type ('within') or across all events ('across'). Defaults to 'within'.
- normalization method
The method to use for normalization. Options are:
z ... compute Z-score
01 ... normalize to fixed range 0 to 1
-11 ... normalize to fixed range -1 to 1
none ... do bot normalize, use weights as provided in fidl file.
This would result in three sets of task regressors: one assumed task regressor for the sustained activity across the block, one unassumed task regressor set spanning 9 frames that would model the presentation of the target, and one behaviorally weighted unassumed regressor that would for each frame estimate the variability in response as explained by the reaction time to the target.
This step results in the following files (if requested):
- residual image:
- GLM coefficient image:
If you want more specific GLM results and information, please use preprocess_conc command.
qunex fc_preprocess \ --sessionf='sessions/OP234' \ --bold=3 \ --omit=4 \ --doIt='s,h,r' \ --rgss='m,V,WM,WB,1d' \ --tr=2.5 \ --overwrite=true \ --scrub='udvarsme' \ --ignores='hipass:linear|regress=ignore|lopass=linear'