AT.SPC.tapply: AT.SPC.tapply

In libamtrack: Computational Routines for Proton and Ion Radiotherapy

Description

Similar to R's tapply this applies a function to cells defined by indices in a spc data object

Usage

AT.SPC.tapply( spc, INDEX, FUN, mixed.field.arguments = list(E.MeV.u =
 "E.mid.MeV.u", fluence.cm2 = "N.per.primary", particle.no = "particle.no"),
 additional.arguments = NULL, names.results = NULL)

Arguments

spc	spc data as returned by AT.SPC.read
INDEX	vector of column names in spc data that should be used as indices (indicating the cells).
FUN	Function to be applied - preferably this is a libamtrack function obeying the standard naming of mixed field variables number.of.field.components and material.no. Additional arguments to FUN can be passed using ...)
mixed.field.arguments	Named list containing the variables necessary to describe a mixed field (energy, fluence, particle type). The defaults are set to correspond to the column names used in AT.SPC.read. The user can change the list refering to other columns (of same length), e.g. when having multiplied the fluence per primary in the spc to get a realistic dose.
additional.arguments	Optional additional arguments to FUN. This should be a list with a three-entry vector for each argument. The first entry is the argument name, the second the value, the third indicated if it should be applied cell-wise (if TRUE). For example: the primitive R function to evaluate the mean energy per cell: mean(x): additional.arguments = list(c("x", "E.MeV.u", TRUE)) Or to pass the material.no (same for all cells): additional.arguments = list(c("material.no", "1", FALSE))
names.results	optional vector with names for the returned values of FUN

Value

A data frame with the following columns:

index.columns	Columns for indices given in INDEX to be looped over
results[]	Additional columns containing the returned values from FUN

Examples

## Not run: 
# Load required libraries
require(libamtrack)
require(lattice)
# Use example data set
file.name 	       <- system.file("extdata",
 "libamtrack.12C.H2O.active3.MeV27000.zip", package = "libamtrack")
endian                 <- c("big", "little")[2]
# Read in spc data, we use old style R reader, so endianess has to be given
spc                    <- AT.SPC.read ( file.name = file.name,
                                        endian    = endian,
                                        flavour   = "vanilla")$spc
# Translate particle numbers in particle names (looks better)
spc$particle.name      <- AT.particle.name.from.particle.no(particle.no =
 spc$particle.no)
spc$particle.name      <- factor(spc$particle.name)
										
# Compute and plot dose per primary with depth from spc data 
df1 <- AT.SPC.tapply( spc                   = spc, 
                      INDEX                 = "depth.g.cm2", 
                      FUN                   = AT.total.D.Gy, 
                      additional.arguments  = list( c("material.no", "1",
 FALSE),                   # Water
                                                   
 c("stopping.power.source.no", "0", FALSE)),     # PSTAR
                      names.results         = "D.Gy")
xyplot( D.Gy ~ depth.g.cm2,
        df1,
        type = "o",
		grid = TRUE,
        ylab = "dose per primary / Gy",
        xlab = "depth / (g/cm2)")
# Compute and plot dose (1 Gy entrance) with depth from spc data 
# To do so, first the fluence per primary has to be scaled and then

# AT.SPC.tapply has to be referred to the new non-standard column (default:
# fluence.cm2 = "N.per.primary")
fluence.factor  <- 1.0 / df1$D.Gy[1]                  
# factor between dose per primary (from above) and 2 Gy
spc$fluence.cm2 <- spc$N.per.primary * fluence.factor
df2 <- AT.SPC.tapply( spc                   = spc, 
  INDEX                 = "depth.g.cm2", 
  FUN                   = AT.total.D.Gy,
  mixed.field.arguments = list( fluence.cm2 = "fluence.cm2", 
                                E.MeV.u     = "E.mid.MeV.u", 
                                particle.no = "particle.no"),
  additional.arguments  = list( c("material.no", 
                                  "1", 
                                  FALSE), # Water
                                c("stopping.power.source.no",
                                  "0", FALSE)), # PSTAR
  names.results         = "D.Gy")
xyplot( D.Gy ~ depth.g.cm2,
        df2,
        type = "o",
	col  = "red",
        grid = TRUE,
	ylab = "dose / Gy",
        xlab = "depth / (g/cm2)")
			   
			   
# Compute and plot the dose with depth, but differentiate contribution
# from individual particle species
# Also: use nicer (human-readable) code for material
df3  <- AT.SPC.tapply( spc                  = spc, 
  INDEX                = c("depth.g.cm2", "particle.name"),  
  FUN                  = AT.total.D.Gy, 
  additional.arguments = list(c("material.no", 
                                "AT.material.no.from.material.name('Water,
 Liquid')", 
                                FALSE),
                              c("stopping.power.source.no", 
                                "0", 
                                FALSE)),
                       names.results        = "D.Gy")
xyplot( log10(D.Gy) ~ depth.g.cm2,
        df3,
        groups      = particle.name,
        type     	= 'o',
        grid        = TRUE,
        auto.key    = list(space = 'right'),
        ylab        = "log10( dose per primary / Gy )",
        xlab        = 'depth / (g/cm2)')

## End(Not run)

libamtrack documentation built on May 1, 2019, 6:47 p.m.