fMRI oriented scripts

Tip

For more information on script inputs, see Params/Instructions files.

cross_bold_pp_161012.csh

generic EPI (BOLD) pre-processing

Usage: cross_bold_pp_161012.csh <params file> [instructions_file]

Examples:

cross_bold_pp_161012.csh VB16168.params

Required parameters

Variable Values Description
patid <str> unique identifier for current subject/session
irun <str array> list of run folders
fstd <int array> list of scan numbers that map to run folders
mprs <int array> list of mprage scan numbers
inpath <str> starting directory (usually subject directory)
target <img> atlas to be used for alignment
go 0,1 if calls should be executed (if 0, statements will only be printed, not executed)
nx <int> number of voxels on the x-axis
ny <int> number of voxels on the y-axis
skip <int> number of pre-steady state frames
TR_vol <flt> time per frame (s)
TR_slc <flt> time per slice (s) (set to 0 to have it computed)
epidir 0,1 direction of EPI slices (0 = inferior to superior, 1 = superior to inferior)
economy <int> level of removal for intermediate files created during execution (see table below)
epi2atl 0,1,2 if EPI to atlas transform is required (0 = no transform, 1 = transform to 333 space, 2 = skip to resampling step)
FDthresh <flt> frame displacement thresholds
normode 0,1 if per-frame volume intensity should be modified
dwell <flt> EPI dwell time (echo spacing) (ms)
ped x,x-,y,y-,z,z- EPI phase encoding direction
rsam_cmnd <str> script to use for resampling (recommended: one_step_resample.csh)
Economy value Files to be removed
> 2 original bold run images
> 3 frame-aligned images (_faln)
> 4 cross-realigned avg images (_r3d_avg or xr3d_BC_avg if $BiasField) (only if $epi2atl == 0)

Field map correction parameters (required)

Variable Values Description
Option 1 (Measured field map - gradient echo)
gre <int array> gradient echo measured field map scan numbers (magnitude image should be first, followed by phase image)
delta <flt> difference between field map echo times (ms)
TE_vol <int> echo time (ms)
Option 2 (Measured field map - spin echo)
sefm <int array> spin echo measured field maps
TE_vol <int> echo time (ms)
Option 3 (Mean field map)
FMmean <img> mean field map image
Option 4 (basis_opt field map)
FMmean <img> mean field map image
FMBases <img> ??

Optional parameters

Tip

Although tse and pdt2 are optional, you should specify one or the other if you have them in order to get a better registration to atlas.

Variable Values Default Description
tse <int array>   list of tse scan numbers
pdt2 <int array>   list of proton-density weighted scan numbers
day1_patid <str>   patient directory for first session (if patid is not patient’s first session)
day1_path <str>   path to day1 atlas directory (required if day1_patid is set)
scrdir <str>   scratch directory to be
sorted 0,1 0 if dcm sort has already been run
MB 0,1 0 skip slice timing correction and debanding
sx <int> 1 unpacked x-dimension squeeze factor (unpack_4dfp)
sy <int> 1 unpacked y-dimension squeeze factor (unpack_4dfp)
E4dfp 0,1 0 if 4dfp files already exist (skips dcm_to_4dfp)
use_anat_ave 0,1 0 use _anat_ave epi image (default is _func_vols_ave)
min_frames <int> 240 minimum number of remaining frames after scrubbing for participant to be included
interleave -S   sequential slice acquisition (frame_align_4dfp)
seqstr <str>   specify [MB] slice sequence (counting from 1) as a comma-separated (no spaces) integer string (if non-standard interleaving)
MBfac <int> 1 multiband factor
lomotil 1-6   lowpass filter for specified motion parameter (mat2dat -l), used for filtered FD (set to 2 for y direction)
BiasField 0,1 0 perform bias field correction
FDtype 1,2 1 frame displacement calculation (1 = absolute value, 2 = squares)
anat_aveb <flt>   run_dvar_4dfp preblur in mm (for small voxels, set to 10mm)
anat_avet <flt> (compute) run_dvar_4dfp criterion (set excessively high to skip DVARS censoring)
cross_day_nostretch 0,1 0 disable stretch for cross-day transform
Gad 0,1 0 if gadolinium contrast was used

Additional optional parameters

Warning

Only specify the following variables if the action is desired. They will happen if you specify them at all (even if you set them to 0).

Variable Description
goto_UNWARP immediately go to unwarp step
epi_zflip flip z when unpacking (unpack_4dfp)
Siemens_interleave enables Siemens interleave order (frame_align_4dfp)
nounpack skips unpacking step

Processing steps

Step description Function Output
Convert bold run DICOM data to 4dfp format dcm_to_4dfp  
Convert mosaic format to volume (if not $nounpack) unpack_4dfp bold<irun>/
<patid>_b<irun>.4dfp.img
Correct slice timing and odd/even slice intensities (if not $MB) frame_align_4dfp, deband_4dfp bold<irun>/
<patid>_b<irun>_faln.4dfp.img
<patid>_b<irun>_faln_dbnd.4dfp.img
Motion correction via rigid body transform of each volume to reference frame cross_realign3d_4dfp bold<irun>/
<patid>_b<irun>[_faln_dbnd]_xr3d.4dfp.img
<patid>_b<irun>[_faln_dbnd]_r3d_avg.4dfp.img
<patid>_b<irun>[_faln_dbnd]_xr3d.mat
Bias field correction (if $BiasField) FSL bet, FSL fast, extend_fast_4dfp bold<irun>/
<patid>_b<irun>[_faln_dbnd]_xr3d_BC_avg.4dfp.img
atlas/
<patid>[_faln_dbnd]_xr3d_avg_brain.nii.gz
<patid>[_faln_dbnd]_xr3d_avg_brain_restore(.4dfp.img, .nii.gz)
Compute and apply within-run mode 1000 normalization normalize_4dfp, scale_4dfp bold<irun>/
<patid>_b<irun>[_faln_dbnd]_xr3d[_BC]_norm.4dfp.img
Extract/format movement data from cross-realign output mat2dat movement/
<patid>_b<irun>[_faln_dbnd]_xr3d(.dat, .ddat, .rdat)
Extract EPI first frame (anatomy) image and create functional volume conc file paste_4dfp, conc_4dfp atlas/
<patid>_anat_ave.4dfp.img
<patid>_func_vols.conc
Compute high movement frames using FD (if $FDthresh specified) and DVARS (stops here if $min_frames criteria not met) FD.awk (using .ddat movement file), run_dvar_4dfp movement/
<patid>[_faln_dbnd]_xr3d.FD
atlas/
<patid>[_faln_dbnd]_xr3d.FD.format (if $FDthresh)
<patid>_func_vols(.vals, .dat, .crit, .xmgr, .format)
Make func_vols_ave image with high movement frames removed actmapf_4dfp atlas/
<patid>_func_vols_ave.4dfp.img
Compute cross-session BOLD atlas transform if $day1_patid specified (then skips to applying EPI transform step) cross_day_imgreg_4dfp, t4_mul atlas/
<patid>_anat_ave_to_<target>_t4
(and other intermediate t4 files)
Convert MPRAGE DICOM data to 4dfp format (if not $E4dfp) dcm_to_4dfp atlas/
<patid>_mpr#.4dfp.img
Convert MPRAGE images to tranverse orientation (if not already) C2T_4dfp or S2T_4dfp atlas/
<patid>_mpr#T.4dfp.img
Compute MPRAGE average avgmpr_4dfp atlas/
<patid>_mpr_n#.4dfp.img
Create transverse t2w image (if $tse or $pdt) collate_slice_4dfp if $tse, extract_frame_4dfp (second frame) if $pdt, C2T_4dfp or S2T_4dfp atlas/
<patid>_t2w[T].4dfp.img
Compute EPI to atlas transform epi2mpr2atl2_4dfp if neither $tse nor $pdt, otherwise epi2t2w2mpr2atl2_4dfp atlas/
<patid>_anat_ave_to_<target>_t4
(and other intermediate t4 files)
Make atlas transformed EPI average image and t2w in 111, 222, and 333 atlas space t4img_4dfp atlas/
<patid>_(anat|func_vols)_ave_on_<target>_111.4dfp.img
<patid>_(anat|func_vols)_ave_on_<target>_222.4dfp.img
<patid>_(anat|func_vols)_ave_on_<target>_333.4dfp.img
Compute field mapping correction fmri_unwarp_170616.tcsh unwarp/
<patid>_(anat|func_vols)_ave_uwrp.4dfp.img
Compute and apply unwarped epi to atlas transform imgreg_4dfp, t4_mul, t4img_4dfp unwarp/
<patid>_(anat|func_vols)_ave_uwrp_on_<target>_111.4dfp.img
<patid>_(anat|func_vols)_ave_uwrp_on_<target>_222.4dfp.img
<patid>_(anat|func_vols)_ave_uwrp_on_<target>_333.4dfp.img
One-step resample unwarped images $rsam_cmnd bold<irun>/
<patid>_[_faln_dbnd]_xr3d_uwrp_atl.4dfp.img

fmri_unwarp_170616.tcsh

distortion correction wrapper script for fMRI preprocessing

Measured field map

Usage: fmri_unwarp_170616.tcsh -map <patid> <epi> <mag> <phase> <dwell> <te> <ped> <delta>

Variable Values Description
patid <str> unique identifier for current subject/session
epi <4dfp img> EPI anat image (_anat_ave or _func_vols_ave)
mag <nifti img> magnitude field map image
phase <nifti img> phase field map image
dwell <flt> EPI dwell time (echo spacing) (ms)
te <int> echo time (ms)
ped x,x-,y,y-,z,z- EPI phase encoding direction
delta <flt> difference between field map echo times (ms) (required only for gradient-echo field map)

Mean field map

Usage: fmri_unwarp_170616.tcsh -mean <epi> <FMmean> <epi_to_atl_t4> <dwell> <ped>

Variable Values Description
epi <4dfp img> EPI anat image (_anat_ave or _func_vols_ave)
FMmean <img> mean field map image
epi_to_atl_t4 <t4 file> EPI to atlas t4 file
dwell <flt> EPI dwell time (echo spacing) (ms)
ped x,x-,y,y-,z,z- EPI phase encoding direction

basis_opt field map

Usage: fmri_unwarp_170616.tcsh -basis <epi> <t2w> <FMmean> <FMbases> <epi_to_t2w_t4> <epi_to_atl_t4> <dwell> <ped> <nbasis> [t2w brain mask]

Variable Values Description
epi <4dfp img> EPI anat image (_anat_ave or _func_vols_ave)
t2w <4dfp img> structural 4dfp image (can be t2w or mpr)
FMmean <img> mean field map image
epi_to_t2w_t4 <t4 file> EPI to T2-weighted t4 file
epi_to_atl_t4 <t4 file> EPI to atlas t4 file
dwell <flt> EPI dwell time (echo spacing) (ms)
ped x,x-,y,y-,z,z- EPI phase encoding direction
nbasis <int> ??

N.B.: with option -basis, basis_opt optimizes the <dwell> value (aka, echo spacing) by default

sefm_pp_AZS.csh

merge AP/PA into one image and run topup to derive field map

Usage: sefm_pp_AZS.csh <params file> [instructions file]

Examples:

sefm_pp_AZS.csh PSQ0001_s1.params ../PSQ_study.params
Variable Values Description
patid <str> unique identifier for current subject/session
sefm <int array> spin echo measured field maps
sorted 1 if dcm sort has already been run (must be sorted)

one_step_resample.csh

one step resampling with support for bias field correction

Usage: one_step_resample.csh <parameters file> [instructions]

Examples:

one_step_resample.csh VB16168.params

Params variables

Variable Values Description
patid <str> unique identifier for current subject/session
day1_patid <str> patient directory for first session (if patid is not patient’s first session)
day1_path <str> path to day1 atlas directory (required if day1_patid is set)
irun <str array> list of run folders

Instructions variables

Variable Values Description
use_anat_ave 0,1 use _anat_ave epi image (default is _func_vols_ave)
outres 111,222,333 output resolution (default = 333)
target <img> atlas to be used for alignment
MB 0,1 skip slice timing correction and debanding
BiasField 0,1 perform bias field correction

epi2mpr2atlv_4dfp

EPI \(\rightarrow\) T1W \(\rightarrow\) atlas

Usage: epi2mpr2atlv_4dfp <epi_anat> <mpr_anat> [useold] [atlas target [711-2? OR -T<target including path>] [-S<atlas space>] [noinit]

Examples:

epi2mpr2atlv_4dfp stem9_anat_ave stem9_654-3 useold 711-2C
epi2mpr2atlv_4dfp stem9_anat_ave stem9_654-3 useold -T/data/cninds01/atlas/NP765 -S711-2B

Options

useold inhibits re-computation of all t4 files
noinit inhibits reinitialization of epi->mpr t4 files
-T<str> atlas target (specified string should include path) (default is 711-2B)
-S specifies the atlas space (requires -T) (currently only 711-2B is supported)

N.B.: Any image argument may include a path, e.g., /data/petmr1/data7/stem/96_06_14_stem9/stem9_654-3

N.B.: All named images must be in either ANALYZE or 4dfp format. ANALYZE will be converted to 4dfp

epi2t2w2mpr2atlv_4dfp

EPI \(\rightarrow\) T2W \(\rightarrow\) T1W \(\rightarrow\) atlas (8 parameter cross-modal; for “low” res fMRI)

Usage: epi2t2w2mpr2atlv_4dfp <epi_anat> <t2w_anat> <mpr_anat> [useold] [atlas_target]

Examples:

epi2t2w2mpr2atlv_4dfp stem9_anat_ave stem9_643-2 stem9_654-3 useold 711-2Y

N.B.: Any argument may include a path, e.g., /data/petmr1/data7/stem/96_06_14_stem9/stem9_654-3

N.B.: All named images must be in either ANALYZE or 4dfp format. ANALYZE will be converted to 4dfp

N.B.: ‘useold’ instructs epi2t2w2mpr2atlv_4dfp to use existing t4 files

N.B.: The default atlas_target is 711-2B

epi2t2w2mpr2atl1_4dfp

EPI \(\rightarrow\) T2W \(\rightarrow\) T1W \(\rightarrow\) atlas (9 parameter cross-modal; for “high” res fMRI)

Usage: epi2t2w2mpr2atl1_4dfp <epi_anat> <t2w_anat> <mpr_anat> [useold] [711-2? OR -T<Target including path>] [-S<atlas space>]

Examples:

epi2t2w2mpr2atl1_4dfp stem9_anat_ave stem9_643-2 stem9_654-3 711-2B
epi2t2w2mpr2atl1_4dfp stem9_anat_ave stem9_654-3 useold -T/data/cninds01/atlas/NP765 -S711-2B

N.B.: Any image argument may include a path, e.g., /data/petmr1/data7/stem/96_06_14_stem9/stem9_654-3

N.B.: All named images must be in 4dfp format

N.B.: -S specifies the atlas space. The only currently supported atlas space is 711-2B

epi2t2w2mpr2atl2_4dfp

EPI \(\rightarrow\) T2W \(\rightarrow\) T1W \(\rightarrow\) atlas (6 parameter cross-modal; best for distorted fMRI)

Usage: epi2t2w2mpr2atl2_4dfp <epi_anat> <t2w_anat> <mpr_anat> [useold] [711-2? OR -T<Target including path>] [-S<atlas space>]

Examples:

epi2t2w2mpr2atl2_4dfp stem9_anat_ave stem9_643-2 stem9_654-3 711-2B
epi2t2w2mpr2atl2_4dfp stem9_anat_ave stem9_654-3 useold -T/data/cninds01/atlas/NP765 -S711-2B

N.B.: Any image argument may include a path, e.g., /data/petmr1/data7/stem/96_06_14_stem9/stem9_654-3

N.B.: All named images must be in 4dfp format

N.B.: -S specifies the atlas space. The only currently supported atlas space is 711-2B

cross_day_imgreg_4dfp

link first session atlas transform to subsequent sessions via EPI “anat_ave”

Usage: cross_day_imgreg_4dfp <curr_patid> <day1_atlas_path> <day1_patid> <atlas_representative_target> [options]

Examples:

cross_day_imgreg_4dfp tpj0202 /data/petsun24/data1/tpj0201/atlas tpj0201 711-2Y
cross_day_imgreg_4dfp tpj0202 /data/petsun24/data1/tpj0201/atlas tpj0201 -T/data/cninds01/data2/ATLAS/ALLEGRA_Y_111

Options

-a<str> specify image filename trailer (default = “anat_ave”)
-nostretch disable stretch in transform
-setecho set echo
-S<str> specify atlas space (default=711-2B)

N.B.: cross_day_imgreg_4dfp must be run in the current atlas directory

N.B.: <atlas_representative_target> may be of form 711-2? OR -T/path/image

compute_run_sd1.csh

run var_4dfp -sn4 on all bold directories (*xr3d_norm and *xr3d_atl) and makes movies

Usage: compute_run_sd1.csh <patid>

Examples:

compute_run_sd1.csh VB15792

cross_day_imgreg_4dfp

compute cross-session BOLD atlas transform

Usage: cross_day_imgreg_4dfp <curr_patid> <day1_atlas_path> <day1_patid> <atlas_representative_target> [options]

Examples:

cross_day_imgreg_4dfp tpj0202 /data/petsun24/data1/tpj0201/atlas tpj0201 711-2Y
cross_day_imgreg_4dfp tpj0202 /data/petsun24/data1/tpj0201/atlas tpj0201 -T/data/cninds01/data2/ATLAS/ALLEGRA_Y_111

Options

-a<str> specify image filename trailer (default = “anat_ave”)
-nostretch disable stretch in transform
-setecho set echo
-S<str> specify atlas space (default=711-2B)

N.B.: cross_day_imgreg_4dfp must be run in the current atlas directory

N.B.: <atlas_representative_target> may be of form 711-2? OR -T/path/image

run_dvar_4dfp

compute format (identify frames with too much motion) (dvar_4dfp wrapper)

Usage: run_dvar_4dfp <(conc) concfile> [options]

Options

-d debug mode
-v verbose mode
-p<str> specify printer on which to plot generated .dat.ps file
-P<str> print previously generated results on specified printer (run on SunOS)
-x<flt> set frame rejection threshold (default = mode + 2.5*(left s.d.) over non-skipped frames)

N.B.: run_dvar_4dfp is a wrapper for dvar_4dfp

N.B.: options -b -m -n -t are passed to dvar_4dfp

N.B.: option -s is always passed to dvar_4dfp

conc_4dfp

create conc file

Usage: conc_4dfp <(conc) outroot> <(4dfp) 1> <(4dfp) 2> …

Examples:

conc_4dfp vb13157_faln_dbnd_xr3d_atl vb13157_b?_faln_dbnd_xr3d_atl.4dfp.img

Options

-w supress inclusion of current working directory in listed file path
-l<str> read input 4dfp list

N.B.: output conc file always has extension “conc”

N.B.: only files in or below the current working directory can be correctly addressed

conc_mv

update conc file 4dfp image pointers

Usage: conc_mv <conc file> <from> <to>

Examples:

conc_mv TC26851_rmsp_faln_dbnd_xr3d_atl.conc /data/nil-bluearc/raichle/gusnard/np751 auto_evolve/AVI_TEST

Options

-v verbose mode
-t practice mode (<conc file> not changed)

conc2format

compute conc-specific format using a fixed number of pre-steady state frames

Examples:

conc2format vb13157_faln_dbnd_xr3d_atl.conc 4

Options

-v verbose mode
-X label first frame of each run ‘X’

RFX2.csh

random effects analysis (1 or 2 groups)

Usage: RFX2.csh <list_group1> <Nimage_group1> [<list_group2> <Nimage_group2>]

Options

-d debug mode
-R suppress creation of large rec files (bootstrap mode)

N.B.: <list_group[12]> name 4dfp images on which to run the t-test

N.B.: <Nimage_group[12]> are 4dfp ‘n’ images (number of subjects for which each voxel is defined)

N.B.: If one group is entered a t-test will be run on this group against the null hypothesis of 0

N.B.: If two groups are entered a t-test will be run comparing the two groups and the computed statistic is Welch’s approximate t’ (Eqn. 8.11, p. 129 in Zar.)