Skip to content

Batch Process

Jump to bottom
Jaspreet Dodd edited this page Jun 17, 2024 · 5 revisions

Instead of using the mouse, messages can also be loaded from a batch file and sent automatically to the GUI as a batch. The first advantage of the batch process is that it dramatically reduces Human-Computer Interactions. You can issue batches at the end of a day, and the computer will create all sessiondata files in sequence and run the analysis. When you come back next day, a PLS result file will be ready. The second advantage is that it is very easy to modify a batch file to re-create a sessiondata file or re-run an analysis. The third advantage is that the sessiondata files and result files that are generated from batch files are fully compatible with those that are generated from the GUI. The only disadvantage is that batch files must be checked carefully, especially when you want to run batches unattended.

How to write a batch file

In order to create datamats or run analyses in batch, you will first need to prepare corresponding batch files. Batch files are simply text files, and we will discuss them in detail in the following sections.

Coming with PLS Applications, you will find several demo batch files:

batch_demo_fmri_data1.txt % batch file to create E.R.fMRI sessiondata

batch_demo_fmri_data2.txt % batch file to create E.R.fMRI sessiondata

batch_demo_fmri_data3.txt % batch file to create E.R.fMRI sessiondata

batch_demo_fmri_analysis.txt % batch file to run E.R.fMRI PLS analysis

batch_demo_bfm_data1.txt % batch file to create Blocked fMRI sessiondata

batch_demo_bfm_data2.txt % batch file to create Blocked fMRI sessiondata

batch_demo_bfm_data3.txt % batch file to create Blocked fMRI sessiondata

batch_demo_bfm_analysis.txt % batch file to run Blocked fMRI PLS analysis

batch_demo_erp_data1.txt % batch file to create ERP sessiondata

batch_demo_erp_data2.txt % batch file to create ERP sessiondata

batch_demo_erp_analysis.txt % batch file to run ERP PLS analysis

batch_demo_pet_data1.txt % batch file to create PET sessiondata

batch_demo_pet_data2.txt % batch file to create PET sessiondata

batch_demo_pet_analysis.txt % batch file to run PET PLS analysis

batch_demo_struct_data1.txt % batch file to create Structural sessiondata

batch_demo_struct_data2.txt % batch file to create Structural sessiondata

batch_demo_struct_analysis.txt % batch file to run Structural PLS analysis

Once you follow the instructions discussed in the following sections and create your own batch file, you can run them using batch_plsgui command.

  • You can run several batch files with one batch call. The following command will create an ERP sessiondata file, and run ERP analysis with the created sessiondata file: batch_plsgui batch_demo_erp_data1.txt batch_demo_erp_analysis.txt

  • You can also streamline the batch processing by putting multiple batch calls in one M file. The following will create three fMRI sessiondata files, and run fMRI analysis with the created sessiondata files: batch_plsgui batch_demo_fmri_data1.txt

batch_plsgui batch_demo_fmri_data2.txt

batch_plsgui batch_demo_fmri_data3.txt

batch_plsgui batch_demo_fmri_analysis.txt

The easiest way to get started is to copy a demo batch file from PLS Applications, and then modify it based on your scenario:

  1. Go to plsgui folder in PLS Applications. If you don't know where it is, you can type which plsgui in MATLAB command window to locate the path.
  2. Search batch_demo_MODULE* for MODULE related batch files. e.g. batch_demo_erp* is for ERP related batch files. batch_demo_erp_data1.txt is for creating ERP sessiondata file for group1; batch_demo_erp_analysis.txt is for running ERP analysis.
  3. Copy all related batch files to your working folder that you prepare to keep the result. You may remember that result file must be kept in the same folder as sessiondata files and batch files that are used when creating the result.
  4. Rename the demo batch files, and edit them with the necessary changes. Sections below and comments in those batch files explain how to edit them.
  5. Each batch file is composed of several lines. Empty line or any line starting with "%" will not be parsed. Each line starts with a keyword string (e.g. prefix, num_boot etc.). These keywords should never be changed. Following the keyword is its corresponding value. You can use either tab or space to separate "keyword / value" and "value1 / value2". At the end of value, you also have the option to append a comment starting with "%" character.
  6. Once you have modified (or created) batch files, you can put all batch calls into an M file, so they can be executed one after the other (see batch_demo_*.m).

Tips: The easiest way to get batch file for running PLS analysis is to click Save to Batch button in PLS analysis window. The GUI will automatically write all parameters on PLS Analysis window to a batch file.

Batch file to create E.R.fMRI sessiondata

Instead of filling the fields in the Session Information window manually, we can put them as the values of keywords in a batch file (see batch_demo_fmri_data1.txt):

  1. Value of prefix keyword is a string (e.g. demo) that will compose sessiondata file name (e.g. demo_fMRIsessiondata.mat).
  2. Value of brain_region keyword can be either a threshold number or a file name with path info that indicates the brain region binary file.
  3. Value of win_size keyword indicates the number of scans in one hemodynamic period.
  4. Value of across_run keyword can be either 1 or 0. Use 1 for merging data across all run for each condition, and use 0 for merging data within each run and then stacked together run by run.
  5. Value of single_subj keyword refers to a feature that does not average all onsets in a condition. To use this feature, set it to 1, and scans that are led by each onset will be treated as an individual block in the datamat. Otherwise, scans for all the onsets will be averaged together as one block.
  6. Value of single_ref_scan keyword refers to a feature that will replace the ref_scan_onset keyword and num_ref_scan keyword below. To use this feature, set it to 1, and all scans in this datamat will use this reference scan.
  7. Value of single_ref_onset keyword is the onset for single_ref_scan keyword above, and starting from 0.
  8. Value of single_ref_number keyword is the number of onset for single_ref_scan keyword above, and starting from 1.
  9. Value of the first cond_name keyword is name of condition1, and the name of condition2 is listed after condition1 in sequence for value of the second cond_name keyword. 10,. Value of the first ref_scan_onset keyword is the reference scan onset for condition1, and the one for condition2 is listed afterwards in sequence for value of the second ref_scan_onset keyword.
  10. Value of the first num_ref_scan keyword is the number of reference scans for condition1, and the one for condition2 is listed afterwards in sequence for value of the second num_ref_scan keyword.
  11. You can re-organize them to let cond_name, ref_scan_onset, and num_ref_scan be grouped together (see batch_fmri_data1.txt). However, sequence should not be changed (i.e. name for condition2 can not be listed before name for condition1). The same rule is also applied to ref_scan_onset & num_ref_scan in condition section and data_files & event_onsets in run section.
  12. Value of the first data_files keyword stands for all selected file names of scan images in run1 with path information. All selected image file names in the run folder should be sorted in alphabetic ascend order that represent scans of this run in time series sequence. Wildcard must be used for all selected file names. Run2 is listed after run1 in sequence for value of the second data_files keyword.
  13. Values of the first event_onsets keyword stand for the onset scans (start from 0) of condition1 in run1. Then, condition2 in run1 for values of the second event_onsets keyword ... etc. So the sequence should always be condition in run.

Batch file to run E.R.fMRI analysis

As I mentioned above, the easiest way to get batch file for running PLS analysis is to click Save to Batch button in PLS Analysis window. However, if you want, you can also manually create such a batch file (see batch demo_fmri_analysis.txt_):

  1. Value of result_file keyword is a string for result file name with path information. It must be listed first in the analysis batch file.
  2. Values of the first group_files keyword stand for all sessiondata file names for group1. (In E.R.fMRI or Blocked fMRI, each group can contain more than one sessiondata file, and each sessiondata file can have more than one run). Group2 is listed after group1 in sequence for value of the second group_files keyword.
  3. You have 6 PLS analysis option. Set value of pls keyword to 1 if you would like to do Mean-Centering PLS; set it to 2 for Non-Rotated Task PLS; set it to 3 for Regular Behav PLS; set it to 4 for Multiblock PLS; set it to 5 for Non-Rotated Behav PLS; set it to 6 for Non-Rotated Multiblock PLS.
  4. Value of mean_type keyword refers to mean-centering type. It can be [0 1 2 3], and default value is 0.
  5. Value of cormode keyword refers to correlation mode. It can be [0 2 4 6], and default value is 0.
  6. Value of num_perm keyword refers to number of permutations.
  7. Value of num_split keyword refers to number of split half permutations.
  8. Value of num_boot keyword refers to number of bootstraps.
  9. Value of boot_type keyword refers to bootstrap type. It can be strat or nonstrat, and default is strat (Please do not change this value).
  10. Value of clim keyword refers to confidence level of bootstrap test for Behavior (or Multiblock) PLS.
  11. Value of save_data keyword can be either 0 or 1. Choose 1 if you would like to save the stacked datamat; choose 0 otherwise.
  12. Leave values of selected_cond keyword commented if you do not deselect any condition. Otherwise, use only 1 or 0 for the value of each condition, where 0 stands for the deselected condition (condition for behavior block in multiblock PLS is not deselected here, and they should be deselected by selected_bcond below).
  13. Leave values of selected_bcond keyword commented if you do not deselect any condition for behavior block in multiblock PLS. Otherwise, use only 1 or 0 for the value of each condition, where 0 stands for the deselected conditions (keyword selected_bcond is only applied to conditions for behavior block in multiblock PLS). In addition, you cannot select any conditions for selected_bcond that were deselected in selected_cond.
  14. Values of the first contrast_data stand for the contrast data of selected condition1 in group1. Then, selected condition2 in group1 for value of the second contrast_data keyword ... etc. So the sequence is selected condition in group. Number of values for each contrast_data row should be the same, and it represents the number of contrasts.
  15. Values of the first behavior_data stand for the behavior data of subject1 of selected_condition1 of run1 of group1. The sequence should always be subject in selected_condition in run in group. Number of values on each behavior_data row should be the same, and it represents the number of behavior measures.

Batch file to create Blocked fMRI sessiondata

It is very similar to Batch file to create E.R.fMRI sessiondata. Here are some differences:

  1. No win_size keyword for Blocked fMRI.
  2. event_onsets keyword is replaced by block_onsets.
  3. block_length keyword is used after each block_onsets to represents the number of scans for each block.

Batch file to run Blocked fMRI analysis

It is very similar to Batch file to run E.R.fMRI analysis. The only difference would be that all the file names containing fMRI are now replaced by BfMRI.

Batch file to create ERP sessiondata

ERP sessiondata file is very different from that of E.R.fMRI or Blocked fMRI, since a lot of EEG/ERP parameters have to be added in:

  1. Value of prefix keyword is a string (e.g. demo) that will compose sessiondata file name (e.g. demp_ERPsessiondata.mat and demo_ERPdata.mat).

  2. Value of prestim keyword stands for the number of milliseconds for prestimulus baseline.

  3. Value of interval keyword stands for the number of milliseconds for digitization interval.

  4. Values of chan_order keyword are indices for electrode channels. The best way to obtain them is run MATLAB command: [chan_order, system] = erp_select_chan

  5. Value of system_class keyword takes structure variable value system.class that was obtained together with chan_order.

  6. Value of system_type keyword takes structure variable value _system.type _that was obtained together with chan_order.

  7. If your data are in plain text file, leave binary_vendor keyword commented or put none for its value. Otherwise, fill the value of binary_vendor keyword with the name of binary data vendor. They can be NeuroScan, ANT, and EGI.

  8. If your data are in plain text file, leave binary_endian keyword commented, or put none for its value. Otherwise, fill the value of binary_endian keyword with a proper MATLAB machine format, they can be: ieee-le or l, ieee-be or b, ieee-le.l64 or a, ieee-be.l64 or s, vaxd or d, vaxg or g, cray or c, and native or n.

  9. Value of the first cond_name keyword is name of condition1, and the name of condition2 is listed after condition1 in sequence for value of the second cond_name keyword.

  10. All binary data and most plain text data are laid out in a way that each row represents an electrode channel. However, there are a few plain text data that are laid out in a way that each column represents an electrode channel. In the latter case, set the value of chan_in_col keyword to 1.

  11. Value of the first subj_file keyword stands for ERP data file name with path information for subject 1 in condition 1. Then, subject 2 in condition 1 for value of the second subj_file keyword ... etc. So the sequence should always be subject in condition.

Batch file to run ERP analysis

It is very similar to Batch file to run E.R.fMRI or Blocked fMRI analysis. Here are the differences:

  1. All file names that contain fMRI or BfMRI are now replaced by ERP.
  2. ERP and PET modules use only one sessiondata file for each group_files keyword, while fMRI and BfMRI can use more sessiondata file names.
  3. The sequences should be subject in selected_condition in group for the value of behavior_data keyword.

Batch file to create PET sessiondata

It is very similar to Batch file to create ERP sessiondata. Since PET does not use any of EEG/ERP parameters, those keywords can all be removed except prefix, cond_name, and subj_file. However, brain_region and normalize keyword needs to be added in. brain_region value can be either a threshold number or a file name with path information that indicates the brain region binary file. normalize value is either 1 or 0, and keep it as 1 (normalize volume mean) unless you have good reason not to do so.

Batch file to run PET analysis

It is very similar to Batch file to run ERP analysis. The only difference would be that all the file names containing ERP are now replaced by PET.

Batch file to create Structural sessiondata

It is very similar to Batch file to create PET sessiondata. Here are the differences:

  1. Since Structural module cannot use threshold, a pre-defined brain region image file must be used for brain_region keyword.
  2. Value of dataset_path keyword is a string that represents subject files' folder.
  3. Value of normalize keyword should be kept as as 0 (do not normalize volume mean) unless you have good reason not to do so.
  4. Value of cond_filter keyword is a string of wildcard to distinguish different conditions.
  5. Value of subj_name keyword is a string of subject's name.
  6. Value of subj_file keyword is just the subject's file name, and does not need to include its path.

Batch file to run Structural analysis

It is very similar to Batch file to run ERP analysis. The only difference would be that all the file names containing ERP are now replaced by STRUCT.

Clone this wiki locally