This is an old revision of the document!
Table of Contents
fmriquality
Motivation
There are several things that can go wrong during the acquisition phase (scanning) of a subject, some of which severely impact the usability of a subject's dataset. While any given project (study) is still in the stage of data collection (subjects are still being scanned), there is always the chance to decide that a particular subject might introduce too much noise into the eventually performed group statistic and should be discarded (and in this case replaced by another subject).
Relevant for that decision could be one of the following issues:
- the subject had to exit the scanner before the experiment was completed → usually such a dataset needs to be discarded
- the subject couldn't restrain from moving their head during the experiment → depending on how difficult it is to find a replacement subject, it is advised to discard such a dataset
- the scanner produced disproportionally strong noise in the data → if possible, such a dataset should also be discarded
Of course there are still many other possible reasons to discard any given subject (e.g. a score on a questionnaire/behavioral measure indicates that the subject does not fall into the distribution of the examined population of subjects), but especially the second and third issue mentioned above can be detected even before entering a subject's dataset into any given group analysis.
This function, fmriquality
allows to assess some of the more general quality measures in a unified way.
Requirements
To run the fMRI quality checking function, the images need to be in one of the functional imaging data formats currently supported by the xff class:
- BrainVoyager's FMR (STC) format
- BrainVoyager's VTC format
- SPM's Analyze or NIftI (HDR/NII) formats (either as series of 3D volumes or a single 4D file)
Function reference ('help fmriquality')
fmriquality - get some quality assurance for fMRI data FORMAT: [fq, fmridata = ] fmriquality(images [, opts]) Input fields: images list of images (or fMRI datatype, like FMR/VTC) opts optional settings .motcor perform motion-correction (and re-do stats, def: false) .nuisreg nuisance regressors/confounds for temp. filtering .pbar 1x1 xfigure::ProgressBar or xprogress object .prange progress bar range (default: [0 .. 1]) .qasheet flag, display quality assessment sheet (default: false) .res resolution (for motion detection, default: from file) .robfilt flag, perform filtering robustly (default: false) .robmotcor flag, do motion detection robustly (default: false) .tempffrq temp filter frequency cut-off (as TRs, default: 80) .tempfset temp filter set, either of 'DC', {'Fourrier'} Output fields: fq complex struct, containing masks, time courses, etc. fmridata 4-D data slab (motion corrected, if selected) Note: the data of one run must at least fit into memory (in single precision), plus some temporary arrays and, if motion correction is selected, with further memory allocation required!
Usage
The most basic (and pre-configured) way of running fmriquality is by simply passing in the filename(s) or object of the run to check:
- using Analyze files:
- fmriquality_example1.m
qas = fmriquality(findfiles(sessionfolder, '*.img', 'depth=1'));
- using a BrainVoyager QX FMR file:
- fmriquality_example2.m
fmr = xff('*.fmr', 'Select FMR for which you want to check the data quality...'); qas = fmriquality(fmr);
- also checking motion parameters with 64 TRs as the filtering cutoff, showing the result immediately:
- fmriquality_example3.m
% selecting files with findfiles qafiles = fmriquality(findfiles(pwd, '*.img')); % options qaopts = struct( ... 'motcor', true, ... 'qasheet', true, ... 'robfilt', true, ... 'tempffrq', 64); % running fmriquality fmriquality(qafiles, qaopts);
- create a quality assessment struct for all VTCs in an MDM, applying robust temporal filtering:
- fmriquality_example4.m
% loop over VTCs in MDM for study = 1:size(mdm.XTC_RTC, 1) % perform quality assessment q = fmriquality(mdm.XTC_RTC{study, 1}, struct('robfilt', true)); % store as VTCNAME_qasheet.mat save([mdm.XTC_RTC{study, 1}(1:end-4) '_qasheet.mat'], 'q'); end
In case the QA sheet is not shown by the function (flag .qasheet
set to false
, which is the default), the returned struct can be visualized via a call to fmriqasheet
:
- fmriqasheet_example.m
% load a QA sheet (contains variable/struct q !) load CPU4212_run3_qasheet.mat % open QA sheet fmriqasheet(q);
If the .qasheet
option is not set to true, the returned variable can later be passed to fmriqasheet manually (for scripted QA-ing). This variable is of type struct and contains (at least) the following fields:
.Dims 1x4 array, size .Filename the first filename given .Masks automatically detected masks (foreground, background, etc) .Raw mean, stdev, and null-voxel image .TempFiltered re-created summary values/maps after applying temporal filtering .Quality summary images trying to capture overall quality measures (SNR, CNR, etc.) .TC diverse time courses
When passed to fmriqasheet, this function then creates a new figure and displays part of the information contained in the structure, which can be used to decide on whether or not a subject would likely introduce too much noise/bias at the group level.
Usage notes
Please be aware that the first argument must be a list of filenames; so, even for a single NIftI (NII) file, a cell array must be passed in:
- fmriquality_example5.m
% using a single NII file qas = fmriquality({'vols.nii'});
Also, please note that motion parameter estimation requires between one and several minutes (depending of the length of the run and whether or not robust motion estimation is employed). The runtime also easily increases tenfold when robust temporal filtering is used. In other words, these options are more useful and meant for situations where the fmriquality function is part of a larger script that automatically checks the quality of all incoming data instead of being used from the command line in a more interactive way!
Finally, at the moment, the “problem detection” thresholds (to mark a volume as outliers) are fixed, but are likely to change in a future version.