pull_sequence_names#

qx_utilities.general.utilities.pull_sequence_names(sessionsfolder='.', batchfile=None, sessions=None, filter=None, sourcefiles='session.txt', targetfile=None, overwrite='no', check='yes', report='yes')#

pull_sequence_names [sessionsfolder="."] [batchfile=None] [sessions=None] [filter=None] [sourcefiles="session.txt"] [targetfile="<sessionsfolder>/inbox/MR/sequences.txt"] [overwrite="no"] [check="yes"]

Gather a list of all the sequence names across the sessions and save it into a specified file.

Parameters

--sessionsfolder (str, '.'):

The base study sessions folder (e.g. WM44/sessions) where the inbox and individual session folders are. If not specified, the current working folder will be taken as the location of the sessionsfolder.

--batchfile (str, None):

An optional path to a batch file or a list file to take the sessions from. sessions and filter then select within it.

--sessions (str, None):

Either a string with pipe | or comma separated list of sessions (sessions ids) to be processed; glob patterns (*, ?, [abc]) may be used, e.g. "AP128,OP139,ER*". A *.list file with a list of session ids may be given instead.

--filter (str, None):

Optional parameter used to filter sessions to include.

It is specified as a string of <key>:<value> pairs joined by | (OR) or by & (AND) — one operator at a time:

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

Only the sessions the filter selects will be included in the list. Values may be glob patterns.

--sourcefiles (str, 'session.txt'):

A file or comma or pipe | separated list of files or grep patterns that define, which session description files to check.

--targetfile (str, None):

The path to the target file, a file that will contain the list of all the session names from all the individual session information files.

Note that targetfile is a parameter of four commands that write four different files, so a batch file header stating it points all of them at one path. State it per command, or keep it out of the header with --unset_batch_header_parameters=targetfile.

--overwrite (str, 'no'):

Whether to overwrite an existing file or not.

--check (str, 'yes'):

Check whether all the identified sessions have the specified information files.

The possible options are:

  • yes check and report an error if no information exists for a session

  • warn warn and list the sessions for which the neuroimaging

    information was not found

  • no do not run a check, ignore sessions for which no imaging

    data was found

--report (str, 'yes'):

Whether to include date when file was generated and the final report in the compiled file ('yes') or not ('no').

Notes

The command will use the sessionsfolders, sessions and filter parameters to create a list of sessions to process. For each session, the command will use the sourcefiles parameter to identify neuroimaging information files from which to generate the list from. If no file is found for a session and the check parameter is set to yes, the command will exit with an error.

Once the files for each session are identified, the command will inspect the files for imaging data and create a list of sequence names across all sessions. The list will be saved to a file specified using targetfile parameter. If no path is specified, the default location will be used:

<sessionsfolder>/inbox/MR/sequences.txt

If a target file exists, it will be deleted and replaced, if the overwrite parameter is set to 'yes'. If the overwrite parameter is set to 'no', the command will exit with an error.

File format:

The command expects the neuroimaging data to be present in the standard 'session.txt' files. Please see online documentation for details. Specifically, it will extract the first information following the sequence name.

The resulting file will be a simple text file, with one sequence name per line. In addition, if report is set to 'yes' (the default), the resulting file will start with a comment line stating the date of creation, and at the end additional comment lines will list the full report of missing files and errors encountered while gathering behavioral data from individual sessions.

Examples

qunex pull_sequence_names sessions="AP*"

The command will compile sequence names present in session.txt files present in all <session id> folders that match the "AP*" glob pattern in the current working directory.

The resulting file will be save in the default location:

<current folder>/inbox/MR/sequences.txt

If any of the identified sessions do not include data or if errors are encountered when processing the data, the command will exit with an error.

qunex pull_sequence_names sessionsfolder="/data/myStudy/sessions"

sessions="AP*|OP*" sourcefiles="session.txt|subject.txt" check="warn" overwrite="yes" report="no"

The command will find all the session folders within /data/myStudy/sessions It will then look for presence of either session.txt or subject.txt files. The compiled data from the found files will be saved in the default location. If a file already exists, it will be overwritten. If any errors are encountered, the command will not throw an error, however it also won't report a successful completion of the task. The resulting file will not have information on file generation or processing report.

qunex pull_sequence_names sessionsfolder="/data/myStudy/sessions" \
        sessions="/data/myStudy/processing/batch.txt" \
        filter="group:controls|behavioral:yes" \
        sourcefiles="*.txt" \
        targetfile="/data/myStudy/sessions/specs/hcp_mapping.txt" \
        check="no" overwrite="yes"

The command will read the session information from the provided batch.txt file. It will then process only those sessions that have the following lines in their description:

group: control
behavioral: yes

For those sessions it will find any files that end with .txt and process them for presence of neuroimaging information. The compiled data will be saved to the specified target file. If the target file exists, it will be overwritten. The command will print a full report of the processing, however, it will exit with reported success even if missing files or errors were encountered.