User Tools

Site Tools


spm5_preprojobs

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

spm5_preprojobs [2011/04/03 06:23] (current)
jochen created
Line 1: Line 1:
 +====== 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.
  
spm5_preprojobs.txt ยท Last modified: 2011/04/03 06:23 by jochen