Changes 1.8

From VoxBoWiki

This page describes the major changes as of release 1.8. For more general information about this release, see the release notes.

Some of these changes are more user-relevant, and some are more admin-relevant. I'll try to put the user-relevant ones up top, but you should at least skim the entire list. A handful off odds and ends are listed at the bottom. The release also features numerous bug fixes and usability improvements.

Single-user mode

VoxBo can now be installed in single-user mode just by unpacking the distribution on your computer. Great for laptops at conferences, or for anyone who just wants to use VoxBo on a single machine and doesn't need all the cluster features. You can still do job scheduling and batch processing, and in fact most of what you already know about VoxBo is still good. But you get your own private queue that you can monitor and start and stop when you want using a new program called vbsingle (instead of voxq).

vbsingle can run complex jobtypes

vbsingle is the heart of single-user mode, but even in cluster mode it can be used to run VoxBo jobtypes without going to the trouble of setting up a script. For example, to run SPM2 realignment on a tes file, you can just do:

 vbsingle exec spm2_realign <dir> <ref> <infile> <outfile>

Permutation test with cluster size criterion

You can now use a cluster size criterion with a permutation test. That is, you can set a cluster size criterion, and identify a threshold at which the probability of observing clusters of that sizer or greater is controlled. If you have already run permutation tests and you still have the data around, you can do this without re-running the whole permutation. See the help for vbperminfo for more information.

New utility: vbdumpstats

vbdumpstats is a command-line utility to generate stat values for a voxel or region. It automates a previously painful process that could only be done in the voxel surfer.

Robust c-based regression code

Numerous changes to the regression code should make it all more robust, slightly faster, and completely IDL-independent. These changes also lay the groundwork for using your image data as an independent measure (as in lesion analysis).

New utility: vbinterpolate

vbinterpolate can be used to replace bad volumes in a 4D time series with interpolated volumes. It's still up to you to decide if/when to do it. It uses cubic spline interpolation (or optionally linear). The G matrix designer (glm and gdw) also supports specifying spikes, so it's never been easier to remove bad data from your model.

New utility: vbcmp

vbcmp will do pairwise comparisons between 3D or 4D volumes, and give you a report on whether or not they differ, and if so by how much. It is happy intermixing file formats and data types, it's just concerned with the numbers. It replaces cmp3d.

Linear detrend before GLM

Linear detrending is now an option in your GLM design (via glm or vbmakeglm). Like mean scaling, the detrending is done at the time of regression, your data files are not modified.

File format support

This release includes numerous improvements to file format support, including NIfTI support, slightly improved DICOM support, and the executables analyzeinfo and dicominfo for dumping header info from those two formats.

Generic file format conversion

vbconv is a new executable that converts between arbitrary file formats. It guesses the right format on the basis of extensions, so it's easier to use than vb2tes, vb2img, etc.

Improved vbmaskmunge

vbmaskmunge, the executable for thresholding, quantizing, and otherwise manipulating cubes, has more features. Some of these are useful for non-mask manipulation.

Much less IDL

IDL-dependence in VoxBo has been reduced to two components: the audit job in the GLM sequence, and the voxel surfer. The audit job is optional, we're hoping to have a much more functional and helpful audit job written in c soon. You can do some voxel surfing in vbview, and we will be releasing periodic updates to make it much more functional over the next few months. Don't be shy about requesting new vbview features, we will be pushing hard on it and releasing frequent updates.

Improved vbview

There's so much new in vbview, it will be easiest if you just run vbview and poke around. The time series surfing should be better, and generation of statistics from regions is now possible. F5-F9 can now be used to hide/show various panels. Copy/paste lets you copy/paste slices. The list goes on, and vbview is in heavy active development right now.

Contrast definitions

A GLM folder can now have a "contrasts" file — if the other files in the directory are called "myglm.xxx," the contrasts file can be called "myglm.contrasts", "myglm.contrast", "contrasts.txt," or "contrast.txt." You can list all your contrasts of interest here, give them simple names, and thereafter just use the names instead of ugly strings of numbers. The format is:

 <name> <scale> <type> <values...>

e.g.,

 my_t_contrast t vec 0 0 1 1 -1 -1 0 0

If the number of weights isn't the same as the number of covariates of interest, the contrast will be ignored silently.

Floating point conversion and removing bad values

Most of the file format converters, including vbconv, now take the -f option to convert to floating point (single-precision) and the -n option to remove NaNs and Infs (replace with 0's). Conversion to floating point may be useful to avoid quantization issues when the volumes are subsequently resliced (e.g., in motion correction or normalization). Removing NaNs may be useful because some software has difficulty dealing with non-finite values. Be careful when using -n on files where 0 is a legitimate and meaningful value.

glm/gds integration

gds is a script processing program for automating G-matrix creation. Now when you create a G matrix using glm or gdw, you automatically get (in addition to your G and preG files) a gds script that can be used to re-create your G matrix (perhaps with minor changes). NOTE: this feature is being held out of the initial release for further testing. But it works.

new utility: glminfo

glminfo is a command-line program that will print out some useful tidbits about a GLM directory, notably the contrasts and covariates. Give it the -i flag and it will just show the covariates of interest. You could do all this by inspecting files manually, but this is easier.

voxq and the scheduler

The new job scheduler is more robust and reduces delays when querying the queue. It's better at catching mid-stream errors in a job, and at catching license failures in MATLAB. Log files are now kept with the job files, and don't disappear until the entire sequence is finished or killed. The only downside is that if for whatever reason the scheduler is down, you can't examine the queue.

voxq has new functionality for examining the logs of just the bad jobs in a sequence.

Other new things

• vbprefs is a new executable that can be used to set your email address for VoxBo notifications, and will also display a little bit of your user configuration
• vbhdr will now replace {DATE} with the current date and {HOST} with the short version of the name of the host it's running on.
• the distribution includes updated scripts for including SPM2 jobs in preprocessing
• VoxBo now builds on OSX and under Cygwin
• fixes to analyze format to improve compatibility with other programs
• vbbatch will now accept the 'IND' tag to generate a unique numerical tag for each file
• glm scripts can now take the 'pieces' tag to set how many pieces your GLM is parallelized into
• FDR now works with F-tests
• vbpermmat generates perm matrices (it's mostly used internally)
• vbse can be used to do smoothness estimation manually
• vbvec2hdr will take a vector and place it in the header of an image file
• vbmaskcompare will compare two 3D mask files and compare them using the metrics described by Fiez et al.