merge_sessions_list

qx_utilities.general.sessions.merge_sessions_list(studyfolder: str, session_list: str, source_folder: str, target_folder: str, overwrite: str = 'no', raw_data: str = 'copy', original_sessions: str = 'leave', _log=None) → bool

merge_sessions_list --studyfolder=<path> --session_list=<file> --source_folder=<path> --target_folder=<path> [--overwrite=<mode>] [--raw_data=<mode>] [--original_sessions=<action>]

Join multiple sessions according to a list file.

Description:

Processes a list file containing multiple session join specifications, calling merge_session for each line. This is useful for batch processing multiple session merges with a single command.

Parameters

--studyfolder (str):

Path to the study folder. This is passed to each merge_session call.

--session_list (str):

Path to a text file containing join specifications. Each line should have the format:

<target_id>: <source_id>, <source_id>, <source_id>

Where target_id is the name of the merged session to create, and source_id are the sessions to merge (comma-separated). Lines starting with # are treated as comments and ignored. Empty lines are skipped.

--source_folder (str):

Path to the folder containing source sessions. Each source_id from the session_list will be resolved as <source_folder>/<source_id>.

--target_folder (str):

Path to the folder where target sessions will be created. Each target_id from the session_list will be resolved as <target_folder>/<target_id>.

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

How to handle existing target folders. Passed to each merge_session call. Options are 'no', 'clean', or 'merge'.

--raw_data (str, default 'copy'):

How to handle raw data. Passed to each merge_session call. Options are 'copy', 'move', or 'leave'.

--original_sessions (str, default 'leave'):

How to handle original source sessions after merging. Options are: - 'leave': Leave original sessions unchanged (default) - 'remove': Remove original sessions after successful merge - 'move:<path>': Move original sessions to specified path (e.g., 'move:/data/backup_sessions')

Examples

Session list file example (session_joins.txt):

# Merge sessions for subject A
A_merged: A_001, A_002, A_003

# Merge sessions for subject B
B_merged: B_001, B_002

Basic usage with default settings:

merge_sessions_list(
    studyfolder='/data/my_study',
    session_list='/data/my_study/processing/session_joins.txt',
    source_folder='/data/my_study/sessions',
    target_folder='/data/my_study/merged',
    overwrite='clean',
    raw_data='copy'
)

Remove original sessions after successful merge:

merge_sessions_list(
    studyfolder='/data/my_study',
    session_list='/data/my_study/processing/session_joins.txt',
    source_folder='/data/my_study/sessions',
    target_folder='/data/my_study/merged',
    overwrite='clean',
    raw_data='copy',
    original_sessions='remove'
)

Move original sessions to archive folder:

merge_sessions_list(
    studyfolder='/data/my_study',
    session_list='/data/my_study/processing/session_joins.txt',
    source_folder='/data/my_study/sessions',
    target_folder='/data/my_study/merged',
    overwrite='clean',
    raw_data='move',
    original_sessions='move:archive/pre_merge_sessions'
)