Unified Equation Representation

library(Colossus)
library(data.table)

Prospective feature, presented for user suggestion

The default method to specify a survival model using a series of vectors can be overly complicated at times. I felt that it wasn’t straight-forward for typical R users, and made it too complicated to translate from a model to a script input. My plan is to add two functions: a conversion from a simple string expression of the model into the regression call, and a function to plot the hazard ratio or rate equation in LaTeX.

Equation Expression

The basic idea of the first 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 the functions runs without a baseline.

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()
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
#> Null data.table (0 rows and 0 cols)

Different model formulas and subterm types are being added as need. Please contact the developer if the methods you want to use are not yet 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.

Subterm Type	Equivalent Aliases
plin	“plin”, “plinear”, “product-linear”
lin	“lin”, “linear”
loglin	“loglin”, “loglinear”, “log-linear”
loglin_slope/loglin_top	“loglin-dose”, “loglinear-dose”, “log-linear-dose”
lin_slope/lin_top	“lin-dose”, “linear-dose”, “linear-piecewise”
quad_slope	“quadratic”, “quad”, “quad-dose”, “quadratic-dose”
step_slope/step_int	“step-dose”, “step-piecewise”
lin_quad_slope/lin_quad_int	“lin-quad-dose”, “linear-quadratic-dose”, “linear-quadratic-piecewise”
lin_exp_slope/lin_exp_int/lin_exp_exp_slope	“lin-exp-dose”, “linear-exponential-dose”, “linear-exponential-piecewise”

Term Type	Equivalent Aliases
M	“m”, “me”, “multiplicative”, “multiplicative-excess”
A	“a”, “additive”
PA	“pa”, “product-additive”
PAE	“pae”, “product-additive-excess”
GMIX	“gmix”,“geometric-mixture”
GMIX-R	“gmix-r”,“relative-geometric-mixture”
GMIX-E	“gmix-e”,“excess-geometric-mixture”

Model Visualization

The second function will be intended to display the equation. This function is currently being developed. Based on required packages the current formats being considered are: plain-text output, LaTeX code output, or directly plotting the equation in a graph display. This method is not currently implemented for use.