softmean

• purpose
• usage
• examples
• comments
• error messages
• see also

Purpose:

This program will average together a series of files. Any zero valued voxels are treated as missing data and the output exclude zero input values when computing the output value. This is the recommended program for creating mean files to be used as inputs to automated registration since a non-zero value in any of the input files assures a non-zero value in the output. If you have no missing data in your field of view (i.e., all zeros truly represent a real world value of zero), you should use mean instead of this program. The program strictmean will give an output value of zero if any input at that voxel is zero and is the program of choice when any missing data is unacceptable (e.g., when creating masks for global normalization). These latter two programs are not included as part of the AIR 3.0 general release.

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)

type 'y' if you want to overwrite any preexisting file with the same name as output

scaling-suffix

the suffix of the files that store the scaling factors. Each input file should 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 (we use the real world value that corresponds to the maximum representable value in the input file).

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. Since no output file scaling file can be created (no suffix available), the scaling factor will be printed out on the screen.

input-file1

the name of the first input file

...input-fileN

the names of any additional input files

NOTE:

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). There is no harm in doing this except that it will take twice as long to get an answer.

Examples:

softmean pet_mean y .max pet1 pet2 pet3 pet4 pet5 pet6

• 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:

• This program provides quantitative averaging of nonzero values.
• If you want to add files instead of averaging them, all you need to do is multiply the output scaling factor by the number of input files
• Using the maximum possible value as the scaling factor rather than the number of real world units per single voxel unit allows 8 and 16 bit files to be mixed and interconverted without loss of quantitation.

Error messages: (alphabetical by case)

See also: Generic error messages

Coding error when calling meancalc(), weighted means should not use strictness of zero

• Consult with a C programmer. You shouldn't get such a message.

Values have been rescaled by a factor of ____

• This message is generated when "null" has been used as the scaling suffix. The message advises you that the output voxels have been multiplied by this value and therefore don't have the same units as your input voxels.

WARNING: File ____ rescaled during loading by multiplicative factor of ____

• Consult with your C programmer to determine whether the loading routine that you are using will create problems with this program. A bug in read_header2() identified on 7/20/95 can caused this warning to be generated erroneously.

WARNING: Files being averaged have different numbers of bits/pixel

• If you are using the convention of storing the maximum representable real world value in the scaling files, this shouldn't be a problem. If you are using scaling factors with per voxel unit values, the values will not be properly interconverted.

WARNING: Values as high as ____ were encountered but were set to ____

• This shouldn't happen unless there is a coding error (most likely the RESCALING option has been disabled).

file ____ is not compatible with file ____

• The file dimensions disagree. Use scanheader to verify the problem.

See also:

• strictmean
• mean