softmean

• purpose
• usage
• examples
• comments
• error messages

Purpose:

This program will average together a series of files. For a given voxel location, only non-zero measurements are averaged. Consequently, any voxel that is non-zero for any subject will allow an estimate of the mean.

Usage:

softmean output overwrite?(y/n) scaling-suffix input-file1 [...input-fileN]

where the following definitions apply:

output

the name of the output file

overwrite?(y/n)

'y' grants permission to overwrite output

scaling-suffix

the suffix of files that store scaling factors. Each input file may have a scaling factor file associated with it. These files should contain a single ASCII number that represents a multiplicative factor for converting voxel values into real world values (i.e., its units should be real world units/voxel unit). All scaling files must have the same units.

An equivalent scaling file will be created for your output file and will have the same units as your input rescaling files.

If all of your input files are scaled identically, you can use "null" as the scaling suffix and a value of 1.0 will be automatically assigned to all input files. Note that the output may still be rescaled.

input-file1

the name of the first input file

...input-fileN

the names of any additional input files

Examples:

• the files mr1, mr2, mr3, mr4, mr5 and mr6 will be averaged to create mri_mean

• The files pet1.img, pet2.img, and pet3.img, etc. will be converted to real world values based on the values stored in pet1.max, pet2.max, and pet3.max, etc., respectively. These real world values will then be averaged and written out to pet_mean.img. A file pet_mean.max will store the values relating the output voxel values to real world values.

Comments:

• If you want to use a * wildcard on a UNIX based system to specify the input file names, you should include either the .img or the .hdr suffix (e.g., pet*.hdr) but not both. If you just end with the wildcard (e.g., pet*), each file will be loaded twice (once as .hdr and once as .img). The final answer will be the same, but it will take twice as long to get the answer.
• The output of this program is rescaled to optimize use of the dynamic range of voxel values. If you use scaling-suffix files, the output scaling suffix will give a quantitative measure of the rescaling applied.
• If you want to add files instead of averaging them, you need to multiply the output scaling factor by the number of input files

Error messages: (alphabetical by case)