create_conc#

qx_utilities.general.utilities.create_conc(sessionsfolder='.', sessions=None, sessionids=None, filter=None, concfolder=None, concname='', bolds=None, boldname='bold', bold_tail='.nii.gz', img_suffix='', bold_variant='', overwrite='no', check='yes')#

create_conc [sessionsfolder="."] [sessions=None] [sessionids=None] [filter=None] [concfolder=None] [concname=""] [bolds=None] [boldname="bold"] [bold_tail=".nii.gz"] [img_suffix=""] [bold_variant=""] [overwrite="no"] [check="yes"]

Creates a set of .conc formated files that can be used as input to a number of processing and analysis functions. The function is fairly flexible, its output defined using a number of parameters.

Parameters

--sessionsfolder (str):

The location of the sessions folder where the sessions to create the list reside.

--batchfile (str, default None):

A path to a batch.txt file.

--sessions (str, default None):

A comma or pipe separated string of session names to include (can be glob patterns).

--filter (str):

If a batch.txt file is provided a string of key-value pairs ("<key>:<value>|<key>:<value>"). Only sessions that match all the key-value pairs will be added to the list.

--img_suffix (str, default ''):

Specifies an optional suffix for 'images' folder when files are to be taken from a folder that enables a parallel workflow.

--bold_variant (str, default ''):

Specifies an optional suffix for 'functional` folder when functional files are to be taken from a folder that enables a parallel workflow with functional images.

--concfolder (str, default <studyfolder>/<session id>/inbox/concs/):

The path to the folder where conc files are to be generated. If not provided, the conc files will be saved to the folder: <studyfolder>/<session id>/inbox/concs/

--concname (str, default ''):

The name of the conc files to generate. The formula: <session id><concname>.conc will be used.

--bolds (str, default 'all'):

A space, comma or pipe separated string that lists bold numbers or bold tags to be included in the conc file.

--boldname (str, 'bold'):

The prefix to be added to the bold number specified in bolds parameter.

--bold_tail (str, default '.nii.gz'):

The full tail to be added to the bold number specified in bolds parameter or bold names that match the tag specified in the bolds parameter.

--overwrite (str, default 'no'):

If the specified list file already exists:

  • ask (ask interactively, what to do)

  • yes (overwrite the existing file)

  • no (abort creating a file)

  • append (append sessions to the existing list file).

Notes

The location of the generated conc files:

The files are created at the path specified in concfolder parameter. If no parameter is provided, the resulting files are saved in:

<studyfolder>/<session id>/inbox/concs/

Individual files are named using the following formula:

<session id><concname>.conc

If a file already exists, depending on the overwrite parameter the function will:

  • ask (ask interactively, what to do)

  • yes (overwrite the existing file)

  • no (abort creating the file)

The sessions to process:

Sessions to include in the generation of conc files are specified using sessions parameter. This can be a pipe, comma or space separated list of sessions ids, a batch file or another list file. If a string is provided, grob patterns can be used (e.g. sessions="AP*|OR*") and all matching sessions will be included.

If a batch file is provided, sessions can be filtered using the filter parameter. The parameter should be provided as a string in the format:

"<key>:<value>|<key>:<value>"

The conc files will be generated only for the sessions for which all the specified keys match the specified values.

If no sessions are specified, the function will inspect the sessionsfolder and generate conc files for all the sessions for which an images folder exists as a subfolder in the sessions's folder.

The files to include in the conc file:

The bold files to include in the conc file are specified using the bolds parameter. To specify the bolds to be included in the conc files, provide a string that lists bold numbers or bold task names in a space, comma or pipe separated string. The numeric values in the string will be interpreted as bold numbers to include, strings will be interpreted as bold task names as they are provided in the batch file. All the bolds that match any of the tasks listed will be included. If all is specified, all the bolds listed in the batch file will be included.

Two other parameters are cruical for generation of bold file entries in the conc files: boldname and bold_tail.

The bolds will be listed in the list file as:

file:<sessionsfolder>/<session id>/images<img_suffix>/functional<bold_variant>/<boldname><boldnumber><bold_tail>

Note that the function expects the files to be present in the correct place within the QuNex sessions folder structure.

Checking for presence of files:

By default the function checks if the files listed indeed exist. If a file is missing, the function will abort and no list will be created or appended. The behavior is specified using the check parameter that can take the following values:

  • yes (check for presence and abort if the file to be listed is not found)

  • no (do not check whether files are present or not)

  • warn (check for presence and warn if the file to be listed is not found).

Examples

The command below will create set of conc files in /inbox/concs, each of them named <session id>.conc, one for each of the sessions found in the current folder:

qunex create_conc \
    --bolds="1,2,3"

Each conc file will include BOLD files 1, 2, 3 listed as:

file:<current path>/<session id>/images/functional/bold[n].nii.gz

The command below will create for each session listed in the batch.txt a <session id>_WM.conc file in sessions/inbox/concs:

qunex create_conc \
    --sessionsfolder="/studies/myStudy/sessions" \
    --batchfile="batch.txt" \
    --bolds="WM" \
    --concname="_WM" \
    --bold_tail="_Atlas.dtseries.nii"

In it it will list all the BOLD files tagged as WM as:

file:<sessionsfolder>/<session id>/images/functional/bold[n]_Atlas.dtseries

For all the sessions in the batch.txt file that have the key:value pair "EC:use" set the command below will create a conc file in analysis/EC/concs folder:

qunex create_conc \
    --sessionsfolder="/studies/myStudy/sessions" \
    --batchfile="batch.txt" \
    --filter="EC:use" \
    --concfolder="analysis/EC/concs" \
    --concname="_EC_s_hpss_res-mVWMWB1de" \
    --bolds="EC" \
    --bold_tail="_s_hpss_res-mVWMWB1deEC.dtseries.nii"

The conc files will be named <session id>_EC_s_hpss_res-mVWMWB1de.conc and will list all the bold files that are marked as EC runs as:

file:<sessionsfolder>/<session id>/images/functional/bold[N]_s_hpss_res-mVWMWB1deEC.dtseries.nii