Running Fabber¶
Specifying options¶
The simplest way to run Fabber is as a command line program. It uses the following syntax for options:
-–option
-–option=value
A simple example command line would be:
fabber --data=fmri_volume.nii.gz --mask=roi.nii.gz \
--model=poly --degree=2 \
--method=vb --noise=white \
--output=out --save-model-fit \
Common options¶
--output=OUTPUTDIR | |
Directory for output files (including logfile) | |
--method=METHOD | |
Use this inference method | |
--model=MODEL | Use this forward model |
--data=DATAFILE | |
Specify a single input data file | |
--mask=MASKFILE | |
Mask file. Inference will only be performed where mask value > 0 | |
--optfile | File containing additional options, one per line, in the same form as specified on the command line |
--overwrite | If set will overwrite existing output. If not set, new output directories will be created by appending ‘+’ to the directory name |
--suppdata | ‘Supplemental’ timeseries data, required for some models |
Selecting what data to output¶
--save-model-fit | |
Output the model prediction as a 4d volume | |
--save-residuals | |
Output the residuals (difference between the data and the model prediction) | |
--save-model-extras | |
Output any additional model-specific timeseries data | |
--save-mvn | Output the final MVN distributions. |
--save-mean | Output the parameter means. |
--save-std | Output the parameter standard deviations. |
--save-zstat | Output the parameter Zstats. |
--save-noise-mean | |
Output the noise means. The noise distribution inferred is the precision of a Gaussian noise source | |
--save-noise-std | |
Output the noise standard deviations. | |
--save-free-energy | |
Output the free energy, if calculated. |
Help and usage information¶
--help | Print this usage method. If given with –method or –model, display relevant method/model usage information |
--version | Print version identifier. If given with –model will print the model’s version identifier |
--listmethods | List all known inference methods |
--listmodels | List all known forward models |
--listparams | List model parameters (requires model configuration options to be given) |
--listoutputs | List additional model outputs (requires model configuration options to be given) |
Advanced options¶
--simple-output | |
Instead of usual standard output, simply output series of lines each giving progress as percentage | |
--data1=DATAFILE, --data2=DATAFILE | |
Specify multiple data files for n=1, 2, 3… | |
--data-order | If multiple data files are specified, how they will be handled: concatenate = one after the other, interleave = first record from each file, then second, etc. |
--mt1=INDEX, --mt2=INDEX | |
List of masked time points, indexed from 1. These will be ignored in the parameter updates | |
--debug | Output large amounts of debug information. ONLY USE WITH VERY SMALL NUMBERS OF VOXELS |
--link-to-latest | |
Try to create a link to the most recent output directory with the prefix _latest | |
--loadmodels | Load models dynamically from the specified filename, which should be a DLL/shared library |
Variational Bayes options (used when method=vb)¶
--noise=NOISE | Noise model to use (white or ar1) |
--convergence=CONVERGENCE | |
Name of method for detecting convergence - default maxits, other values are fchange, trialmode | |
--max-iterations=NITS | |
number of iterations of VB to use with the maxits convergence detector | |
--min-fchange=FCHANGE | |
When using the fchange convergence detector, the change in F to stop at | |
--max-trials=NTRIALS | |
When using the trial mode convergence detector, the maximum number of trials after an initial reduction in F | |
--print-free-energy | |
Output the free energy in the log file | |
--continue-from-mvn=MVNFILE | |
Continue previous run from output MVN files | |
--output-only | Skip model fitting, just output requested data based on supplied MVN. Can only be used with continue-from-mvn |
--noise-initial-prior=MVNFILE | |
MVN of initial noise prior | |
--noise-initial-posterior=MVNFILE | |
MVN of initial noise posterior | |
--noise-pattern=PATTERN | |
repeating pattern of noise variances for each point (e.g. 12 gives odd and even data points different variances) | |
--PSP_byname1=PARAMNAME, --PSP_byname2=PARAMNAME | |
Name of model parameter to use for prior specification 1, 2, 3… | |
--PSP_byname1_type=PRIORTYPE | |
Type of prior to use for parameter 1 - I=image prior | |
--PSP_byname1_image=FILENAME | |
File containing image for image prior for parameter 1 | |
--PSP_byname1_prec | |
Precision to apply to image prior for parameter 1 | |
--PSP_byname1_transform | |
Transform to apply to parameter 1 | |
--allow-bad-voxels | |
Continue if numerical error found in a voxel, rather than stopping | |
--ar1-cross-terms=TERMS | |
For AR1 noise, type of cross-linking (dual, same or none) | |
--spatial-dims=NDIMS | |
Number of spatial dimensions (1, 2 or 3). Default is 3. | |
--spatial-speed=SPEED | |
Restrict speed of spatial smoothing | |
--param-spatial-priors=PRIORSTR | |
Type of spatial priors for each parameter, as a sequence of characters. N=nonspatial, M=Markov random field, P=Penny, A=ARD | |
--locked-linear-from-mvn=MVNFILE | |
MVN file containing fixed centres for linearization |
Model-specific options¶
These are usually quite extensive and control the fine details of the model that is being implemented. For example the generic ASL model will need to be told the TIs/PLDs of the sequence, the number of repeats, the structure of the data, bolus duration and what components to include in the model (arterial as well as tissue, dispersion and exchange options, …).
The best way to look at model options is to use --help
, e.g.:
fabber_asl --help --model=aslrest