fc_compute_roifc#

qx_mri.fc.fc_compute_roifc(flist, roiinfo, frames, targetf, options)#

fc_compute_roifc(flist, roiinfo, frames, targetf, options)

Computes ROI functional connectivity matrices for group and/or individual subjects / sessions.

Parameters

--flist (str):

A .list file listing the subjects and their files for which to compute seedmaps.

Alternatively, a string that specifies the list, session id(s) and files to be used for computing seedmaps. The string has to have the following form:

'listname:<name>|session id:<session id>|file:<path to bold file>|
roi:<path to individual roi mask>'

Note: - 'roi' is optional, if individual roi masks are to be used, - 'file' can be replaced by 'conc' if a conc file is provied.

Example:

'listname:wmlist|session id:OP483|file:bold1.nii.gz|roi:aseg.nii.gz'

--roiinfo (str):

A path to the names file specifying group based ROI for which to extract timeseries for.

--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:
```
'<extraction name>:<event list>:<extraction start>:<extraction end>'
```

where:

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:

'encoding:e-color,e-shape:s2:s2|delay:d-color,d-shape:s2:e0'

--targetf (str, default '.'):

The group level folder to save results in.

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:

sessions
Which sessions to include in the analysis. The sessions should be provided as a comma or space separated list. If all sessions are to be processed this can be designated by 'all'. Defaults to 'all'.
roimethod
What method to use to compute ROI signal:
- mean
  compute mean values across the ROI
- median
  compute median value across the ROI
- max
  compute maximum value across the ROI
- min
  compute mimimum value across the ROI
- pca
  compute first eigenvariate of the ROI.
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
- none
  do not ignore any frames.
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
- rho
  Spearman's rho value
- cv
  covariance estimate
- cc
  cross correlation
- icv
  inverse covariance
- coh
  coherence
- mi
  mutual information
- mar
  multivariate autoregressive model (coefficients)
Defaults to 'r'.

Additional parameters for specific measures can be added using fcargs optional parameter (see below).
fcargs
Additional arguments for computing functional connectivity, e.g. k for computation of mutual information or standardize and shrinkage for computation of inverse covariance. These parameters need to be provided as subfields of fcargs, e.g.: 'fcargs>standardize:partialcorr,shrinkage:LW'
savegroup
A comma separated list of formats to use to save the group data:
- all_long
  save the results from all sessions in a long format .tsv file
- all_wide_single
  save the results from all sessions in a single wide format .tsv file
- all_wide_separate
  save the results from all sessions in a wide format .tsv file, one file per each measure of interest
- mean_long (not yet implemented)
  save the group mean results in a long format .tsv file
- mean_wide_single (not yet implemented)
  save the group mean results in a single wide format .tsv file
- mean_wide_separate (not yet implemented)
  save the group mean results in a wide format .tsv file, one file per each measure of interest
- mat
  save the resulting data in a matlab .mat file
- none
  do not save group results.c =
Defaults to 'none'.
saveind
A comma separted list of formats to use to save the data:
- long
  save the resulting data in a long format .tsv file
- wide_single
  save the resulting data in a single wide format .tsv file
- wide_separate
  save the resulting data in a wide format .tsv file, one file per each measure of interest
- mat
  save the resulting data in a matlab .mat file.
- none
  do not save individual results.
Defaults to 'none'.
savesessionid
whether to add the id of the session or subject to the individual output file when saving to the individual session images/functional folder:
- true
- false.
Defaults to 'true'.
itargetf
Where to save the individual data:
- gfolder
  in the group target folder
- sfolder
  in the individual session folder.
Defaults to 'gfolder'.
fcname
An optional name describing the functional connectivity computed 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

fcset

title
The title of the extraction as specifed in the frames string. It defaults to 'timeseries' if not provided.
roi
A cell array with the names of the ROI used in the order of columns and rows in the functional connectivity matrix.
subject
A structure array with the following fields for each subject/session included in the analysis:
- id
  An id of the subject/session.
- <fcmeasure>
  A matrix of functional connectivity measure between all ROI for that subject/session.
- fz
  Fisher z transformed connectivity matrix between all ROI for that subject/session.
- z
  z-scores for the correlations.
- p
  p-values for the correlations.
group
A structure with group-level data:
- <fcmeasure>
  A matrix of mean functional connectivity measure between all ROI averaged over the group.
- fz
  Fisher z transformed connectivity matrix between all ROI averaged over the group.
- z
  z-scores computed across the group connectivity matrices.
- p
  p-values computed across the group connectivity matrices.

Notes

Please note, that only those results that are valid for the specific fcmeasure are saved. For example, fz, p, and z will not be reported for cv at the individual level, and fz won't be reported on the group level.

Based on savegroup 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>/roifc_<listname>[_<fcname>]_<fcmeasure>_[long|[Fz_]wide>].<tsv|mat>

<targetf> is the group target folder.
<listname> is the name of the provided <flist>.
<fcname> is the provided name of the functional connectivity computed, if it was specified.
<fcmeasure> is the measure of functional connectivity that was computed.

long and wide will be added for long and wide tsv files, respectively. Fz will be added when wide data is saved in separate wide format files.

Based on saveind option specification a file may be saved with the functional connectivity data saved in a matlab.mat and/or in a text wide or long format:

<stargetf>/roifc_<listname>[_<fcname>][_<subjectid>]_<fcmeasure>_[long|[Fz_]wide>].<tsv|mat>

<stargetf> is eitehr the group target folder or the individual's functional images folder, depending on the itargetf option.
<listname> is the name of the provided <flist>.
<fcname> is the provided name of the functional connectivity computed, if it was specified
<subjectid> is the subject/session id, if it was requested by the savesessionid or if the files are saved in the group target folder.

long and wide will be added for long and wide tsv files, respectively. Fz will be added when wide data is saved in separate wide format files.

The text file will have the following columns (depending on the fcmethod):

long format - name - title - subject - roi1 - roi2 - <fcmeasure> - Fz - Z - p

wide format - name - title - subject - <fcmeasure> - [<roi1_code>]_<roi1_name>-[<roi_code>2]_<roi3_name>

Note: In wide format only <fcmeasure> and Fz data will be saved.

Use:

The function computes functional connectivity matrices for the specified ROI. If an event string is provided, it has to start with a path to the .fidl file to be used to extract the events, following by a pipe separated list of event extraction definitions:

<title>:<eventlist>:<frame offset1>:<frame offset2>

multiple extractions can be specified by separating them using the pipe '|' separator. Specifically, for each extraction, all the events listed in a comma-separated eventlist will be considered (e.g. 'congruent,incongruent'). For each event all the frames starting from the specified beginning and ending offset will be extracted. If options eventdata is specified as 'all', all the specified frames will be concatenated in a single timeseries, otherwise, each event will be summarised by a single frame in a newly generated events series image.

From the resulting timeseries, ROI series will be extracted for each specified ROI as specified by the roimethod option. A functional connectivity matrix between ROI will be computed.

The results will be returned in a fcmat structure and, if so specified, saved.

QuNex documentation

fc_compute_roifc

fc_compute_roifc#