create_session_info#

qx_utilities.general.utilities.create_session_info(sessions=None, pipelines='hcp', sessionsfolder='.', sourcefile='session.txt', targetfile=None, mapping=None, filter=None, overwrite='no')#

create_session_info sessions=<sessions specification> [pipelines=hcp] [sessionsfolder=.] [sourcefile=session.txt] [targetfile=session_<pipeline>.txt] [mapping=specs/<pipeline>_mapping.txt] [filter=None] [overwrite=no]

Creates session.txt files that hold the information necessary for correct mapping to a folder structure supporting specific pipeline processing.

Parameters

--batchfile (str, default ''):: Path to a batch file.
--sessions (str, default '*'):: Either an explicit list (space, comma or pipe separated) of sessions to process or the path to a list file with sessions to process. If left unspecified, '*' will be used and all folders within sessions' folders will be processed.
--pipelines (str, default 'hcp'):: Specify a comma separated list of pipelines for which the session info will be prepared.
--sessionsfolder (str, default '.'):: The directory that holds sessions' folders.
--sourcefile (str, default 'session.txt'):: The "source" session.txt file.
--targetfile (str, default session_<pipeline>.txt):: The "target" session.txt file.
--mapping (str, default specs/<pipeline>_mapping.txt):: The path to the text file describing the mapping.
--filter (str, default None):: An optional "key:value|key:value" string used as a filter if a batch file is used. Only sessions for which all the key:value pairs are true will be processed. All the sessions will be processed if no filter is provided.
--overwrite (str, default 'no'):: Whether to overwrite target files that already exist ('yes') or not ('no').

Notes

If an explicit list of parameters is provided, each element is treated as a glob pattern and the command will process all matching session ids.

The create_session_info command is used to prepare session.txt files so that they hold the information necessary for correct mapping to a folder structure supporting specific pipeline preprocessing.

For all the sessions specified, the command checks for the presence of specified source file (sourcefile). If the source file is found, each sequence name is checked against the source specified in the mapping file (mapping), and the specified label is aded. The results are then saved to the specified target file (targetfile). The resulting session information files will have "<pipeline>ready: true" key-value pair added.

Mapping specification:

The mapping file specifies the mapping between original sequence names and the desired pipeline labels. There are no limits to the number of mappings specified. Each mapping is to be specified in a single line in a form:

<original_sequence_name>  => <user_specified_label>

or:

<sequence number> => <user_specified_label>

BOLD files should be given a compound label after the => separator:

<original_sequence_name>  => bold:<user_specified_label>

as this allows for flexible labeling of distinct BOLD runs based on their content. Here the 'bold' part denotes that it is a bold file and the <user_speficied_label> allows for flexibility in naming. create_session_info will automatically number bold images in a sequential order, starting with 1.

Any empty lines, lines starting with #, and lines without the "map to" => characters in the mapping file will be ignored. In the target file, images with names that do not match any of the specified mappings will be given empty labels. When both sequence number and sequence name match, sequence number will have priority.

Example mapping file:

Example lines in a mapping file:

C-BOLD 3mm 48 2.5s FS-P => SE-FM-AP
C-BOLD 3mm 48 2.5s FS-A => SE-FM-PA

T1w 0.7mm N1 => T1w
T1w 0.7mm N2 => T1w
T2w 0.7mm N1 => T2w
T2w 0.7mm N2 => T2w

RSBOLD 3mm 48 2.5s  => bold:rest
BOLD 3mm 48 2.5s    => bold:WM

5 => bold:sleep

Example lines in a source session.txt file:

01: Scout
02: T1w 0.7mm N1
03: T2w 0.7mm N1
04: RSBOLD 3mm 48 2.5s
05: RSBOLD 3mm 48 2.5s

Resulting lines in target session_<pipeline>.txt file:

01:                  :Scout
02: T1w              :T1w 0.7mm N1
03: T2w              :T2w 0.7mm N1
04: bold1:rest       :RSBOLD 3mm 48 2.5s
05: bold2:sleep      :RSBOLD 3mm 48 2.5s

Note, that the old sequence names are preserved.

Examples

Specify the session folder for a given study to automatically loop over the entire folder:

qunex create_session_info \
    --sessions="*" \
    --sessionsfolder=<study_folder>/sessions

Define source and target session parameter files and mapping file. In this example the --sourcefile flag points to the original session information file, --targetfile points to the session information file to generate, and --mapping points to a generic mapping file:

qunex create_session_info \
    --sessionsfolder=/<study_folder>/sessions \
    --sourcefile=<original_session_information_file> \
    --targetfile=<hcp_session_information_file> \
    --mapping=<generic_mapping_file>

Two additional examples:

qunex create_session_info \
    --sessions="OP*|AP*" \
    --sessionsfolder=session \
    --mapping=session/hcp_mapping.txt

qunex create_session_info \
    --sessions="processing/batch_new.txt" \
    --sessionsfolder=session \
    --mapping=session/hcp_mapping.txt

QuNex documentation

create_session_info

create_session_info#