TRiP98 Dose command

dose file / import()   list      calculate     field(*)    debug
            export()   delete    biological    window(*)
            read       display                 slice()
            write      inspect   nolateral     subdivide()
            prefix()             nofragments   events()
	                         norbe         clipctnum()
	                         nosvv         voi()
	                         rbe           datatype()
	                         svv
	                         dosemeanlet meanlet
	                         alpha beta
	                         specdose effdose
                                 algorithm(cl)
                                 bioalgorithm(cl)
                                 round

Purpose

Parameters

file

Specifies the stem of the file name (without extension) for input and output of dosecubes. Since dose cubes are data cubes they come as a binary <file>.DOS data file together with a text <file>.HED header file.

import()

Not yet implemented.

export(fmt)

Exports current dose cube(s) in some non-native format. At present only gd is foreseen, to be plotted with the gd program. Depending on window() or slice() data are exported as a single 1-dim file, a 2-dim file or a series of 2-dim files. File naming convention is
<file><xxxx>.gd
and
<file><xxxx>.um<yyyyyy>.gd
for 1D and 2D files, respectively, where <xxxx> is "phys", "bio", "rbe" or "svv". <yyyyyy> is the slice coordinate in micrometers.

read

Read dose cube specified by file. The target cube is specified by the biological, RBE or svv parameters, respectively. If omitted, the absorbed (physical) dose cube is assumed. Only a single dose cube can be read at a time.

write

Writes the current dose cube(s) as specified by file. Naming convention:

• <file> contains the extension .DOS or .dos:
  <file> for the physical dose. For the biological dose: <file><xxxx>.DOS and <file><xxxx>.HED, where <xxxx> is "bio", "rbe" and "svv".
• otherwise:
  <file><xxxx>.dos and <file><xxxx>.hed, where <xxxx> is "phys", "bio", "rbe" or "svv".

list

List current dose cube(s).

delete

Deletes the current dose cube(s) from memory (not from file).

display

Displays the current dose cube(s). Not yet implemented.

inspect

Show some internal info about the current dose cube(s).

calculate

Triggers dose calculation, by default the physical dose. If biological is specified, the biological dose as well as the RBE and survival cubes are computed. If a file parameter is additionally given, the dose cube(s) are created externally as if write was specified. Dimension and voxel size are cloned from the current CT cube

biological

Selects biological dose as well as the RBE and survival cubes.

norbe

nosvv

Do not compute or output cubes for RBE or survival distributions, respectively. These parameters are disk space savers.

specdose

Along with the biological dose calculate the absorbed dose obtained from sampling of particle spectra. Within sampling statistics it should coincide with the absorbed dose obtained from the depth dose distributions.

dosemeanlet

Calculates a dose-mean LET cube (keV/um).

meanlet

Calculates a mean LET cube (keV/um).

alpha

Calculates an alpha cube (1/Gy).

beta

Calculates a beta cube (1/Gy**2).

effdose

Calculates dose distribution created by the superposition of preirradiation and actual optimization.

nolateral

Do not consider lateral dose contributions from finite beam width or small angle scattering. This is for backward compatibility with the "old" TRiP versions.

rbe

svv

Select RBE or survival cubes as target for read operations.

algorithm(alg)

Selects algorithm for dose calculation. Same choices as for detector signal calculation:

• classic or cl (default)
• allpoints or ap
• multiplescatter or ms

bioalgorithm(alg)

Selects algorithm for biological effect calculation.

• classic or cl (default)
• lowdose or ld

round

Dose calculation is performed in double precision. When stored in external integer dose cubes, results are truncated by default. round specifies rounding to the nearest integer, thus improving the accuracy. Floating point cubes are not affected.

events(nevt)

Not yet implemented.

field(fieldlist)

Specifies a (comma-separated) list of partial fields which should contribute. "*" means all fields. This is the default.

window(xmin,xmax,ymin,ymax,zmin,zmax)

Specifies a window in CT coordinates (mm) for which the dose computation (and export) should be performed. This is useful to avoid lengthy calculations when only a small part of the cube is needed. Note that the data cube itself has always the full size.
You may use this parameter to distribute the dose calculation across many computers. Use the cubemerge command to collect the different slices into a single dose cube.
Note that with version 1310 and above the specified coordinates are treated slightly different than before. The voxel range considered is now determined by the voxels in which the respective coordinate limits are located. Before 1310, the coordinate limits had to enclose at least the numerical voxel centre in order for a voxel to be considered, which could lead to "empty" voxel ranges and thus to missing output.

slice(interval)

Consider only the specified interval of slice numbers for dose computation. <interval> might be

*
<slice-number>
<low-slice>,<high-slice>
*,<high-slice>
<low-slice>,*

where * stands for "all" or the lower/upper limit, respectively. Slicing is useful to avoid lengthy calculations when only a small part of the cube is needed. Note that the data cube itself has always the full size.
You may use this parameter to distribute the dose calculation across many computers. Use the cubemerge command to collect the different slices into a single dose cube.

clipctnum(lo,hi)

If given, specifies an interval of CT numbers for which dose voxels should be calculated.

voi()

Restricts dose calculation to voxels within the given VOI.

subdivide(ndx,ndy,ndz)

Specifies a finer granularity of voxel-based calculations. Each voxel is divided into ndx, ndy, ndz subvoxels to calculate partial doses which are subsequently averaged.
At present implemented for physical dose only.

prefix(prefix)

Not yet implemented.

datatype(dt)

Specifies datatype dt of output dose cube:

• short
• long
• float
• double

The default type is short.

debug

Debug switch. Lots of output!

Remarks

• Whereever possible, dose cubes are mapped to external files, rather than keeping them directly in computer memory. This is a big memory saver !
• Note that when file-mapped dose cubes are calculated they are created with their full size immediately. Thus the actual file size is no progress report !
• In LET related cubes the regions beyond the Bragg peak location might show higher values for mlet than for dosemlet due to the normalization to a low number of particles.
• With integer (short,long) dose cubes, results are normalized to 1000 and either truncated or rounded. In either case, this limits the achievable accuracy. If higher accuracy is needed, use floating point cubes.

Examples

1. 
   

   dose MyDose. / calculate 
   dose MyDose. / write
   

   First calculates the physical dose, where the auxiliary file MyDose.phys.dos is memory-mapped. Then make it available to the public by simply unmapping it.

2. dose xyz. / bio write field(1,3) voi(rand)
   

   Compute and output biological dose, RBE and survival on xyx.bio.dos, xyx.rbe.dos and xyx.svv.dos (and the corresponding HED files). Only fields 1 and 3 contribute.
   To save calculation time, only voxels within VOI rand are considered.

3.  dose z005. / window(*,*,*,*, 0, 10) calculate write
    dose z015. / window(*,*,*,*,10, 20) calculate write
    cubemerge merge.dos / infile(z0*.phys.dos)
   

   Calculate two slices of a dose cube separately and merge them into a single result dose cube.

4. dose phys.dos /read
   dose biol.dos /read bio
   dose export.  /export(gd) window(128,128,128,128,*,*) bio
   

   Read an absorbed and a biological dose cube and subsequently export a 1-dimensional cut along the z-Axis in gd format.