Equation Expression

The basic idea of this function is to take a string expression, similar to the model objects in the Survival package, which contains all of the information required in a more easily read format. This is intended to serve three functions: simplify the required input, make it easier to add multiple elements to each subterm, and make it easier to add factors.

Generally, a survival model is defined by using a Surv object, initialized with the interval and event columns, and a list of columns. Because Colossus can handle much more complicated models, the definition has to be more complicated. Instead of a Surv object, the model is specified with ‘cox’ or ‘poisson’. Based on the number of entries, the format of the time interval is assumed. The right side of the equation is listed similarly. Columns are added to subterm types (loglinear, linear, plinear). Each subterm has a list of columns and a term number. Finally, the method to combine terms is added as a separate item (multiplicative, additive). To prevent any issues with function definitions, the model equation is stored in a string.

$$\begin{aligned} \text{Surv(interval, event) ~ name + ... + factor(name)} \\ \text{'Survival(interval, event) ~ subterm(name, factor(name), term_number) + ... + term_model()'} \end{aligned}$$

The factor option can be used with or without a baseline specified. By default, no baseline is used. A baseline can be added by changing ‘factor(name)’ to ‘factor(name;baseline=level)’. If a valid baseline is used, the proper factor will not be included in the model expression or the final datatable returned. If an invalid baseline is used a warning is thrown and no baseline is used.

The following expressions are equivalent.

term_n <- c(0, 0, 1)
tform <- c("loglin", "loglin", "lin")
names <- c("dose0", "dose1", "dose2")
modelform <- "M"
tstart <- "t0"
tend <- "t1"
event <- "lung"

Model_Eq <- "cox(t0, t1, lung) ~ loglinear(dose0, dose1, 0) + linear(dose2, 1) + multiplicative()"
Model_Eq <- "cox(t0, t1, lung) ~ loglinear(dose0, dose1) + linear(dose2, 1)"

df <- data.table("dose0" = 1:4, "dose1" = 2:5, "dose2" = 3:6)
Convert_Model_Eq(Model_Eq, df)
#> $term_n
#> [1] 0 0 1
#> 
#> $tform
#> [1] "loglin" "loglin" "lin"   
#> 
#> $names
#> [1] "dose0" "dose1" "dose2"
#> 
#> $modelform
#> [1] "M"
#> 
#> $survival_model_type
#> [1] "cox"
#> 
#> $start_age
#> [1] "t0"
#> 
#> $end_age
#> [1] "t1"
#> 
#> $person_year
#> [1] "NONE"
#> 
#> $event
#> [1] "lung"
#> 
#> $strata
#> [1] "NONE"
#> 
#> $data
#>    dose0 dose1 dose2
#>    <int> <int> <int>
#> 1:     1     2     3
#> 2:     2     3     4
#> 3:     3     4     5
#> 4:     4     5     6

Different model formulas and subterm types are being added as needed. Please contact the developer if the methods you want to use have not yet been added. The following tables cover the subterms and term models that are currently implemented. Every option listed has multiple equivalent aliases that all refer to the same subterm or model formula.