fc_compute_seedmaps#

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

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

Computes seed based functional connectivity maps 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 (matrix | 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 event end, that specifies the frame at which the extraction should start

  • extraction end

    is a frame number relative to event start or event end, that specifies the frame at which the extraction should end.

    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:s4|delay:d-color,d-shape:s2:e0'
--targetf (str, '.'):

The group level folder to save images in.

--options (str, default 'roimethod=mean|eventdata=all|ignore=use,fidl|badevents=use|fcmeasure=r|saveind=none|savesessionid=false|itargetf=gfolder|verbose=false|debug=false'):

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.

    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 coefficient of correlation

    • rho

      Spearman's rho coefficient of correlation

    • cv

      covariance estimate

    • cc

      cross correlation

    • coh

      coherence

    • mi

      mutual information

    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 files to save, options are:

    • mean_r

      mean group correlation coefficients or covariances

    • mean_fz

      mean group Fisher Z values

    • group_z

      Z converted p values testing difference from 0

    • group_p

      p values testing difference from 0

    • all_r

      correlation coefficients or covariances for all the sessions

    • all_fz

      Fz values for all the sessions

    • all

      save all the relevant group level results

    • none

      do not save any group level results.

    Defaults to 'all'. Any invalid options will be ignored without a warning.

  • saveind

    A comma separted list of individual session / subject files to save:

    • r

      save correlation coefficients or covariance separately for each roi

    • fz

      save Fisher Z values (r or rho) separately for each roi

    • z

      save Z statistic (r only) separately for each roi

    • p

      save p value (r only) separately for each roi

    • all_by_roi

      save all relevant values by roi

    • jr

      save correlation coefficients or covariances in a single file for all roi

    • jfz

      save Fisher Z values (r or rho) in a single file for all roi

    • jz

      save Z statistic (r only) in a single file for all roi

    • jp

      save p value (r only) in a single file for all roi

    • all_joint

      save all relevant values in a joint file

    • none

      do not save any individual level results

    Default is 'none'. Any invalid options will be ignored without a warning.

  • 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 'false'.

  • itargetf

    Where to save the individual data:

    • gfolder

      in the group target folder

    • sfolder

      in the individual session folder.

    Defaults to 'gfolder'.

  • 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

fcmaps

A structure array for all the extractions specified with the following fields:

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 their seed-maps in the fc image.

subjects

A cell array with the names of subjects for which the fc maps were computed.

fc

A structure array with data per subject/session. With the following fields:

  • r/cv/rho/coh/mi/cc

    The functional connectivity map, with one seed-map per frame.

  • fz

    The functional connectivity map converted to Fisher z-values.

  • N

    Number of frames over which the map was computed.

Output files

Based on savegroup specification it saves the following group files:

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_group_mean

Mean group requested correlation coefficient or covariance.

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_Fz_group_mean

Mean group Fisher Z values.

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_group_p

Group p values testing difference from 0.

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_group_Z

Group Z converted p values testing difference from 0.

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_all_sessions

Correlation coefficients or covariance for all sessions.

<targetf>/seedmap_<listname>[_<title>]_<roi>_<fcmeasure>_Fz_all_sessions

Fisher Z values for all sessions.

Definitions:

  • <targetf> is the group target folder.

  • <roi> is the name of the ROI for which the seed map was computed for.

  • <listname> is the listname name of the flist.

  • <title> is the title of the extraction event(s), if event string was specified.

Based on saveind option specification the following files may be saved:

  • <targetf>/seedmap[_<sessionid>]_<listname>[_<title>]_<roi>_<fcmeasure>

    Correlation coefficients or covariances

  • <targetf>/seedmap[_<sessionid>]_<listname>[_<title>]_<roi>_<fcmeasure>_Fz

    Fisher Z values

  • <targetf>/seedmap[_<sessionid>]_<listname>[_<title>]_<roi>_<fcmeasure>_Z

    Z converted p values testing difference from 0

  • <targetf>/seedmap[_<sessionid>]_<listname>[_<title>]_<roi>_<fcmeasure>_p

    p values testing difference from 0

Definitions:

  • <targetf> is either the group target folder or the individual image folder.

  • <listname> is the provided name of the bold(s).

  • <sessionid> is the id of the session/subject, if it was requested or if files are saved to the group folder.

  • <title> is the title of the extraction event(s), if event string was specified.

  • <roi> is the name of the ROI for which the seed map was computed for.

Notes

The method returns a structure array named fcmaps with the fields lised above for each specified data extraction.

Use:

The function computes seed maps 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 summrised by a single frame in a newly generated events series image.

From the resulting image, ROI series will be extracted for each specified ROI as specified by the roimethod option. A seed-map will be computed for each ROI where for each voxel or grayordinate, a correlation or covariance of its dataseries with the ROI will be entered.

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

Examples

To compute resting state seed maps using first eigenvariate of each ROI:

qunex fc_compute_seedmaps \
    --flist='scz.list' \
    --roiinfo='CCNet.names' \
    --frames=0 \
    --targetf='seed-maps' \
    --options='roimethod:pca|ignore:udvarsme'

To compute resting state seed maps using mean of each region and covariances instead of correlation:

qunex fc_compute_seedmaps \
    --flist='scz.list' \
    --roiinfo='CCNet.names' \
    --frames=0 \
    --targetf='seed-maps' \
    --options='roimethod:mean|igmore:udvarsme|fcmeasure:cv'

To compute seed maps for third and fourth frame of incongruent and congruent trials (listed as inc and con events in fidl files with duration 1) using mean of each region and exclude only frames marked for exclusion in fidl files:

qunex fc_compute_seedmaps \
    --flist='scz.list' \
    --roiinfo='CCNet.names' \
    --frames='incongruent:inc:2,3|congruent:con:2,3' \
    --targetf='seed-maps' \
    --options='roimethod:mean|ignore:event'

To compute seed maps across all the tasks blocks, starting with the third frame into the block and taking one additional frame after the end of the block, use:

qunex fc_compute_seedmaps \
    --flist='scz.list' \
    --roiinfo='CCNet.names' \
    --frames='task:easyblock,hardblock:2,1' \
    --targetf='seed-maps' \
    --options='roimethod:mean|ignore:event'