fc_compute_roifc
fc_compute_roifc#
- qx_mri.fc.fc_compute_roifc(bolds, roiinfo, frames, targetf, options)#
fc_compute_roifc(bolds, roiinfo, frames, targetf, options)
Computes ROI functional connectivity matrices for individual subject / session.
Parameters
- --bolds (str):
A string with a pipe separated list of paths to .conc or bold files. The first element has to be the name of the file or group to be used when saving the data. E.g.: 'rest|<path to rest file 1>|<path to rest file 2>'.
- --roiinfo (str):
A path to the names file specifying group based ROI. Additionaly, separated by a pipe '|' symbol, a path to an image file holding subject/session specific ROI definition.
- --frames (cell array | int | str, default ''):
The definition of which frames to extract, specifically
a numeric array mask defining which frames to use (1) and which not (0), or
a single number, specifying the number of frames to skip at the start of each bold, or
a string describing which events to extract timeseries for, and the frame offset from the start and end of the event in format:
'<fidlfile>|<extraction name>:<event list>:<extraction start>:<extraction end>'
where:
- fidlfile
is a path to the fidle file that defines the events
- extraction name
is the name for the specific extraction definition
- event list
is a comma separated list of events for which data is to be extracted
- extraction start
is a frame number relative to event start or end when the extraction should start
- extraction end
is a frame number relative to event start or end when the extraction should start the extraction start and end should be given as '<s|e><frame number>'. E.g.:
's0' ... the frame of the event onset
's2' ... the second frame from the event onset
'e1' ... the first frame from the event end
'e0' ... the last frame of the event
'e-2' ... the two frames before the event end.
Example:
'<fidlfile>|encoding:e-color,e-shape:s2:s2|delay:d-color,d-shape:s2:e0'
- --targetf (str, default '.'):
The folder to save images in.
- --options (str, default 'roimethod=mean|eventdata=all|ignore=use,fidl|badevents=use|fcmeasure=r|saveind=none|verbose=false|debug=false|fcname='):
A string specifying additional analysis options formated as pipe separated pairs of colon separated key, value pairs:
"<key>:<value>|<key>:<value>".
It takes the following keys and values:
- roimethod
What method to use to compute ROI signal:
'mean'
'median'
'pca'.
Defaults to 'mean'.
- eventdata
What data to use from each event:
- all
use all identified frames of all events
- mean
use the mean across frames of each identified event
- min
use the minimum value across frames of each identified event
- max
use the maximum value across frames of each identified event
- median
use the median value across frames of each identified event.
Defaults to 'all'.
- ignore
A comma separated list of information to identify frames to ignore, options are:
- use
ignore frames as marked in the use field of the bold file
- fidl
ignore frames as marked in .fidl file (only available with event extraction)
- <column>
the column name in ∗_scrub.txt file that matches bold file to be used for ignore mask.
Defaults to 'use,fidl'.
- badevents
What to do with events that have frames marked as bad, options are:
- use
use any frames that are not marked as bad
- <number>
use the frames that are not marked as bad if at least <number> ok frames exist
- ignore
if any frame is marked as bad, ignore the full event.
Defaults to 'use'.
- fcmeasure
Which functional connectivity measure to compute, the options are:
- r
Pearson's r value
- cv
covariance estimate.
Defaults to 'r'.
- saveind
A comma separted list of formats to use to save the data:
- txt
save the resulting data in a long format .txt file
- mat
save the resulting data in a matlab .mat file
- none
don't save the results in a file, same as ''.
Defaults to 'none'.
- fcname
An optional name describing the functional connectivity computed to add to the output files, if empty, it won't be used. Defaults to ''.
- subjectname
An optional subject/session name to add to the output files, if empty, it won't be used. Defaults to ''.
- verbose
Whether to be verbose when running the analysis:
true
false.
Defaults to 'false'.
- debug
Whether to print debug when running the analysis:
true
false.
Defauts to 'false'.
Returns
- fcmat
- title
The title of the extraction as specifed in the frames string, empty if extraction was specified using a numeric value.
- roi
A cell array with the names of the ROI used in the order of columns and rows in the functional connectivity matrix.
- N
Number of frames over which the matrix was computed.
- r
Correlation matrix between all ROI for that subject/session.
- fz
Fisher z transformed correlation matrix between all ROI for that subject/session.
- z
z-scores for the correlations.
- p
p-values for the correlations.
- cv
Covariance matrix between all ROI for that subject/session.
Notes
Please note, that cv will only be present if it was specified as the cmeasure. r, fz, z, p will only be present if r was specified as the fcmeasure.
Based on saveind option specification a file may be saved with the functional connectivity data saved in a matlab.mat file and/or in a text long format:
<targetf>/<name>[_<fcname>][_<subjectname>]_<cor|cov>.<txt|mat>