# Batch files Preprocessing and analysis commands are typically run on batches of sessions that most often represent all the sessions in a study. Additionally, a number of parameters that are to be used in preprocessing and analysis commands are stable and do not change between command invocations. To facilitate processing of batches of sessions from small sets to thousands, QuNex utilizes batch files. The basic name for a batch file is something like `batch.txt`; however, any name can be used, which allows setting up separate versions of batch files for different purposes or preprocessing and analysis variants. A batch file (e.g. `batch.txt`) consists of two core elements: * the parameter header * the session-level information for all sessions to be processed with the parameters in the header The information for the parameter header is typically taken from the parameter file (commonly stored in: `//spec/parameters.txt`) to allow flexible deployment and re-generation of the batch file for a given set of sessions. The final batch files are by default stored in `//processing/` to allow easy access to all the study-specific batch iterations. In principle the final batch file can be stored anywhere as long as the relevant QuNex command specifies its absolute path. ## Batch file group-level header information The header element of the batch file provides group-level information that will be used across all specified sessions in a form of `--parameter : value` pairs, one per line. Here is a concrete example of a group level section (for full details of all the parameter explanation see `~/qunex/python/qx_utilities/templates/parameters_example.txt`): ``` bash # --- basic settings --image_source: hcp --image_target: cifti --log: keep --glm_matrix: both --glm_residuals: forget --bold_preprocess: WM|flanker|rest --base_folder: /data/studies/WM3/sessions --TR: 2.5 --omit: 0 --pignore: hipass=linear|regress=ignore|lopass=linear # --- nuisance signal --shrinknsroi: true # --- smoothing parameters --surface_smooth: 4 --volume_smooth: 4 --voxel_smooth: 3 --smooth_mask: nonzero ``` Note that lines starting with `#` are ignored and can be used for comments or to remove specific parameters. Please note that if a parameter is specified in the batch file, QuNex will set it to the value specified. This is also the case for parameters that are left empty (e.g. `_event_file :`). In this case, the `_event_file` parameter is actually being set to an empty string and is being read as such by QuNex. The situation where this would be a misspecification would be, for instance: `_nprocess :`. In this case the `_nprocess` parameter checks how many concurrent jobs to run. If it is set to an empty string then the QuNex engine cannot set the process number. This behavior is important so that the QuNex engine can interpret all specified parameters based on actual values provided (empty or some value) as opposed to making an assumption that the parameter is absent when in fact it is present with an empty string. ## Batch file session-level information following the header Information for each session has the same format as the session information files. To separate information from individual sessions, each new session section has to start with three dashes (`---`) in a line. Continuing the example from above, the session level information could start with: ``` bash --- session: NK3 subject: NK3 dicom: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK03/dicom raw_data: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK03/nii hpc: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK03/hpc age: 21 handedness: right gender: male group: control 01: Survey 02: T1w: T1w 0.7mm N2 03: T2w: T2w 0.7mm N2 04: Survey 05: SE-FM-AP: C-BOLD 3mm 48 2.5s FS-P 06: SE-FM-PA: C-BOLD 3mm 48 2.5s FS-A 07: bold1:rest: BOLD 3mm 48 2.5s 08: bold2:task: BOLD 3mm 48 2.5s 09: bold2:task: BOLD 3mm 48 2.5s --- session: NK4 subject: NK4 dicom: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK04/dicom raw_data: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK04/nii hpc: /Volumes/pooh/NK/fMRI/PD-fcMRI-TMS/sessions/NK04/hpc age: 24 handedness: left gender: female group: intervention 01: Survey 02: T1w: T1w 0.7mm N2 03: T2w: T2w 0.7mm N2 04: Survey 05: SE-FM-AP: C-BOLD 3mm 48 2.5s FS-P 06: SE-FM-PA: C-BOLD 3mm 48 2.5s FS-A 07: bold1:rest: BOLD 3mm 48 2.5s 08: bold2:task: BOLD 3mm 48 2.5s 09: bold2:task: BOLD 3mm 48 2.5s ``` Note that the information above is also referenced inside the session-specific `session_.txt` files. ## Generating batch files for preprocessing The QuNex batch files described above are the 'workhorse' of the preprocessing workflow as they can flexibly specify all relevant parameters in a header component of the file, followed by a listing of all relevant sessions to work on. Once all the data is gathered, the batch file needs to be compiled. These files (commonly named `batch.txt`) list information for all the sessions, as well as study parameters, so that they don't have to be specified with each invocation of a given QuNex command, which flexibly reads the relevant header parameter subset. The key advantage here is that for rapid re-processing or specification of new parameters, even within a single study, use of batch files accelerates this workflow. To help with generation of batch files, QuNex provides a convenient [`create_batch`](../../api/gmri/create_batch.rst) command. The command scours all the subfolders in the study sessions directory for the specified session information files and joins them in the specified target file. If desired, the sessions to add can be specified explicitly or taken from another batch or list file. Run `qunex ?create_batch` for more detailed information on the command use. As noted, the command also prepends the specific batch header parameters. They need to be provided if they are saved in a specific header batch parameters file. The default location of the batch header files is in `//sessions/specs/`. If the batch file does not exist, an example will be created automatically, placing all the possible parameters into the header, their default values and explanations to allow easy editing. The command also supports appending new sessions to an existing batch file. The final batch file with the appended session information is saved in `//processing/.txt`. This file should be used in subsequent processing. Note that if a batch file already exists then the parameter file will not be added to the header of the batch unless `--overwrite` parameter is set to `yes`. If `overwrite` is set to `append`, then the parameters will not be changed; however, any sessions that are not yet present in the batch file will be appended at the end of the batch file. Please see additional help regarding compiling a batch file on [Running HCP minimal preprocessing pipeline](../UsageDocs/HCPPreprocessing) page.