export_hcp

qx_utilities.hcp.export_hcp.export_hcp(sessionsfolder='.', batchfile=None, sessions=None, filter=None, mapaction='link', mapto=None, overwrite='no', mapexclude=None, hcp_suffix='', verbose='no')

export_hcp [sessionsfolder="."] [batchfile=None] [sessions=None] [filter=None] [mapaction=<how to map>] [mapto=None|<location to map to>] [overwrite="no"] [mapexclude=None] [hcp_suffix=""] [verbose="no"]

Export HCP style data out of the QuNex Suite file structure.

Parameters

--sessionsfolder (str, default '.'):

The base study sessions folder within the QuNex folder structure to or from which the data are to be mapped. If not specified explicitly, the current working folder will be taken as the location of the sessionsfolder.

--batchfile (str, default ''):

A path to a batch.txt file.

--sessions (str, default ''):

A list of sessions to map (comma/pipe-separated, patterns allowed). When a batch file is given, it selects within it.

--filter (str, default ''):

An optional string of <key>:<value> pairs joined by | (OR) or by & (AND) — one operator at a time, used to select sessions within the given batch file. Values may be glob patterns.

--mapaction (str, default 'link'):

How to map the data: copy, link, or move.

--mapto (str, default ''):

Target location to map to when exporting.

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

Whether to overwrite existing files at the target, skip them, or abort.

--mapexclude (str, default ''):

Comma separated list of regex patterns that match files to exclude from mapping.

--hcp_suffix (str, default ''):

Optional suffix appended to session id under the hcp folder.

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

Report details while running.

Notes

The function maps HCP style data out of QuNex data structure. How to do the mapping (move, copy, link) is specified by the mapaction parameter. The overwrite parameter specifies whether to replace any existing data at the target location if it already exist. The target location has to be provided by the mapto parameter.

The function first prepares the mapping. Next it checks that the mapping can be conducted as specified by the parameters given. If the check identifies any potential issues, no mapping is conducted to avoid an incomplete mapping. Do note that the check only investigates the presence of source and target files, it does not check, whether the user has permission on the file system to execute the actions.

This mapping supports the data preprocessed using the HCP Pipelines following the Life Span (LS) convention. The processed derivatives from the HCP pipelines are mapped into the specified target location on the file system to comply with the HCPLS output expectations. The mapping expects that HCPLS folder structure was used for the processing. The function will map all the content of the session's hcp directory to a corresponding session directory in the indicated target location. If any part of the unprocessed data or the results are not to be mapped, they can be specified using the mapexclude parameter.

Examples

We will assume the following:

• data to be mapped is located in the folder /data/studies/myStudy/sessions

• a batch file exists in the location /data/studies/myStudy/processing/batch.txt

• we would like to map the data to location /data/outbox/hcp_formatted/myStudy

given the above assumptions the following example commands can be run:

qunex export_hcp \
    --sessionsfolder=/data/studies/myStudy/sessions \
    --batchfile=/data/studies/myStudy/processing/batch.txt \
    --mapto=/data/outbox/hcp_formatted/myStudy \
    --mapexclude=unprocessed \
    --mapaction=link \
    --overwrite=skip

Using the above commands the data found in the /data/studies/myStudy/sessions/<session id>/hcp/<session id> folders, excluding the unprocessed folder would be mapped to the /data/outbox/hcp_formatted/myStudy/<session id> folder for all the sessions listed in the batch.txt file. Specifically, folders would be recreated as needed and hard-links would be created for all the files to be mapped. If any target files already exist, they would be skipped, but the processing of other files would take place anyway.

qunex export_hcp \
    --sessionsfolder=/data/studies/myStudy/sessions \
    --batchfile=/data/studies/myStudy/processing/batch.txt \
    --mapto=/data/outbox/hcp_formatted/myStudy \
    --filter="group:controls|institution:Yale" \
    --mapaction="copy" \
    --overwrite=no

Using the above commands, only data from the sessions that are marked in the batch.txt file to be from the control group and acquired at Yale would be mapped. In this case, the files would be copied and if any files would already exist in the target location, the mapping would be aborted altogether.

qunex export_hcp \
    --sessionsfolder=/data/studies/myStudy/sessions \
    --batchfile=/data/studies/myStudy/processing/batch.txt \
    --mapto=/data/outbox/hcp_formatted/myStudy \
    --sessions="AP*,HQ*" \
    --mapaction="move" \
    --overwrite=yes

Using the above commands, only the sessions that start with either "AP" or "HQ" would be mapped, the files would be moved and any existing files at the target location would be overwritten.

qunex export_hcp \
    --sessionsfolder=/data/studies/myStudy/sessions \
    --batchfile=/data/studies/myStudy/processing/batch.txt \
    --mapto=/data/outbox/hcp_formatted/myStudy \
    --mapaction="link" \
    --mapexclude="unprocessed,MotionMatrices,MotionCorrection" \
    --overwrite=skip

Using the above commands, all the sessions specified in the batch.txt would be processed, files would be linked, files that already exist would be skipped, and any files for which the path include 'unprocessed', ' MotionMatrices' or 'MotionCorrection' would be excluded from the mapping.