NeuroElf wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== spm5_preprojobs ======

===== Motivation =====
As said on the page describing the [[Processing stream - preprocessing|UI-based configuration of SPM5/SPM8 preprocessing]] in NeuroElf, this function is mostly meant to ensure that all subjects are preprocessed using the same parameters (and that all steps are performed in their entirety and same order).

===== Requirements =====
See the [[Processing stream - preprocessing|page on the GUI]].

===== Function reference ('help spm5_preprojobs') =====
<file>  spm5_preprojobs  - create jobs and jobhelps from options
 
  FORMAT:       [jobs, jobhelps, ff] = spm5_preprojobs(sf, fp, ap, opts)
  FORMAT:       spm5_preprojobs;
 
  Input fields:
 
        sf          subject (base) folder
        fp          functional folder pattern (e.g. f*/r*)
        ap          anatomical folder pattern (e.g. a*/*)
        opts        1x1 struct with options
         .afp       anatomical file pattern (default: '*.img' / '*.nii');
         .ffp       anatomical file pattern (default: '*.img' / '*.nii');
         .fsingle   force images to single precision (default: true)
         .fun2str   boolean flag, coregister func2struct (default: true)
         .jobfile   save output into a mat file (full or partial filename)
         .jobrun    flag, run jobs?
         .normsess  normalize sessions separately (only epi, default: false)
         .normtype  normalization type, one of 'anat', 'epi', {'segment'}
         .reganat   register anatomical scan to T1 template (default: true)
         .reslice   re-slice images are realignment (default: true)
         .rinterpe  realignment estimation spline degree (default: 2)
         .rinterpr  realignment reslicing spline degree (default: 4)
         .rqual     realignment quality (accuracy trade-off default: 0.9)
         .rrtm      realignment register-to-mean flag (default: true)
         .rsep      realignment sampling grid resolution (default: 3mm)
         .skip      skip N volumes at beginning of each run (default: 0)
         .smk       smoothing kernel (either 1x1 or 1x3 double, default: 6)
         .spmv      which SPM version (if empty, auto detect)
         .st        flag, perform slice time correction (default: true)
         .sto       slice acquisition order, either of
                    'a', 'aie', {'aio'}, 'd', 'die', 'dio' or numeric list
         .str       reference slice (default: 1)
         .stta      TA (default: auto)
         .sttr      TR (default: 2 sec)
         .wbb       normalize writing bounding box
                    (default: [-78, -114, -54; 78, 78, 84])
         .winterp   normalize writing interpolation spline (default: 1)
         .wvox      normalize writing voxel size (default: [3, 3, 3])
 
  Output fields:
 
        jobs        cell array with jobs suitable for spm_jobman
        jobhelps    cell array with helps (required when saved as jobs.mat)
        ff          cell array with functional files (after preprocessing)
 
  Note: without inputs, the UI-based mode will be used.</file>

===== Arguments and options =====

==== sf ====
This must be a single folder name (the UI loops over all folders matching a pattern!) containing separate folders for the anatomical and each functional scan (run).

==== fp ====
A foldername pattern, relative to the ''sf'' argument, specifying the location of the folders (plural!) of the functional runs.

==== ap ====
A foldername (or pattern), relative to the ''sf'' argument, specifying the location of the folder containing the anatomical scan.

==== opts ====
Optional settings in a 1x1 ''struct'':

==== .afp ====
Filename pattern for the anatomical scan (image), defaults to ''{'*.img', '*.nii'}''.

==== .ffp ====
Filename pattern for the functional files, defaults to ''{'*.img', '*.nii'}''.

==== .fsingle ====
Boolean flag, if set to ''true'' forces the data to single precision float (which mostly eliminates the problem of rounding errors for each preprocessing step).

==== .fun2str ====
Boolean flag, if set to ''true'' coregisters the functional to the anatomical data, otherwise vice versa.

==== .jobfile ====
If given and set to a valid '''filename.mat''' string, save the resulting jobfile to disk.

==== .jobrun ====
Boolean flag, if set to ''true'' execute resulting jobs (using ''spm_jobman('run', jobs);'').

==== .normsess ====
Boolean flag, if set to ''true'' normalizes each functional run (session) separately (only effective if ''.normtype'' is set to '''epi''').

==== .normtype ====
Choice of normalization algorithm. One of

  * '''anat''' - use ''spm_normalize'' on the anatomical data (using the T1.nii template image) to determine the non-linear warping parameters from the individual subject space to MNI space
  * '''epi''' - use ''spm_normalize'' on the functional data (using the EPI.nii template image) to determine the non-linear warping parameters from the individual subject space to MNI space (potentially allowing to normalize each run/session separately, see ''.normsess'' flag).
  * '''segment''' - use SPM's Unified Segmentation approach on the anatomical data (several prior images from the ICBM atlas are used) to determine the non-linear warping parameters from the individual subject space to MNI (ICBM-MNI) space

**Please note that the final location of activation peaks (across subjects) will differ based on your choice of normalization algorithm!**

==== .reganat ====
Boolean flag, if set to ''true'' begin processing by coregistration of the anatomical dataset to the T1 template image (in some cases improving the outcome of the segmentation algorithm substantially).

==== .reslice ====
Boolean flag, if set to ''true'' reslice the data after motion correction (mostly useful if you also wish to look at subject-only results prior to further processing steps, such as smoothing). **If the ''.fsingle'' flag is set to false, it is advisable to also set this flag to false to reduce the amount of rounding error in the preprocessed images!**

==== .rinterpe ====
Sets the interpolation degree of SPM's sampling function for the estimation component of the realignment step.

==== .rinterpr ====
Sets the interpolation degree of SPM's sampling function for the reslicing component of the realignment step (only in effect if ''.reslice'' is set to true).

==== .rqual ====
Sets the realignment quality value, which is a trade-off value between quality (1) and speed (smaller than 1), setting the ratio of voxels to be maximally included in the estimation of motion (see SPM's manual for further instructions).

==== .rrtm ====
Boolean flag, if set to ''true'' perform "realignment-to-mean" (two-pass realignment, whereas the first pass generates a mean image after preliminary motion correction and the second pass then determines motion as rotation and translation relative to this mean image). Usually improves the quality of motion correction at the cost of increased processing time.

==== .rsep ====
Sets the realignment (motion estimation) sampling grid resolution (see SPM's manual for further instructions). Generally, the higher the number, the faster (and less precise) the process becomes.

==== .skip ====
Number of volumes to skip (from raw data); this can be used to "discard" of the volumes in the data that suffer from incomplete T2* contrast saturation.

==== .smk ====
Smoothing kernel in mm. If set to 0, smoothing step is removed from processing stream.

==== .st ====
Boolean flag, if set to ''true'' perform slice-timing correction.

==== .sto ====
Sets the order of slices for the slice-timing correction step of **''N''** slices, can be either of
  * '''a''' - ascending (equates to ''1:N'')
  * '''aie''' - ascending, interleaved acquisition, even-numbered slices first (equates to ''[2:2:N, 1:2:N]'')
  * '''aio''' - ascending, interleaved acquisition, odd-numbered slices first (equates to ''[1:2:N, 2:2:N]'')
  * '''d''' - descending (equates to ''N:-1:1'')
  * '''die''' - descending, interleaved acquisition, even-numbered slices first (depending on whether ''N'' is even or odd equates to ''[N:-2:1, (N-1):-2:1]'' or ''[(N-1):-2:1, N:-2:1]'')
  * '''dio''' - descending, interleaved acquisition, odd-numbered slices first (depending on whether ''N'' is even or odd equates to ''[(N-1):-2:1, N:-2:1]'' or ''[N:-2:1, (N-1):-2:1]'')
  * a numeric list of all integer numbers in the range (and including) 1 through N, each number occurring exactly once

==== .str ====
Sets the reference slice number for the slice-timing correction step.

==== .stta ====
Sets the TA (time-of-acquisition in seconds) for one volume of data for the slice-timing correction step.

==== .sttr ====
Sets the TR (repetition time in seconds) for the slice-timing correction step.

==== .wbb ====
Sets the bounding box for the call to the ''spm_write_sn'' function. See the SPM manual for further instructions.

==== .winterp ====
Sets the interpolation degree of SPM's sampling function for the ''spm_write_sn'' call.

==== .wvox ====
Sets the voxel size for the ''spm_write_sn'' call.

===== Usage notes =====
If called without arguments, a [[Processing stream - preprocessing|UI window]] opens, that allows to configure these values interactively. If multiple subjects are found and configured, this function (spm5_preprojobs) is called for each of those subjects in turn.