fc_extract_roi_timeseries

qx_mri.fc.fc_extract_roi_timeseries(flist, roiinfo, frames, targetf, options)

function [tsset] = fc_extract_roi_timeseries(flist, roiinfo, frames, targetf, options)

Extract ROI timeseries for group or individual subject / session.

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.

--options (str, default 'sessions=all|roimethod=mean|eventdata=all|ignore=use,fidl|badevents=use|savegroup=none|saveind=none|itargetf=gfolder|tsname=|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'.

• savegroup

  A comma separated list of formats to use to save the group level timeseries data. The options are:

  • long

    save the resulting data in a long format .tsv file

  • wide

    save the resulting data in a wide format .tsv file

  • mat

    save the resulting data in a matlab .mat file

  • none

    do not save any group level results.

  Defaults to 'none'.

• saveind

  a comma separted list of formats to use to save the individual level timeseries data ['']:

  • long

    save the resulting data in a long format .tsv file

  • wide

    save the resulting data in a wide format .tsv file

  • mat

    save the resulting data in a matlab .mat file

  • ptseries

    save the resulting data as a ptseries image

  • none

    do not save any individual level results.

  Defaults to 'none'.

• itargetf

  Where to save the individual data:

  • gfolder

    in the group target folder

  • sfolder

    in the individual session folder.

  Defaults to 'gfolder'.

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

• tsname

  an optional name describing the extracted timeseries 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

tsmat

A structure array with the following fields for each specified data extraction:

• 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 they were used for timeseries extraction

• N

  number of extracted frames

• ts

  the extracted timeseries matrix in the format ROI x timepoint

Output files

Based on saveind option specification a file may be saved with the extracted timeseries saved in a matlab.mat file and/or in a .tsv format:

<targetf>/<name>[_<tsname>][_<subjectid>]_ts[_<long|wide>].<tsv|mat>

<name> is the provided name of the bold(s). <tsname> is the optional name for the extracted timeseries if it was specified. <subjectid> is the single session id. It is added in case of single session extraction if it was specified and if savesessionid was set to 'true'. It is allways added in the context of group data extraction when the single session data extraction is saved to the specified group target folder. <long|wide> is the provided text format, if it was specified.

The text .tsv file(s) will have the following columns:

long format wide format - name - name - title - title - subject - subject - roi_name - event - roi_code - event - event - frame - frame - [<roi_code>]_<roi_name> - value

• 'event' refers to the index of the extracted event.

• When all frames are extracted, 'frame' refers to the frame number within the original BOLD timeseries. When a summary for each event is extracted (e.g. mean across frames), then 'frame' refers to the number of frames that were included in computation of the summary measure.

Notes

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

Use:

The function extracts timeseries 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.

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