create_list#

qx_utilities.general.utilities.create_list(sessionsfolder='.', sessions=None, sessionids=None, filter=None, listfile=None, bolds=None, conc=None, fidl=None, glm=None, roi=None, boldname='bold', bold_tail='.nii.gz', img_suffix='', bold_variant='', overwrite='no', check='yes')#

create_list [sessionsfolder="."] [sessions=None] [sessionids=None] [filter=None] [listfile=None] [bolds=None] [conc=None] [fidl=None] [glm=None] [roi=None] [boldname="bold"] [bold_tail=".nii.gz"] [img_suffix=""] [bold_variant=""] [overwrite="no"] [check="yes"]

Creates a .list formatted file 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, default '.'):

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, default None):

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.

--listfile (str, default None):

The path to the generated list file. If no path is provided, the list is created as: <studyfolder>/processing/lists/sessions.list

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

--bolds (str, default None):

If provided the specified bold files will be added to the list. The value should be a string that lists bold numbers or bold tags in a space, comma or pipe separated string.

--boldname (str, default '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.

--img_suffix (str, default ''):

Specifies a suffix for 'images' folder to enable support for multiple parallel workflows (e.g. <session id>/images<img_suffix>). Empty if not used.

--conc (str, default None):

If provided, the specified conc file that resides in <session id>/images<img_suffix>/functional/concs/ folder will be added to the list.

--fidl (str, default None):

If provided, the specified fidl file that resides in <session id>/images<img_suffix>/functional/events/ folder will be added to the list.

--glm (str, default None):

If provided, the specified glm file that resides in <session id>/images<img_suffix>/functional/ folder will be added to the list.

--roi (str, default None):

If provided, the specified ROI file that resides in <session id>/images<img_suffix>/<roi> will be added to the list. Note that <roi> can include a path, e.g.: segmentation/freesurfer/mri/aparc+aseg_bold.nii.gz.

--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).

--check (str, default 'yes'):

Whether to check for existence of files to be included in the list and what to do if they don't exist:

'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, but do not abort)
'present' (check for presence, warn if the file to be listed is not found, but do not include missing files in the list).

Notes

The location of the list file:

The file is created at the path specified in listfile parameter. If no parameter is provided, the resulting list is saved in:

<studyfolder>/processing/lists/sessions.list

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 a file)
'append' (append sessions to the existing list file)

The sessions to list:

Sessions to include in the list are specified using sessions parameter. This can be a pipe, comma or space separated list of session 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>"

Only the sessions for which all the specified keys match the specified values will be included in the list.

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

The location of files to include:

By default the files to incude in the list are searched for in the standard location of image and functional files:

<session id>/images/functional`

The optional img_suffix and bold_variant parameters enable specifying alternate folders, when imaging and functional data is being processed in multiple parallel workflows. When these parameters are used the files are added to the list from the following location:

<session id/images<img_suffix>/functional<bold_variant>

The files to include in the list The function enables inclusion of bold, conc, fidl, glm and roi files.

bold files:

To include bold files, specify them using the bolds parameter. 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 crucial for generation of bold file entries in the list: 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>

conc files:

To include conc files, provide a conc parameter. In the parameter list the name of the conc file to be include. Conc files will be listed as:

conc:<sessionsfolder>/<session id>/images<img_suffix>/functional<bold_variant>/concs/<conc>

fidl files:

To include fidl files, provide a fidl parameter. In the parameter list the name of the fidl file to include. Fidl files will be listed as:

fidl:<sessionsfolder>/<session id>/images<img_suffix>/functional<bold_variant>/events/<fidl>

GLM files:

To include GLM files, provide a glm parameter. In the parameter list the name of the GLM file to include. GLM files will be listed as:

glm:<sessionsfolder>/<session id>/images<img_suffix>/functional<bold_variant>/<glm>

ROI files:

To include ROI files, provide a roi parameter. In the parameter list the name of the ROI file to include. ROI files will be listed as:

roi:<sessionsfolder>/<session id>/images<img_suffix>/<roi>

Note that for all the files the function expects the files to be present in the correct places within the QuNex sessions folder structure. For ROI files provide the relative path from the images<img_suffix> folder.

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)
'present' (check for presence, warn if the file to be listed is not found, but do not include the file in the list).

Examples

The command:

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

will create a list file in ../processing/list/sessions.list that will list for all the sessions found in the current folder BOLD files 1, 2, 3 listed as:

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

The command:

qunex create_list \
    --sessionsfolder="/studies/myStudy/sessions" \
    --batchfile="batch.txt" \
    --bolds="rest" \
    --listfile="lists/rest.list" \
    --bold_tail="_Atlas_s_hpss_res-mVWMWB1d.dtseries"

will create a lists/rest.list list file in which for all the sessions specified in the batch.txt it will list all the BOLD files tagged as rest runs and include them as:

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

The command:

qunex create_list \
    --sessionsfolder="/studies/myStudy/sessions" \
    --batchfile="batch.txt" \
    --filter="EC:use" \
    --listfile="lists/EC.list" \
    --conc="bold_Atlas_dtseries_EC_s_hpss_res-mVWMWB1de.conc" \
    --fidl="EC.fidl" \
    --glm="bold_conc_EC_s_hpss_res-mVWMWB1de_Bcoeff.nii.gz" \
    --roi="segmentation/hcp/fsaverage_LR32k/aparc.32k_fs_LR.dlabel.nii"

will create a list file in lists/EC.list that will list for all the sessions in the conc file, that have the key:value pair "EC:use" the following files:

conc:<sessionsfolder>/<session id>/images/functional/concs/bold_Atlas_dtseries_EC_s_hpss_res-mVWMWB1de.conc
fidl:<sessionsfolder>/<session id>/images/functional/events/EC.fidl
glm:<sessionsfolder>/<session id>/images/functional/bold_conc_EC_s_hpss_res-mVWMWB1de_Bcoeff.nii.gz
roi:<sessionsfolder>/<session id>/images/segmentation/hcp/fsaverage_LR32k/aparc.32k_fs_LR.dlabel.nii

QuNex documentation

create_list

create_list#