GLM Analysis

Overview

clpipe includes functions to help you set up and run general linear models (GLM) on your neuroimaging data. It uses FSL’s implementation of GLM (FEAT), and the functions provided in clpipe serve to help setup and manage the necessary files and folders.

Currently, clpipe includes the following commands:

  1. fsl_onset_extract

    This function will extract task trial onset, duration and an optional parametric variable from the BIDS formatted events files, and constructs a set of FSL 3-column EV files.

  2. glm_l1_preparefsfs

    This function takes an fsf file that you have generated as a prototype, and copies/modifies it for use with the images in your dataset. Multiple different L1 fsfs can be used, and images can be excluded or explicitly included in a given L1. See below for details on the glm configuration file.

  3. glm_l1_launch

    Use this command to launch the fsf files generated by the glm_l1_preparefsfs command.

  4. glm_l2_preparefsfs

    This function takes an fsf file, and a csv sheet that contains information about which image goes with which subject, and copies/modifies the fsf file for use with your dataset. Similarly to L1, multiple L2 fsf files can be specified. See below for details on how to do this.

  5. glm_l2_launch

    Use this command to launch the fsf files generated by the glm_l2_preparefsfs command.

Configuration

clipe’s GLM commands are all driven by a GLM configuration that is seperate from the main configuration file of a project. A GLM configuration file describes the L1 and L2 setup for a single task. It is structured as follows:

Preamble

  • GLMName: Descriptive Name

  • Authors: Author List

  • DateCreated: Date

  • GLMSetupOptions: Options for the initial resampling of data

    • ParentClpipeConfig: File path to project’s clpipe config json,

    • TargetDirectory: Directory containing the image files, defaults to fmriprep directory,

    • TargetSuffix: Suffix that designates the files to be resampled, defaults to space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz,

    • WorkingDirectory: Working directory, must be user specified,

    • TaskName: Name of the task that the GLM is run on, must be the same as in the task-*, descriptors

    • ReferenceImage: Reference image, used to determine dimensions and resolution. Should be the reference image for the space the data is normalized to, e.g. MNI152NLin2009cAsym ,

    • DummyScans: Number of timepoints at the beginning of the scan to drop. Specify as an integer

    • ApplyFMRIPREPMask: Apply brain mask, defaults to true

    • MaskFolderRoot: Root of the directory tree that contains the masks, defaults to fmriprep directory,

    • MaskSuffix: Suffix of the mask file, defaults to space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz,

    • SUSANSmoothing: Perform Susan Smoothing? Defaults to false

    • SUSANOptions: Options for SUSAN spatial smoothing

      • BrightnessThreshold: Brightness threshold for SUSAN

      • FWHM: Full Width Half Max (Same as in FEAT GUI, not the same as in SUSAN GUI)

    • PreppedDataDirectory: Output directory for resampled images, project setup defaults this to main project directory/data_glm,

    • PreppedSuffix: Suffix for resampled data, defaults to resampled.nii.gz,

    • PrepareConfounds: Boolean flag to prepare confound tables, defaults to true,

    • ConfoundSuffix: Suffix for files containing confound information, defaults to desc-confounds_regressors.tsv,

    • Confounds: A list of confound names. Note, the use of .* specifies a wildcard (i.e. a_comp_cor.* will extract all confounds that begin with a_comp_cor). Defaults to 6 motion parameters, CSF, WM and Global Signal.

    • ConfoundsQuad: Which confounds to calculate quadratic expansions. Defaults to previous confounds list.

    • ConfoundsDerive: Which confounds to calculate first derivatives? Defaults to previous confounds list.

    • ConfoundsQuadDerive: Which confounds to calculate quadratic expansions of first derivatives.

    • MotionOutliers: Calculate motion outliers. If true then dummy codes for motion outliers will be included in the confounds file. Defaults to true

    • ScrubVar: Which variable in the confounds file should be used to calculate motion outliers, defaults to framewise displacement

    • Threshold: Threshold at which to flag a timepoint as a motion outlier, defaults to .2

    • ScrubAhead: How many time points ahead of a flagged time point should be flagged also, defaults to 0

    • ScrubBehind: How many time points behind of a flagged time point should be flagged also, defaults to 0

    • ScrubContiguous: How many “good” contiguous timepoints are needed, defaults to 5

    • MemoryUsage: Memory usage, defaults to 5 GB

    • TimeUsage: Time usage, defaults to 1 hour

    • NThreads: Number of processing threads, defaults to 1

    • LogDirectory: Log directory, defaults to glm_setup_logs in the project logs directory.

Level 1 Onsets

The entry Level1Onsets contains the specification for extracting the onset timing files and transforming them into FSL three column format EV files.

  • EventFileSuffix: Suffix for the BIDS format event file. Unless your data is not in BIDS format, this likely shouldn’t be changed.

  • TrialTypeVariable: The name of the variable that contains information as to the trial type. Defaults to trial_type, which is a BIDS standard header for the events files, but can be changed to use any variable.

  • TrialTypeToExtract: The values of the trial type variable to extract. A warning will be thrown if there are no trials with a given trial type (which might indicate a misspelling or a mistake in this field)

  • TimeConversionFactor: The factor the onset/duration values need to be divided by to put them into units of seconds. For example, if your onsets are in milliseconds, this factor would be 1000. If in seconds, the factor is 1.

  • ParametricResponseVariable: The name of the variable in the events file that corresponds to the third column of the FSL 3 column format EV file. If left empty (“”), this defaults to 1

  • EVDirectory: What directory to output the EV files to.

Level 1 Setups

The entry Level1Setups contains a list of Level 1 specifications of the following form:

  • ModelName: Name of this L1 setup. Will be used when you use the glm_l1_preparefsfs function

  • TargetDirectory: Target directory containing the files to be analyzed, defaults to resampled data directory from GLM setup

  • TargetSuffix: File suffix that specifies which files are to be used, defaults to resampled.nii.gz,

  • FSFPrototype: A .fsf file that acts as the prototype for this setup,

  • ImageIncludeList: A list of which images should be included in this setup (MUTUALLY EXCLUSIVE WITH ImageExcludeList)

  • ImageExcludeList: A list of which images should NOT be included in this setup (MUTUALLY EXCLUSIVE WITH ImageIncludeList)

  • FSFDir: The directory that the generated .fsf files are created in, defaults to l1_fsfs,

  • EVDirectory: The directory that contains the onset files for each image. These files must be in FSL 3 column format. The filenames have specific structuring as well (see below),

  • ConfoundDirectory: Directory that contains the confound files, defaults to the directory containing the resampled data,

  • EVFileSuffices: A list of file suffices that specify which event file to use. NOTE: This list is ordered, so the first suffix corresponds with EV 1, the second with EV 2, etc.

  • ConfoundSuffix: Suffix that specifies which files are the confound files.

  • OutputDir: Where the resulting FEAT directories will be created.

Filenames for EV Onset Files

Event Onset files must be in the FSL 3 column format. Additionally, the file names for the onset files must be of the following form: filename of image - target suffix + EV file suffix. For example. If the image filename was “sub-1001_ses-01_task-gng_run-01_bold.nii.gz”, the target suffix was “_bold.nii.gz” and a EV suffix was “_hit.txt”, then the EV file should be named: “sub-1001_ses-01_task-gng_run-01_hit.txt``.

Level 2 Setups

The entry Level2Setups contains a list of Level 2 specifications of the following form:

  • ModelName: The model name, used in the glm_l2_preparefsfs function.

  • FSFPrototype: A .fsf prototype used in this setup.

  • SubjectFile: A .csv file containing information as to which images go into which L2 model. See below for details.

  • FSFDir: The directory in which the fsfs will be generated.

  • OutputDir: Which folder will the L2 gfeat folders be generated

Subject File Formatting

The L2 subject file maps each image onto a specific L2 model setup entry and onto a specific L2 model (i.e. assigns a subject’s images to that subject.) This is a three column csv file, with the headers: fsf_name, feat_folders, L2_name. The fsf_name column contains the desired name of a L2 fsf file, the feat_folders column contains the paths to the feat folders that are used in the L2 FSF files (in order), and the L2_name column contains which ModelName corresponds to a given image. For an example, see the l2_sublist.csv file generated when you run the project_setup function.

Commands

clpipe glm fsl_onset_extract

Convert onset files to FSL’s 3 column format.

clpipe glm fsl_onset_extract [OPTIONS]

Options

-config_file, -c <config_file>

Required Use a given configuration file.

-glm_config_file, -g <glm_config_file>

Required Use a given GLM configuration file.

-debug, -d

Print detailed processing information and traceback for errors.

clpipe glm fsl_onset_extract

Convert onset files to FSL’s 3 column format.

clpipe glm fsl_onset_extract [OPTIONS]

Options

-config_file, -c <config_file>

Required Use a given configuration file.

-glm_config_file, -g <glm_config_file>

Required Use a given GLM configuration file.

-debug, -d

Print detailed processing information and traceback for errors.

clpipe glm fsl_onset_extract

Convert onset files to FSL’s 3 column format.

clpipe glm fsl_onset_extract [OPTIONS]

Options

-config_file, -c <config_file>

Required Use a given configuration file.

-glm_config_file, -g <glm_config_file>

Required Use a given GLM configuration file.

-debug, -d

Print detailed processing information and traceback for errors.

clpipe glm fsl_onset_extract

Convert onset files to FSL’s 3 column format.

clpipe glm fsl_onset_extract [OPTIONS]

Options

-config_file, -c <config_file>

Required Use a given configuration file.

-glm_config_file, -g <glm_config_file>

Required Use a given GLM configuration file.

-debug, -d

Print detailed processing information and traceback for errors.

Legacy Commands

glm_l1_preparefsf

Propagate an .fsf file template for L1 GLM analysis.

You must create a template .fsf file in FSL’s FEAT GUI first.

glm_l1_preparefsf [OPTIONS]

Options

-glm_config_file, -g <glm_config_file>

Required Your GLM configuration file.

-l1_name <l1_name>

Required Name for a given L1 model as defined in your GLM configuration file.

-debug, -d

Flag to enable detailed error messages and traceback

glm_l1_launch

Launch all prepared .fsf files for L1 GLM analysis.

glm_l1_launch [OPTIONS]

Options

-glm_config_file, -g <glm_config_file>

Required The path to your clpipe configuration file.

-l1_name <l1_name>

Required Name of your L1 model

-test_one

Only submit one job for testing purposes.

-submit, -s

Flag to submit commands to the HPC.

-debug, -d

Flag to enable detailed error messages and traceback.

glm_l2_preparefsf

Propagate an .fsf file template for L2 GLM analysis.

You must create a group-level template .fsf file in FSL’s FEAT GUI first.

glm_l2_preparefsf [OPTIONS]

Options

-glm_config_file, -g <glm_config_file>

Required Your GLM configuration file.

-l2_name <l2_name>

Required Name for a given L2 model

-debug, -d

Flag to enable detailed error messages and traceback

glm_l2_launch

Launch all prepared .fsf files for L2 GLM analysis.

glm_l2_launch [OPTIONS]

Options

-glm_config_file, -g <glm_config_file>

Required The path to your clpipe configuration file.

-l2_name <l2_name>

Required Name of your L2 model

-test_one

Only submit one job for testing purposes.

-submit, -s

Flag to submit commands to the HPC.

-debug, -d

Flag to enable detailed error messages and traceback.