## Note: This page was created with the CommandTemplate
##
## If you're modifying this page please take a look at the
## latest version of CommandTemplate to ensure that you're
## using the latest version of the CommandTemplate
##
## See HelpOnCommandTemplate for description of formatting
'''Index''' <<TableOfContents>>

= mri_fwhm =
mri_fwhm - Estimates the global Gaussian smoothness of a multi-frame, volume-based data size.

= Synopsis =
mri_fwhm --i inputvol --o outputvol [--flag arg]

= Arguments =
== Required Flagged Arguments ==
||--i inputvol ||input volume ||Input data. Format must be something readable by mri_convert (eg, mgh, mgz, img, nii, nii.gz). Alternately, one can synthesize white gaussian noise with --synth and --synth-frames in which case inputvol is used as a dimension template. ||
||--o outputvol ||save input after smoothing ||Save input after smoothing. See also --save-detended and --save-unmasked. ||




== Optional Flagged Arguments ==
||--smooth-only ||smooth and save, do not compute fwhm (--so) ||Does not attempt to compute FWHM. Smooths the input, saves to outputvol, and exists. Respects --save-unmasked, but not --save-detended. This allows for data sets with fewer than 10 frames to be smoothed. ||
||--save-detended ||save input after smoothing, masking, and detrending || ||
||--save-unmasked || ||Save input after smoothing and detrending, but do not mask while<<BR>>smoothing. Note that the output will be different even inside<<BR>>the mask because the smoother handles voxels on the boundary<<BR>>of the mask differently than those at the center. ||
||--mask maskvol ||binary mask ||Compute FWHM only over voxels in the given mask. Format can be anything accepted by mri_convert. If smoothing is to be done, it will only be done inside the mask. It is strongly recommended that a masked be used (see also --auto-mask and --save-unmasked). ||
||--mask-thresh absthresh ||threshold for mask (default is .5) ||Threshold mask at thresh. Default is 0.5 (ie, it expects a binary mask). ||
||--auto-mask rthresh ||compute mask ||Compute a mask based on a fraction (rthresh) of the global mean. If<<BR>>rthresh is 0.1, then all voxels in the mean image above 0.1*globalmean<<BR>>are in the mask. ||
||--nerode n ||erode mask n times prior to computer fwhm ||Erode mask n times (ie, make it smaller). Occurs after any mask inversion. ||
||--mask-inv ||invert mask ||Invert mask, ie, compute FWHM only over voxels outside the given mask. ||
||--out-mask outmask ||save final mask to outmask || ||
||--ar1 ar1path ||save apatial AR1 volume || ||
||--X x.mat ||matlab4 detrending matrix ||Detrend/residualize data with the matrix in x.mat. Ie,<<BR>>y = (I-inv(X'*X)*X')*y, where y is the input. x.mat must<<BR>>be a matlab4 matrix. Not with --detrend. ||
||--detrend order ||polynomial detrending (default 0) ||Detrend data with polynomial of given order. Not with --X. Note:<<BR>>if neither --X nor --detrend are specified, then detrending<<BR>>order of 0 is used (ie, the mean is removed). ||
||--sqr ||compute square of input before smooething || ||
||--fwhm fwhm ||smooth by fwhm before measuring ||Smooth BY fwhm mm before estimating the fwhm. This is mainly good for<<BR>>debuggging. But with --out can also be used to smooth data. ||
||--gstd gstd ||same as --fwhm but specified as the stddev || ||
||--to-fwhm tofwhm ||smooth to fwhm ||Smooth TO tofwhm mm. This is idea proposed by Lee Friedman<<BR>>( lfriedman10@comcast.net ) and fBIRN (www.birn.net) as a way to<<BR>>reduce variation across data sets, particularly when the data<<BR>>may have come from different scanners. The method implemented<<BR>>here uses an iterative approach in which the data are smoothed<<BR>>BY varying amounmts until the resulting fwhm is within a certain<<BR>>tolerance of tofwhm. By default, the tolerance is 0.5 mm, but<<BR>>can be changed with --to-fwhm-tol. It will iterate at most 20<<BR>>times (can be changed with --to-fwhm-nmax). An error will be<<BR>>returned if the tofwhm is less than the inherent fwhm or the max<<BR>>number of iterations is exceeded. The minimization is done with<<BR>>a Golden Section Search (see Numerical Recipes in C). ||
||--to-fwhm-tol tolerance ||smooth to fwhm +/- tol (default .5mm) ||Keep iterating the tofwhm search until the result is within tol<<BR>>of the desired fwhm (or until the maximum number of iterations<<BR>>is reached). ||
||--to-fwhm-nmax nitersmax ||maximum number of iterations (default 20) || ||
||--to-fwhm-file file ||save to-fwhm params in file ||Save some results of the tofwhm minimization to file. Good for<<BR>>debugging. Results also saved in summary file. ||
||--sum sumfile ||summary/log ||Prints summary to ascii sumfile. Send this file when requesting<<BR>>help or more information. ||
||--dat datfile ||only the final fwhm estimate || ||
||--synth || ||Synthesize input with white gaussian noise. Ten frames are used by default,<<BR>>but this can be changed with --synth-frames. Uses input volume as template.<<BR>>This functionality is useful for degugging. Eg, when using --synth and --fwhm,<<BR>>it should measure the resulting fwhm to be that passed by --fwhm. Can do<<BR>>the same with --to-fwhm. ||
||--synth-frames nframes ||default is 10 ||Synthesize input with white gaussian noise with the given number of frames.<<BR>>Implies --synth. ||
||--nframesmin n ||require at least this many frames || ||
||--ispm ||input is spm-analyze. Set --i to stem. || ||
||--in_nspmzeropad nz ||zero-padding for spm-analyze || ||
||--debug ||turn on debugging || ||
||--checkopts ||don't run anything, just check options and exit || ||
||--help ||print out information on how to use this program || ||
||--version ||print out version and exit || ||




= Description =
FreeSurfer program to estimate the global Gaussian smoothness of a multi-frame, volume-based data set. The smoothness is measured as the Full-Width-Half-Max (FWHM) in mm.  Gaussian stddev = fwhm/sqrt(log(256.0)). The voxels used in the fwhm estimation can be constrained to be inside of a mask. It is STRONGLY recommended that a masked be used. The mask can be specified explictly or computed automatically. By default, the time course will be detrended by removing the mean. Higher order polynomial detrending is possible. Alternatively, the user can specify a detrending matrix. The data can be smoothed BY a given fwhm or TO a given fwhm prior to estimating the fwhm.  The resulting data can then be saved (thus turning this program into a smoother). If smoothing is to be done, it will only be done inside the mask (except see --save-unmasked).

= Examples =
== Example 1 ==
mri_fwhm --i f.mgh --auto-mask .2 --sum f.fwhm.sum

mri_fwhm --i f.nii.gz --auto-mask .2 --sum f.fwhm.sum

 . Measure the fwhm of an input data set, compute mask automatically by thresholding input at 20% of global mean. The time series will be have its mean removed prior to computing the fwhm. Save result in a summary file (one example uses mgh format, the other gzipped NIFTI)

== Example 2 ==
 . mri_fwhm --i f.mgh --auto-mask .2 --sum f.fwhm5.sum --fwhm 5 --o fsm5.mgh --out-mask automask.nii

Same as above, but smooth input BY 5mm fwhm first. Save the smoothed output in fsm5.mgh. Save the mask to automask.nii. Note: mask is computed on unsmoothed data.

== Example 3 ==
 . mri_fwhm --i f.mgh --auto-mask .2 --sum f.fwhm5.sum --to-fwhm-tol .1 --to-fwhm 5 --o fto5.mgh

Same as above, but smooth input TO 5 +/- .1mm fwhm first. Save the smoothed output in fto5.mgh.

= Bugs =
None

= See Also =
= Links =
FreeSurfer, FsFast

= Methods Description =
{{{
}}}
= References =
[[References/Lastname#|References/Greve]]

= Reporting Bugs =
Report bugs to < analysis-bugs@nmr.mgh.harvard.edu >

= Author/s =
DougGreve