SimSET Utilities

Division of Nuclear Medicine

SimSET
Utilities

[News] [Installation guide] [User guide] [Programmers' info] [Resources] [Contacts]

We have developed a set of small utilities that can help in the analysis of data produced by SimSET. The page lists all of the utilities that we distribute together with a brief description.

Long time SimSET users will note that the list is much shorter than before: many of the utilities had not been updated or tested in years. We have lost confidence in them, particularly as we have not tested them on 64-bit systems. We have moved description of these utilities to the bottom of this page. If you have been using them, they are still in the software and should function as they have previously, but we offer no guarantee! If there are unsupported utilities that you find / have found very useful, let us know. We may then test them and add them to the supported list.

[addrandoms] [bin] [convert] [makeindexfile] [reversebytes] [timesort] [ttest]

addrandoms Adds random events to a time-sorted detector history file. Description and usage are given on the Randoms Simulation page.

bin
This program is the stand-alone binning module. It reads in a PHG history file and "bins" the photons up according to the parameters specified in the "bin params" file.

Usage: bin -X param_file

where param_file is the same parameters file given to the PHG when the simulation is done (see PHG page) and the flag -X is -p for PHG history files (photons have been tracked through the object only), -c is for collimator history files, and -d is for detector history files. Note that in order to have bin do anything you must specify a path name to the "bin_params_file" parameter (described in the binning page).

convert
This program is used to convert binary files from one format to another (eg, 8 byte double to 4 byte integer). It handles a wide variety of formats including ASCII. It will skip over a header or include it in the output file. Note that using ASCII as the input format, is only supported when the output is also ASCII. In this case, the conversion is assumed to be new-line to carriage return or vice-versa. The program simply checks each character for being either a new-line or a carriage return and swaps it to the other.

Usage:

convert -i in_form -o out_form [-s header_size -h -n num_per_line ] input_file output_file

-i: The format of the input data. in_form is a numerical code.

Supported types are listed below:

0: input is one byte character data, no convertion is defined
1: input is unsigned one byte character data, no convertion is defined
2: input is "short" this is defined by the system that created the data
3: input is unsigned short
4: input in "int" this is defined by the system that created the data
5: input is unigned int
6: input is "long" this is defined by the system that created the data
7: input is unsigned long this is defined by the system that created the data
8: input is "float" this is defined by the system that created the data
9: input is "double" this is defined by the system that created the data
10: input is one byte character data (same as 0)
11: input is unsigned one byte character data (same as 1)
12: input is two byte integer data
13: input is unsigned two byte integer data
14: input is four byte integer data
15: input is unsigned four byte integer data
16: input is ASCII text

-o: The format of the output data. out_form is a numerical code. This is the same as in_form except ASCII is a supported output type. Note that you may use the -n option with ASCII to specify how many numbers are printed per line. For example if you specify -3, a new-line will be inserted after every 3rd number is converted to ASCII. Supported types are listed below:

0-15: same as input
16: output is ASCII text

-s: The size of the file's header to be skipped. This portion of the file will not be converted.

-h: Copy the header. If this flag is included the header that is skipped due to the -s option is copied to the front of the converted file.

-n: The number of ASCII conversion per line of ASCII output. For example if you specify -3, a new-line will be inserted after every 3rd number is converted to ASCII.

input_file: The source file that will be converted.

output_file: The output file that will be created.

makeindexfile
This program is referred to as the "Object Editor" in the PHG manual. It creates index files for the activity and attenuation objects.

Usage: makeindexfile param_file

param_file: This is the same PHG parameter file that will be used for the simulation. Hence, it contains the definition of the object geometry and the path names to the index files.

phgbin (old name for bin - see above) Processes a PHG history file by reading in the data and sending it through the binning module.

reversebytes
This program does byte swapping for moving binary files from one system to the other where the binary byte ordering is different. It prompts for a header size which is skipped, and not stored in the resulting output.

Usage: reversebytes inputFile, outputFile, numBytes

inputFile is the source file, outputFile is the result file and numBytes is the size of the elements to be swapped.

All elements must be the same size. For instance a file might be all four byte integers, eight byte reals, etc. One byte data doesn't need to be swapped :).

timesort Sorts the decays in a history file by their time stamps. Description and usage are given on the Randoms Simulation page.

ttest
This program is for diagnostics. It performs a large sample t-test on two different simulations. You must bin up the counts, weights, and weights squared for both simulations. The program prompts for the names of all six of these files. It runs through the count images and finds all bins which contain 30 or more counts in both simulations. For these bins it performs a t-test using the weight and weight squared values. It will print out the resulting t-tests, and offers the option of binning them up. The result of this binning should be a gaussian. If you have a large number of valid bins it is not reasonable to look at all of the t-test results, so you can bin them up and compare the results with a gaussian.

Usage: ttest

Unsupported utilities

We will be testing combinebin with the intent of moving it back into the supported utilities before the next release. We are open to testing some of the other utilities if users express interest in them.

[attncorrect] [bcomp] [buildatt] [buildcoh] [calcattenuation] [collapse] [collapse3d] [combinebin] [combinehist] [convertheader] [correlate] [displayheader] [extract] [extractlines] [line3d] [migrate] [phgswap] [printheader] [reorder] [scale] [stripheader]

[top of page]

attncorrect	Applies a calculated attenuation map to simulated emission data to correct for attenuation effects.
bcomp	Performs a comparison of two binary files.
buildatt	This program creates the necessary "attenuation" tables for the PHG. It is not normally required that you run this program since the attenuation tables are in text format, and one is supplied with the PHG. However if you lose that file or want to modify the values created you can use this program. There are no arguments to this program. The output file is always named "phg.attenuation".
buildcoh	Takes a list of attenuation data tables, one for each material, and combines them into a master table.
calcattenuation	Calculates an attenuation image based on an attenuation index file for use in reconstructions.
collapse	Collapses two dimensional data into one, prompting the user to specify which dimension is to be collapsed.
collapse3d	Collapses three dimensional data into two, prompting the user to specify which dimension is to be collapsed.
combinebin	This program combines two or more "images" (or "histograms) created by the binning module into a single output file. This allows you to combine the results of multiple simulations. This program uses the information in the image header to scale the events appropriately. Usage: combinebin file1, file2, .... It is important to note that the result of the combining is stored in file1. Hence you must make a copy of file1 ahead of time to preserve. it. The program prompts you for the option to delete the remaining files automatically.
combinehist	This program concatenates two or more photon history files. The result is stored in the last argument, which is a file that will be created from scratch. The header from the first argument is used for the results with the appropriate fields updated. Usage: combinehist file1, file2, file3, ..., outputFile
convertheader	Converts headers on history or histogram files created with version of SimSET prior to 2.5 to the new 2.5 style header.
correlate	Performs an auto-correlation test on two histogram files.
displayheader	This program displays the data in the header of a history or bin file produced by the PHG (or the stand-alone modules). This is for old-style (pre-2.5) headers only (see printheader) Usage: displayheader file
extract	Separates a block of data from a file, storing it into a new file. The user specifies the starting byte and number of bytes to be extracted.
extractlines	Separates a user specified number of lines from a text file into a new file.
line3d	Extracts a "line" from 3D histogram data. The user specifies the (x,y) coordinate and the program extracts one value for each axial slice from that (x,y) bin.
migrate	This program simply converts end of line formats from UNIX (carriage return) to Macintosh (Line Feed) format. Usage: migrate -u \| -m [-i] file1 [file2, ...] -u Make all end of line markers UNIX format. -m Make all end of line markers Macintosh format. -i Perform migration "in-place". This means the file will be converted without being copied to a second file. Hence there are two modes to run the utility, when using "in-place" migration each file passed to the utility is converted. When not using "in-place" migration, the user must specify two file name arguments, the first is the source file and the second is the destination file. If the destination file exists it is deleted and recreated.
phgbin	Processes a PHG history file by reading in the data and sending it throughthe binning module.
phgswap	This program is like "reversebytes" except that it knows about the PHG header and will actually swap all of the fields in the header. The file being swapped must have been created with the same byte orientation as the machine it is being converted on (ie you must run phgswap before moving the file to a machine which has the opposite byte orientation). Usage: phgswap file1, file2, ... NOTE: the swapping is done in-place. Hence file1 will have its contents swapped and stored in file1. The program takes a variable number of input files to support batch processing.
printheader	This program displays the data in the header of a history or bin file produced by the PHG (or the stand-alone modules). This is for new-style (2.5) headers only (see displayheader) Usage: printheader file
reorder	Changes the order of 3D data, for instance if the data is [i, j, k] the user can specify to produce [j, k, i].
scale	Scales a histogram file.
stripheader	Removes a header from any file, the user specifies the header size.

Last revised by: Robert Harrison

Revision date: 19 September 2013

addrandoms	Adds random events to a time-sorted detector history file. Description and usage are given on the Randoms Simulation page.
bin	This program is the stand-alone binning module. It reads in a PHG history file and "bins" the photons up according to the parameters specified in the "bin params" file. Usage: bin -X param_file where param_file is the same parameters file given to the PHG when the simulation is done (see PHG page) and the flag -X is -p for PHG history files (photons have been tracked through the object only), -c is for collimator history files, and -d is for detector history files. Note that in order to have bin do anything you must specify a path name to the "bin_params_file" parameter (described in the binning page).
convert	This program is used to convert binary files from one format to another (eg, 8 byte double to 4 byte integer). It handles a wide variety of formats including ASCII. It will skip over a header or include it in the output file. Note that using ASCII as the input format, is only supported when the output is also ASCII. In this case, the conversion is assumed to be new-line to carriage return or vice-versa. The program simply checks each character for being either a new-line or a carriage return and swaps it to the other. Usage: convert -i in_form -o out_form [-s header_size -h -n num_per_line ] input_file output_file -i: The format of the input data. in_form is a numerical code. Supported types are listed below: 0: input is one byte character data, no convertion is defined 1: input is unsigned one byte character data, no convertion is defined 2: input is "short" this is defined by the system that created the data 3: input is unsigned short 4: input in "int" this is defined by the system that created the data 5: input is unigned int 6: input is "long" this is defined by the system that created the data 7: input is unsigned long this is defined by the system that created the data 8: input is "float" this is defined by the system that created the data 9: input is "double" this is defined by the system that created the data 10: input is one byte character data (same as 0) 11: input is unsigned one byte character data (same as 1) 12: input is two byte integer data 13: input is unsigned two byte integer data 14: input is four byte integer data 15: input is unsigned four byte integer data 16: input is ASCII text -o: The format of the output data. out_form is a numerical code. This is the same as in_form except ASCII is a supported output type. Note that you may use the -n option with ASCII to specify how many numbers are printed per line. For example if you specify -3, a new-line will be inserted after every 3rd number is converted to ASCII. Supported types are listed below: 0-15: same as input 16: output is ASCII text -s: The size of the file's header to be skipped. This portion of the file will not be converted. -h: Copy the header. If this flag is included the header that is skipped due to the -s option is copied to the front of the converted file. -n: The number of ASCII conversion per line of ASCII output. For example if you specify -3, a new-line will be inserted after every 3rd number is converted to ASCII. input_file: The source file that will be converted. output_file: The output file that will be created.
makeindexfile	This program is referred to as the "Object Editor" in the PHG manual. It creates index files for the activity and attenuation objects. Usage: makeindexfile param_file param_file: This is the same PHG parameter file that will be used for the simulation. Hence, it contains the definition of the object geometry and the path names to the index files.
phgbin	(old name for bin - see above) Processes a PHG history file by reading in the data and sending it through the binning module.
reversebytes	This program does byte swapping for moving binary files from one system to the other where the binary byte ordering is different. It prompts for a header size which is skipped, and not stored in the resulting output. Usage: reversebytes inputFile, outputFile, numBytes inputFile is the source file, outputFile is the result file and numBytes is the size of the elements to be swapped. All elements must be the same size. For instance a file might be all four byte integers, eight byte reals, etc. One byte data doesn't need to be swapped :).
timesort	Sorts the decays in a history file by their time stamps. Description and usage are given on the Randoms Simulation page.
ttest	This program is for diagnostics. It performs a large sample t-test on two different simulations. You must bin up the counts, weights, and weights squared for both simulations. The program prompts for the names of all six of these files. It runs through the count images and finds all bins which contain 30 or more counts in both simulations. For these bins it performs a t-test using the weight and weight squared values. It will print out the resulting t-tests, and offers the option of binning them up. The result of this binning should be a gaussian. If you have a large number of valid bins it is not reasonable to look at all of the t-test results, so you can bin them up and compare the results with a gaussian. Usage: ttest

Last revised by:	Robert Harrison
Revision date:	19 September 2013