Unified Equation Representation • Colossus

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 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 developper if the methods you want to use are not yet added.

Model Visualization

The second function will be intended to display the equation. This function is currently being developped. 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.