To illustrate this, we will implement a basic group-based trajectory model (GBTM), also known as latent-class growth analysis. We make use of the implementation available in the lcmm package through the lcmm() function, which allows for a relatively concise illustration.
Extending the lcMethod class
Firstly, we create a new method class named lcMethodSimpleGBTM, which extends the lcMethod class.
setClass("lcMethodSimpleGBTM", contains = "lcMethod")
Note that a lcMethod class has a single slot call, which stores all the arguments to the method. The other relevant aspects of a lcMethod implementation are the prepareData() and fit() functions, which are called when passing a lcMethod object to the latrend() function or any other model estimation function.
lcMethodSimpleGBTM <- function(formula = Value ~ Time,
time = getOption("latrend.time"),
id = getOption("latrend.id"),
nClusters = 2,
nwg = FALSE) {
lcMethod.call("lcMethodSimpleGBTM", call = stackoverflow::match.call.defaults())
}
Next, we override the getName() and getShortName() functions in our method class to ensure that the model is easily distinguishable from other methods in the summary output. While we return a simple constant character sequence, the naming functions could be improved by generating a more detailed description of the model based on the arguments of the method object.
setMethod("getName",
signature("lcMethodSimpleGBTM"), function(object, ...) "simple group-based trajectory model")
setMethod("getShortName", signature("lcMethodSimpleGBTM"), function(object, ...) "sgbtm")
Implementing the prepareData() function enables the lcMethod to do data processing or transforming the data or other arguments in a structure which is suitable for the model fitting procedure. The prepare function takes a lcMethod, the data as a data.frame, and the verbosity level as inputs. The processing is passed onto the fit function by returning an environment with the relevant variables.
In this example, we need to ensure that the Id column is an integer.
setMethod("prepareData", signature("lcMethodSimpleGBTM"), function(method, data, verbose, ...) {
envir <- new.env()
envir$data <- as.data.frame(data)
envir$data[[method$id]] <- factor(data[[method$id]]) %>% as.integer()
return(envir)
})
The fit() function estimates the model and should return an object that extends the lcModel class. In our implementation, we call the lcmm() with the appropriate arguments, and we construct a lcModelSimpleGBTM instance. The class is defined in the subsection below. The envir argument contains the return value of the prepare() function, which would be NULL here.
setMethod("fit", signature("lcMethodSimpleGBTM"), function(method, data, envir, verbose, ...) {
args <- as.list(method, args = lcmm::lcmm)
args$data <- envir$data
args$fixed <- method$formula
if (method$nClusters > 1) {
args$mixture <- update(method$formula, NULL ~ .)
} else {
args$mixture <- NULL
}
args$subject <- method$id
args$ng <- method$nClusters
args$returndata <- TRUE
model <- do.call(lcmm::lcmm, args)
new("lcModelSimpleGBTM",
method = method,
data = data,
model = model,
clusterNames = LETTERS[seq_len(method$nClusters)])
})
Extending the lcModel class
We start off by defining the lcModelSimpleGBTM as an extension of the lcModel class. Extending the base class also enables the addition of new fields to the class, although there is no need for this in the present model.
setClass("lcModelSimpleGBTM", contains = "lcModel")
Our model inherits a couple of slots from the lcModel class, namely:
slotNames("lcModelSimpleGBTM")
#> [1] "model" "method" "call" "data"
#> [5] "id" "time" "response" "label"
#> [9] "ids" "clusterNames" "date" "estimationTime"
#> [13] "tag"
The "model" slot is free to be used to assign an arbitrary data structure that represents the internal model representation(s). In our implementation, this slot contains the lcmm model. The other slots are assigned in the constructor of the lcModel class, or by the latrend() estimation function. It is best practice to use the relevant getter functions for obtaining these values (via e.g., idVariable(), getLcMethod(), clusterNames()).
Typically, most effort of implementing the model interface goes to the predict() function. While implementing the function is optional, it is used for obtaining the fitted values, fitted trajectories, residuals, and cluster trajectories. Without this function, there is little functionality from a model except for the partitioning of the fitted trajectories.
The default fitted.lcModel() function returns the output from predict(model, newdata=NULL). As such, it is advisable to implement this special case. Here, we move the logic to the custom fitted.lcModelSimpleGBTM function, as defined below.
predict.lcModelSimpleGBTM <- function(object, newdata = NULL, what = "mu", ...) {
if(is.null(newdata)) {
predMat <- fitted(object, clusters = NULL)
} else {
predMat <- lcmm::predictY(object@model, newdata = newdata)$pred %>%
set_colnames(clusterNames(object))
}
transformPredict(pred = predMat, model = object, newdata = newdata)
}
The fitted() function should return the fitted values per trajectory per (requested) cluster. If not clusters are provided, the function is expected to return a matrix with the fitted values for each cluster. This logic is handled in the transformFitted() function, which is available in the package.
fitted.lcModelSimpleGBTM <- function(object, clusters = trajectoryAssignments(object)) {
predNames <- paste0("pred_m", 1:nClusters(object))
predMat <- as.matrix(object@model$pred[predNames])
colnames(predMat) <- clusterNames(object)
transformFitted(pred = predMat, model = object, clusters = clusters)
}
In order for the model implementation to return cluster assignments through the trajectoryAssignments() function, we need to implement the postprob() function to return the posterior probability matrix for the fitted data.
setMethod("postprob", signature("lcModelSimpleGBTM"), function(object) {
as.matrix(object@model$pprob)[, c(-1, -2), drop = FALSE]
})
Lastly, we override the converged() function to return the convergence code of the internal model.
setMethod("converged", signature("lcModelSimpleGBTM"), function(object, ...) {
object@model$conv
})
