Package 'latrend'

Description

A framework for clustering longitudinal datasets in a standardized way. The package provides an interface to existing R packages for clustering longitudinal univariate trajectories, facilitating reproducible and transparent analyses. Additionally, standard tools are provided to support cluster analyses, including repeated estimation, model validation, and model assessment. The interface enables users to compare results between methods, and to implement and evaluate new methods with ease. The 'akmedoids' package is available from https://github.com/MAnalytics/akmedoids.

Features

• Unified cluster analysis, independent of the underlying algorithms used. Enabling users to compare the performance of various longitudinal cluster methods on the case study at hand.

• Supports many different methods for longitudinal clustering out of the box (see the list of supported packages below).

• The framework consists of extensible S4 methods based on an abstract model class, enabling rapid prototyping of new cluster methods or model specifications.

• Standard plotting tools for model evaluation across methods (e.g., trajectories, cluster trajectories, model fit, metrics)

• Support for many cluster metrics through the packages clusterCrit, mclustcomp, and igraph.

• The structured and unified analysis approach enables simulation studies for comparing methods.

• Standardized model validation for all methods through bootstrapping or k-fold cross-validation.

The supported types of longitudinal datasets are described here.

Getting started

The latrendData dataset is included with the package and is used in all examples. The plotTrajectories() function can be used to visualize any longitudinal dataset, given the id and time are specified.

data(latrendData)
head(latrendData)
options(latrend.id = "Id", latrend.time = "Time")
plotTrajectories(latrendData, response = "Y")

Discovering longitudinal clusters using the package involves the specification of the longitudinal cluster method that should be used.

kmlMethod <- lcMethodKML("Y", nClusters = 3)
kmlMethod

The specified method is then estimated on the data using the generic estimation procedure function latrend():

model <- latrend(kmlMethod, data = latrendData)

We can then investigate the fitted model using

summary(model)
plot(model)
metric(model, c("WMAE", "BIC"))
qqPlot(model)

Create derivative method specifications for 1 to 5 clusters using the lcMethods() function. A series of methods can be estimated using latrendBatch().

kmlMethods <- lcMethods(kmlMethod, nClusters = 1:5)
models <- latrendBatch(kmlMethods, data = latrendData)

Determine the number of clusters through one or more internal cluser metrics. This can be done visually using the plotMetric() function.

plotMetric(models, c("WMAE", "BIC"))

Vignettes

Further step-by-step instructions on how to use the package are described in the vignettes.

• See vignette("demo", package = "latrend") for an introduction to conducting a longitudinal cluster analysis on a example case study.

• See vignette("simulation", package = "latrend") for an example on conducting a simulation study.

• See vignette("validation", package = "latrend") for examples on applying internal cluster validation.

• See vignette("implement", package = "latrend") for examples on constructing your own cluster models.

Useful pages

Data requirements and datasets: latrend-data latrendData PAP.adh

High-level method recommendations and supported methods: latrend-approaches latrend-methods

Method specification: lcMethod lcMethods

Method estimation: latrend latrendRep latrendBatch latrendBoot latrendCV latrend-parallel Steps performed during estimation

Model functions: lcModel clusterTrajectories plotClusterTrajectories postprob trajectoryAssignments predictPostprob predictAssignments predict.lcModel predictForCluster fitted.lcModel fittedTrajectories

Author(s)

Maintainer: Niek Den Teuling [email protected] (ORCID)

Other contributors:

• Steffen Pauws [email protected] [contributor]

• Edwin van den Heuvel [email protected] [contributor]

• Koninklijke Philips N.V. [copyright holder]

See Also

Useful links:

• https://github.com/philips-software/latrend

• https://philips-software.github.io/latrend/

• Report bugs at https://github.com/philips-software/latrend/issues

Description

Retrieve and evaluate a lcMethod argument by name

Usage

## S4 method for signature 'lcMethod'
x$name

## S4 method for signature 'lcMethod'
x[[i, eval = TRUE, envir = NULL]]

Arguments

Value

The argument call or evaluation result.

See Also

Other lcMethod functions: as.data.frame.lcMethod(), as.data.frame.lcMethods(), as.lcMethods(), as.list.lcMethod(), evaluate.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Examples

method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time", nClusters = 3)
method$nClusters # 3
m = lcMethodLMKM(Y ~ Time, id = "Id", time = "Time", nClusters = 5)
m[["nClusters"]] # 5

k = 2
m = lcMethodLMKM(Y ~ Time, id = "Id", time = "Time", nClusters = k)
m[["nClusters", eval=FALSE]] # k

Description

Computes the average posterior probability of assignment (APPA) for each cluster.

Usage

APPA(object)

Arguments

Value

The APPA per cluster, as a ⁠numeric vector⁠ of length nClusters(object). Empty clusters will output NA.

References

Nagin DS (2005). Group-based modeling of development. Harvard University Press. ISBN 9780674041318, doi:10.4159/9780674041318.

Klijn SL, Weijenberg MP, Lemmens P, van den Brandt PA, Passos VL (2017). “Introducing the fit-criteria assessment plot - A visualisation tool to assist class enumeration in group-based trajectory modelling.” Statistical Methods in Medical Research, 26(5), 2424-2436.

van der Nest G, Lima Passos V, Candel MJ, van Breukelen GJ (2020). “An overview of mixture modelling for latent evolutions in longitudinal data: Modelling approaches, fit statistics and software.” Advances in Life Course Research, 43, 100323. ISSN 1040-2608, doi:10.1016/j.alcr.2019.100323.

See Also

confusionMatrix OCC

Description

Converts the arguments of a lcMethod to a named list of atomic types.

Usage

## S3 method for class 'lcMethod'
as.data.frame(x, ..., eval = TRUE, nullValue = NA, envir = NULL)

Arguments

Value

A single-row data.frame where each columns represents an argument call or evaluation.

See Also

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethods(), as.lcMethods(), as.list.lcMethod(), evaluate.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Description

Converts a list of lcMethod objects to a data.frame.

Usage

## S3 method for class 'lcMethods'
as.data.frame(x, ..., eval = TRUE, nullValue = NA, envir = parent.frame())

Arguments

Value

A data.frame with each row containing the argument values of a method object.

See Also

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethod(), as.lcMethods(), as.list.lcMethod(), evaluate.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Description

Generate a data.frame containing the argument values per method per row

Usage

## S3 method for class 'lcModels'
as.data.frame(x, ..., excludeShared = FALSE, eval = TRUE)

Arguments

Value

A data.frame.

Functionality

• Print an argument summary for each of the models.

• Convert to a data.frame of method arguments.

• Subset the list.

• Compute an internal metric or external metric.

• Obtain the best model according to minimizing or maximizing a metric.

• Obtain the summed estimation time.

• Plot a metric across a variable.

• Plot the cluster trajectories.

Description

Convert a list of lcMethod objects to a lcMethods list

Usage

as.lcMethods(x)

Arguments

Value

A lcMethods object.

See Also

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethod(), as.data.frame.lcMethods(), as.list.lcMethod(), evaluate.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Description

Convert a list of lcModels to a lcModels list

Usage

as.lcModels(x)

Arguments

Value

A lcModels object.

Functionality

• Print an argument summary for each of the models.

• Convert to a data.frame of method arguments.

• Subset the list.

• Compute an internal metric or external metric.

• Obtain the best model according to minimizing or maximizing a metric.

• Obtain the summed estimation time.

• Plot a metric across a variable.

• Plot the cluster trajectories.

See Also

lcModels

Other lcModels functions: lcModels, lcModels-class, max.lcModels(), min.lcModels(), plotMetric(), print.lcModels(), subset.lcModels()

Description

Extract the method arguments as a list

Usage

## S3 method for class 'lcMethod'
as.list(x, ..., args = names(x), eval = TRUE, expand = FALSE, envir = NULL)

Arguments

Value

A list with the argument calls or evaluated results depending on the value for eval.

See Also

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethod(), as.data.frame.lcMethods(), as.lcMethods(), evaluate.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
as.list(method)

as.list(method, args = c("id", "time"))

if (require("kml")) {
  method <- lcMethodKML("Y", id = "Id", time = "Time")
  as.list(method)

  # select arguments used by kml()
  as.list(method, args = kml::kml)

  # select arguments used by either kml() or parALGO()
  as.list(method, args = c(kml::kml, kml::parALGO))
}

Description

Get the cluster names

Usage

clusterNames(object, factor = FALSE)

Arguments

Value

A character of the cluster names.

See Also

Other lcModel functions: clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData)
clusterNames(model) # A, B

Description

Update the cluster names

Usage

clusterNames(object) <- value

Arguments

Value

The updated lcModel object.

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData, nClusters = 2)
clusterNames(model) <- c("Group 1", "Group 2")

Description

Obtain the proportional size per cluster, between 0 and 1.

Usage

clusterProportions(object, ...)

## S4 method for signature 'lcModel'
clusterProportions(object, ...)

Arguments

Value

A ⁠named numeric vector⁠ of length nClusters(object) with the proportional size of each cluster.

lcModel

By default, the cluster proportions are determined from the cluster-averaged posterior probabilities of the fitted data (as computed by the postprob() function).

Classes extending lcModel can override this method to return, for example, the exact estimated mixture proportions based on the model coefficients.

setMethod("clusterProportions", "lcModelExt", function(object, ...) {
  # return cluster proportion vector
})

See Also

nClusters clusterNames

clusterSizes postprob

Other lcModel functions: clusterNames(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData, nClusters = 2)
clusterProportions(model)

Description

Obtain the size of each cluster, where the size is determined by the number of assigned trajectories to each cluster.

Usage

clusterSizes(object, ...)

Arguments

Details

The cluster sizes are computed from the trajectory cluster membership as decided by the trajectoryAssignments() function.

Value

A named ⁠integer vector⁠ of length nClusters(object) with the number of assigned trajectories per cluster.

See Also

clusterProportions trajectoryAssignments

Other lcModel functions: clusterNames(), clusterProportions(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData, nClusters = 2)
clusterSizes(model)

Description

Extracts a data.frame of the cluster trajectories associated with the given object.

Usage

clusterTrajectories(object, ...)

## S4 method for signature 'lcModel'
clusterTrajectories(object, at = time(object), what = "mu", ...)

Arguments

Value

A data.frame of the estimated values at the specified times. The first column should be named "Cluster". The second column should be time, with the name matching the timeVariable(object). The third column should be the expected value of the observations, named after the responseVariable(object).

See Also

plotClusterTrajectories

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData)

clusterTrajectories(model)

clusterTrajectories(model, at = c(0, .5, 1))

Description

Extract the coefficients of the lcModel object, if defined. The returned set of coefficients depends on the underlying type of lcModel. The default implementation checks for the existence of a coef() function for the internal model as defined in the ⁠@model⁠ slot, returning the output if available.

Usage

## S3 method for class 'lcModel'
coef(object, ...)

Arguments

Value

A named ⁠numeric vector⁠ with all coefficients, or a matrix with each column containing the cluster-specific coefficients. If coef() is not defined for the given model, an empty ⁠numeric vector⁠ is returned.

Implementation

Classes extending lcModel can override this method to return model-specific coefficients.

coef.lcModelExt <- function(object, ...) {
  # return model coefficients
}

See Also

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData, nClusters = 2)
coef(model)

Description

Note: this function should not be called directly, as it is part of the lcMethod estimation procedure. For fitting an lcMethod object to a dataset, use the latrend() function or one of the other standard estimation functions.

The compose() function of the lcMethod object evaluates and finalizes the lcMethod arguments.

The default implementation returns an updated object with all arguments having been evaluated.

Usage

compose(method, envir, ...)

## S4 method for signature 'lcMethod'
compose(method, envir = NULL)

Arguments

Value

The evaluated and finalized lcMethod object.

Implementation

In general, there is no need to extend this method for a specific method, as all arguments are automatically evaluated by the ⁠compose,lcMethod⁠ method.

However, in case there is a need to extend processing or to prevent evaluation of specific arguments (e.g., for handling errors), the method can be overridden for the specific lcMethod subclass.

setMethod("compose", "lcMethodExample", function(method, envir = NULL) {
  newMethod <- callNextMethod()
  # further processing
  return(newMethod)
})

Estimation procedure

The steps for estimating a lcMethod object are defined and executed as follows:

1. compose(): Evaluate and finalize the method argument values.

2. validate(): Check the validity of the method argument values in relation to the dataset.

3. prepareData(): Process the training data for fitting.

4. preFit(): Prepare environment for estimation, independent of training data.

5. fit(): Estimate the specified method on the training data, outputting an object inheriting from lcModel.

6. postFit(): Post-process the outputted lcModel object.

The result of the fitting procedure is an lcModel object that inherits from the lcModel class.

See Also

evaluate.lcMethod

Description

Compute the posterior confusion matrix (PCM). The entry $(i,j)$ represents the probability (or number, in case of scale = TRUE) of a trajectory belonging to cluster $i$ is assigned to cluster $j$ under the specified trajectory cluster assignment strategy.

Usage

confusionMatrix(object, strategy = which.max, scale = TRUE, ...)

Arguments

Value

A K-by-K confusion matrix with K = nClusters(object).

See Also

postprob clusterProportions trajectoryAssignments APPA OCC

Examples

data(latrendData)

if (rlang::is_installed("lcmm")) {
  method <- lcMethodLcmmGMM(
    fixed = Y ~ Time,
    mixture = ~ Time,
    random = ~ 1,
    id = "Id",
    time = "Time"
  )
  model <- latrend(method, latrendData)
  confusionMatrix(model)
}

Description

Check whether the fitted object converged.

Usage

converged(object, ...)

## S4 method for signature 'lcModel'
converged(object, ...)

Arguments

Value

Either logical indicating convergence, or a numeric status code.

The default lcModel implementation returns NA.

Implementation

Classes extending lcModel can override this method to return a convergence status or code.

setMethod("converged", "lcModelExt", function(object, ...) {
  # return convergence code
})

See Also

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData, nClusters = 2)
converged(model)

Description

Create the test fold data for validation

Usage

createTestDataFold(data, trainData, id = getOption("latrend.id"))

Arguments

See Also

createTrainDataFolds

Other validation methods: createTestDataFolds(), createTrainDataFolds(), latrendBoot(), latrendCV(), lcModel-data-filters

Examples

data(latrendData)

if (require("caret")) {
  trainDataList <- createTrainDataFolds(latrendData, id = "Id", folds = 10)
  testData1 <- createTestDataFold(latrendData, trainDataList[[1]], id = "Id")
}

Description

Create all k test folds from the training data

Usage

createTestDataFolds(data, trainDataList, ...)

Arguments

See Also

Other validation methods: createTestDataFold(), createTrainDataFolds(), latrendBoot(), latrendCV(), lcModel-data-filters

Examples

data(latrendData)

if (require("caret")) {
  trainDataList <- createTrainDataFolds(latrendData, folds = 10, id = "Id")
  testDataList <- createTestDataFolds(latrendData, trainDataList)
}

Description

Create the training data for each of the k models in k-fold cross validation evaluation

Usage

createTrainDataFolds(
  data,
  folds = 10L,
  id = getOption("latrend.id"),
  seed = NULL
)

Arguments

Value

A list of data.frame of the folds training datasets.

See Also

Other validation methods: createTestDataFold(), createTestDataFolds(), latrendBoot(), latrendCV(), lcModel-data-filters

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")

if (require("caret")) {
  trainFolds <- createTrainDataFolds(latrendData, folds = 5, id = "Id", seed = 1)

  foldModels <- latrendBatch(method, data = trainFolds)
  testDataFolds <- createTestDataFolds(latrendData, trainFolds)
}

Description

Define an external metric for lcModels

Usage

defineExternalMetric(
  name,
  fun,
  warnIfExists = getOption("latrend.warnMetricOverride", TRUE)
)

Arguments

See Also

Other metric functions: defineInternalMetric(), externalMetric(), getExternalMetricDefinition(), getExternalMetricNames(), getInternalMetricDefinition(), getInternalMetricNames(), metric()

Description

Define an internal metric for lcModels

Usage

defineInternalMetric(
  name,
  fun,
  warnIfExists = getOption("latrend.warnMetricOverride", TRUE)
)

Arguments

See Also

Other metric functions: defineExternalMetric(), externalMetric(), getExternalMetricDefinition(), getExternalMetricNames(), getInternalMetricDefinition(), getInternalMetricNames(), metric()

Examples

defineInternalMetric("BIC", fun = BIC)

mae <- function(object) {
  mean(abs(residuals(object)))
}
defineInternalMetric("MAE", fun = mae)

Description

Get the deviance of the fitted lcModel object.

Usage

## S3 method for class 'lcModel'
deviance(object, ...)

Arguments

Details

The default implementation checks for the existence of the deviance() function for the internal model, and returns the output, if available.

Value

A numeric with the deviance value. If unavailable, NA is returned.

See Also

stats::deviance metric

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Description

Extract the residual degrees of freedom from a lcModel

Usage

## S3 method for class 'lcModel'
df.residual(object, ...)

Arguments

Value

A numeric with the residual degrees of freedom. If unavailable, NA is returned.

See Also

stats::df.residual nobs residuals

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Description

Get the elapsed time for estimating the given model.

For lcModel: Get the estimation time of the model, determined by the time taken for the associated fit() function to finish.

Usage

estimationTime(object, unit = "secs", ...)

## S4 method for signature 'lcModel'
estimationTime(object, unit = "secs", ...)

## S4 method for signature 'lcModels'
estimationTime(object, unit = "secs", ...)

## S4 method for signature 'list'
estimationTime(object, unit = "secs", ...)

Arguments

Value

A non-negative ⁠scalar numeric⁠ representing the estimation time in the specified unit..

See Also

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData)

estimationTime(model)
estimationTime(model, unit = 'mins')
estimationTime(model, unit = 'days')

Description

Substitutes the call arguments if they can be evaluated without error.

Usage

## S3 method for class 'lcMethod'
evaluate(
  object,
  classes = "ANY",
  try = TRUE,
  exclude = character(),
  envir = NULL,
  ...
)

Arguments

Value

A new lcMethod object with the substituted arguments.

See Also

compose

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethod(), as.data.frame.lcMethods(), as.lcMethods(), as.list.lcMethod(), formula.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Description

Compute one or more external metrics for two or more objects.

Note that there are many external metrics available, and there exists no external metric that works best in all scenarios. It is recommended to carefully consider which metric is most appropriate for your use case.

Many of the external metrics depend on implementations in other packages:

• clusterCrit (Desgraupes 2018)

• mclustcomp (You 2018)

• igraph (Csardi and Nepusz 2006)

• psych (Revelle 2019)

See mclustcomp::mclustcomp() for a grouped overview of similarity metrics.

Call getInternalMetricNames() to retrieve the names of the defined internal metrics. Call getExternalMetricNames() to retrieve the names of the defined internal metrics.

Usage

## S4 method for signature 'lcModel,lcModel'
externalMetric(
  object,
  object2,
  name = getOption("latrend.externalMetric"),
  ...
)

## S4 method for signature 'lcModels,missing'
externalMetric(object, object2, name = "adjustedRand")

## S4 method for signature 'lcModels,character'
externalMetric(object, object2 = "adjustedRand")

## S4 method for signature 'lcModels,lcModel'
externalMetric(object, object2, name, drop = TRUE)

## S4 method for signature 'list,lcModel'
externalMetric(object, object2, name, drop = TRUE)

Arguments

Value

For externalMetric(lcModel, lcModel): A numeric vector of the computed metrics.

For externalMetric(lcModels): A distance matrix of class dist representing the pairwise comparisons.

For externalMetric(lcModels, name): A distance matrix of class dist representing the pairwise comparisons.

For externalMetric(lcModels, lcModel): A named numeric vector or data.frame containing the computed model metrics.

For externalMetric(list, lcModel): A named numeric vector or data.frame containing the computed model metrics.

Supported external metrics

Implementation

See the documentation of the defineExternalMetric() function for details on how to define your own external metrics.

References

Cohen J (1960). “A Coefficient of Agreement for Nominal Scales.” Educational and Psychological Measurement, 20(1), 37-46.

Csardi G, Nepusz T (2006). “The igraph software package for complex network research.” InterJournal, Complex Systems, 1695. https://igraph.org.

Desgraupes B (2018). clusterCrit: Clustering Indices. R package version 1.2.8, https://CRAN.R-project.org/package=clusterCrit.

Hubert L, Arabie P (1985). “Comparing Partitions.” Journal of Classification, 2(1), 193–218. ISSN 1432-1343, doi:10.1007/BF01908075.

M K V, K K (2016). “A Survey on Similarity Measures in Text Mining.” Machine Learning and Applications: An International Journal, 3, 19-28. doi:10.5121/mlaij.2016.3103.

Revelle W (2019). psych: Procedures for Psychological, Psychometric, and Personality Research. Northwestern University, Evanston, Illinois. R package version 1.9.12, https://CRAN.R-project.org/package=psych.

You K (2018). mclustcomp: Measures for Comparing Clusters. R package version 0.3.1, https://CRAN.R-project.org/package=mclustcomp.

See Also

metric

Other metric functions: defineExternalMetric(), defineInternalMetric(), getExternalMetricDefinition(), getExternalMetricNames(), getInternalMetricDefinition(), getInternalMetricNames(), metric()

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model2 <- latrend(method, latrendData, nClusters = 2)
model3 <- latrend(method, latrendData, nClusters = 3)

if (require("mclustcomp")) {
  externalMetric(model2, model3, "adjustedRand")
}

Description

Note: this function should not be called directly, as it is part of the lcMethod estimation procedure. For fitting an lcMethod object to a dataset, use the latrend() function or one of the other standard estimation functions.

The fit() function of the lcMethod object estimates the model with the evaluated method specification, processed training data, and prepared environment.

Usage

fit(method, data, envir, verbose, ...)

## S4 method for signature 'lcMethod'
fit(method, data, envir, verbose)

Arguments

Value

The fitted object, inheriting from lcModel.

Implementation

This method should be implemented for all lcMethod subclasses.

setMethod("fit", "lcMethodExample", function(method, data, envir, verbose) {
  # estimate the model or cluster parameters
  coefs <- FIT_CODE

  # create the lcModel object
  new("lcModelExample",
    method = method,
    data = data,
    model = coefs,
    clusterNames = make.clusterNames(method$nClusters)
  )
})

Estimation procedure

The steps for estimating a lcMethod object are defined and executed as follows:

1. compose(): Evaluate and finalize the method argument values.

2. validate(): Check the validity of the method argument values in relation to the dataset.

3. prepareData(): Process the training data for fitting.

4. preFit(): Prepare environment for estimation, independent of training data.

5. fit(): Estimate the specified method on the training data, outputting an object inheriting from lcModel.

6. postFit(): Post-process the outputted lcModel object.

The result of the fitting procedure is an lcModel object that inherits from the lcModel class.

Description

Returns the cluster-specific fitted values for the given lcModel object. The default implementation calls predict() with newdata = NULL.

Usage

## S3 method for class 'lcModel'
fitted(object, ..., clusters = trajectoryAssignments(object))

Arguments

Value

A numeric vector of the fitted values for the respective class, or a matrix of fitted values for each cluster.

Implementation

Classes extending lcModel can override this method to adapt the computation of the predicted values for the training data. Note that the implementation of this function is only needed when predict() and predictForCluster() are not defined for the lcModel subclass.

fitted.lcModelExt <- function(object, ..., clusters = trajectoryAssignments(object)) {
  pred = predict(object, newdata = NULL)
  transformFitted(pred = pred, model = object, clusters = clusters)
}

The transformFitted() function takes care of transforming the prediction input to the right output format.

See Also

fittedTrajectories plotFittedTrajectories stats::fitted predict.lcModel trajectoryAssignments transformFitted

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData)
fitted(model)

Description

Extract the fitted trajectories

Usage

fittedTrajectories(object, ...)

## S4 method for signature 'lcModel'
fittedTrajectories(
  object,
  at = time(object),
  what = "mu",
  clusters = trajectoryAssignments(object),
  ...
)

Arguments

Details

The default lcModel implementation uses the output of fitted() of the respective model.

Value

A data.frame representing the fitted response per trajectory per moment in time for the respective cluster.

For lcModel: A data.frame with columns id, time, response, and "Cluster".

See Also

plotFittedTrajectories

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), getCall.lcModel(), getLcMethod(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
# Note: not a great example because the fitted trajectories
# are identical to the respective cluster trajectory
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, latrendData)
fittedTrajectories(model)

fittedTrajectories(model, at = time(model)[c(1, 2)])

Description

Extracts the associated formula for the given distributional parameter.

Usage

## S3 method for class 'lcMethod'
formula(x, what = "mu", envir = NULL, ...)

Arguments

Value

The formula for the given distributional parameter.

See Also

Other lcMethod functions: [[,lcMethod-method, as.data.frame.lcMethod(), as.data.frame.lcMethods(), as.lcMethods(), as.list.lcMethod(), evaluate.lcMethod(), lcMethod-class, names,lcMethod-method, update.lcMethod()

Examples

method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
formula(method) # Y ~ Time

Description

Get the formula associated with the fitted lcModel object. This is determined by the formula argument of the lcMethod specification that was used to fit the model.

Usage

## S3 method for class 'lcModel'
formula(x, what = "mu", ...)

Arguments

Value

Returns the associated formula, or response ~ 0 if not specified.

See Also

stats::formula

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, data = latrendData)
formula(model) # Y ~ Time

Description

Generate longitudinal test data

Usage

generateLongData(
  sizes = c(40, 60),
  fixed = Value ~ 1,
  cluster = ~1 + Time,
  random = ~1,
  id = getOption("latrend.id"),
  data = data.frame(Time = seq(0, 1, by = 0.1)),
  fixedCoefs = 0,
  clusterCoefs = cbind(c(-2, 1), c(2, -1)),
  randomScales = cbind(0.1, 0.1),
  rrandom = rnorm,
  noiseScales = c(0.1, 0.1),
  rnoise = rnorm,
  clusterNames = LETTERS[seq_along(sizes)],
  shuffle = FALSE,
  seed = NULL
)

Arguments

See Also

latrend-data

Examples

longdata <- generateLongData(
  sizes = c(40, 70), id = "Id",
  cluster = ~poly(Time, 2, raw = TRUE),
  clusterCoefs = cbind(c(1, 2, 5), c(-3, 4, .2))
)

if (require("ggplot2")) {
  plotTrajectories(longdata, response = "Value", id = "Id", time = "Time")
}

Description

Returns the default arguments associated with the respective lcMethod subclass. These arguments are automatically included into the lcMethod object during initialization.

Usage

getArgumentDefaults(object, ...)

## S4 method for signature 'lcMethod'
getArgumentDefaults(object)

Arguments

Value

A ⁠named list⁠ of argument values.

Implementation

Although implementing this method is optional, it prevents users from having to specify all arguments every time they want to create a method specification.

In this example, most of the default arguments are defined as arguments of the function lcMethodExample, which we can include in the list by calling formals. Copying the arguments from functions is especially useful when your method implementation is based on an existing function.

setMethod("getArgumentDefaults", "lcMethodExample", function(object) {
  list(
    formals(lcMethodExample),
    formals(funFEM::funFEM),
    extra = Value ~ 1,
    tol = 1e-4,
    callNextMethod()
  )
})

It is recommended to add callNextMethod() to the end of the list. This enables inheriting the default arguments from superclasses.

See Also

getArgumentExclusions

lcMethod

Other lcMethod implementations: getArgumentExclusions(), lcMethod-class, lcMethodAkmedoids, lcMethodCrimCV, lcMethodDtwclust, lcMethodFeature, lcMethodFunFEM, lcMethodFunction, lcMethodGCKM, lcMethodKML, lcMethodLMKM, lcMethodLcmmGBTM, lcMethodLcmmGMM, lcMethodMclustLLPA, lcMethodMixAK_GLMM, lcMethodMixtoolsGMM, lcMethodMixtoolsNPRM, lcMethodRandom, lcMethodStratify

Description

Returns the names of arguments that should be excluded during instantiation of the specification.

Usage

getArgumentExclusions(object, ...)

## S4 method for signature 'lcMethod'
getArgumentExclusions(object)

Arguments

Value

A ⁠character vector⁠ of argument names.

Implementation

This function only needs to be implemented if you want to avoid users from specifying redundant arguments or arguments that are set automatically or conditionally on other arguments.

setMethod("getArgumentExclusions", "lcMethodExample", function(object) {
  c(
    "doPlot",
    "verbose",
    callNextMethod()
  )
})

Adding `callNextMethod()` to the end of the return vector enables inheriting exclusions from superclasses.

See Also

getArgumentDefaults

lcMethod getArgumentExclusions

Other lcMethod implementations: getArgumentDefaults(), lcMethod-class, lcMethodAkmedoids, lcMethodCrimCV, lcMethodDtwclust, lcMethodFeature, lcMethodFunFEM, lcMethodFunction, lcMethodGCKM, lcMethodKML, lcMethodLMKM, lcMethodLcmmGBTM, lcMethodLcmmGMM, lcMethodMclustLLPA, lcMethodMixAK_GLMM, lcMethodMixtoolsGMM, lcMethodMixtoolsNPRM, lcMethodRandom, lcMethodStratify

Description

Get a citation object indicating how to cite the underlying R packages used for estimating or representing the given method or model.

Usage

getCitation(object, ...)

## S4 method for signature 'lcMethod'
getCitation(object, ...)

## S4 method for signature 'lcModel'
getCitation(object, ...)

Arguments

Value

A utils::citation object.

See Also

utils::citation

Description

Get the external metric definition

Usage

getExternalMetricDefinition(name)

Arguments

Value

The metric function, or NULL if not defined.

See Also

Other metric functions: defineExternalMetric(), defineInternalMetric(), externalMetric(), getExternalMetricNames(), getInternalMetricDefinition(), getInternalMetricNames(), metric()

Description

Get the names of the available external metrics

Usage

getExternalMetricNames()

See Also

Other metric functions: defineExternalMetric(), defineInternalMetric(), externalMetric(), getExternalMetricDefinition(), getInternalMetricDefinition(), getInternalMetricNames(), metric()

Description

Get the internal metric definition

Usage

getInternalMetricDefinition(name)

Arguments

Value

The metric function, or NULL if not defined.

See Also

Other metric functions: defineExternalMetric(), defineInternalMetric(), externalMetric(), getExternalMetricDefinition(), getExternalMetricNames(), getInternalMetricNames(), metric()

Description

Get the names of the available internal metrics

Usage

getInternalMetricNames()

See Also

Other metric functions: defineExternalMetric(), defineInternalMetric(), externalMetric(), getExternalMetricDefinition(), getExternalMetricNames(), getInternalMetricDefinition(), metric()

Description

Get the object label, if any.

Extracts the assigned label from the given lcMethod or lcModel object. By default, the label is determined from the "label" argument of the lcMethod object. The label of an lcModel object is set upon estimation by latrend() to the label of its associated lcMethod object.

Usage

getLabel(object, ...)

## S4 method for signature 'lcMethod'
getLabel(object, ...)

## S4 method for signature 'lcModel'
getLabel(object, ...)

Arguments

Value

A ⁠scalar character⁠. The empty string is returned if there is no label.

See Also

getName

getName getShortName

Examples

method <- lcMethodLMKM(Y ~ Time, time = "Time")
getLabel(method) # ""

getLabel(update(method, label = "v2")) # "v2"

Description

Get the lcMethod specification that was used for fitting the given object.

Usage

getLcMethod(object, ...)

## S4 method for signature 'lcModel'
getLcMethod(object)

Arguments

Value

An lcMethod object.

See Also

getCall.lcModel

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), ids(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

method <- lcMethodRandom("Y", id = "Id", time = "Time")
model <- latrend(method, latrendData)
getLcMethod(model)

Description

Get the name associated with the given object.

getShortName(): Extracts the short object name

Usage

getName(object, ...)

getShortName(object, ...)

## S4 method for signature 'lcMethod'
getName(object, ...)

## S4 method for signature 'NULL'
getName(object, ...)

## S4 method for signature 'lcMethod'
getShortName(object, ...)

## S4 method for signature 'NULL'
getShortName(object, ...)

## S4 method for signature 'lcModel'
getName(object)

## S4 method for signature 'lcModel'
getShortName(object)

Arguments

Details

For lcModel: The name is determined by its associated lcMethod name and label, unless specified otherwise.

Value

A nonempty string, as character.

Implementation

When implementing your own lcMethod subclass, override these methods to provide full and abbreviated names.

setMethod("getName", "lcMethodExample", function(object) "example name")

setMethod("getShortName", "lcMethodExample", function(object) "EX")

Similar methods can be implemented for your lcModel subclass, however in practice this is not needed as the names are determined by default from the lcMethod object that was used to fit the lcModel object.

See Also

getShortName getLabel

Examples

method <- lcMethodLMKM(Y ~ Time)
getName(method) # "lm-kmeans"
method <- lcMethodLMKM(Y ~ Time)
getShortName(method) # "LMKM"

Description

Get the trajectory ids on which the model was fitted

Usage

ids(object)

Arguments

Details

The order returned by ids(object) determines the id order for any output involving id-specific values, such as in trajectoryAssignments() or postprob().

Value

A ⁠character vector⁠ or ⁠integer vector⁠ of the identifier for every fitted trajectory.

See Also

Other lcModel functions: clusterNames(), clusterProportions(), clusterSizes(), clusterTrajectories(), coef.lcModel(), converged(), deviance.lcModel(), df.residual.lcModel(), estimationTime(), externalMetric(), fitted.lcModel(), fittedTrajectories(), getCall.lcModel(), getLcMethod(), lcModel-class, metric(), model.frame.lcModel(), nClusters(), nIds(), nobs.lcModel(), plot-lcModel-method, plotClusterTrajectories(), plotFittedTrajectories(), postprob(), predict.lcModel(), predictAssignments(), predictForCluster(), predictPostprob(), qqPlot(), residuals.lcModel(), sigma.lcModel(), strip(), time.lcModel(), trajectoryAssignments()

Examples

data(latrendData)
method <- lcMethodRandom("Y", id = "Id", time = "Time")
model <- latrend(method, latrendData)
ids(model) # 1, 2, ..., 200

Description

Extracts the trajectory identifier variable (i.e., column name) from the given object.

Usage

idVariable(object, ...)

## S4 method for signature 'lcMethod'
idVariable(object, ...)

## S4 method for signature 'lcModel'
idVariable(object)

## S4 method for signature 'ANY'
idVariable(object)

Arguments

Value

A nonempty string, as character.

See Also

Other variables: responseVariable(), timeVariable()

Examples

method <- lcMethodLMKM(Y ~ Time, id = "Traj")
idVariable(method) # "Traj"

method <- lcMethodRandom("Y", id = "Id", time = "Time")
model <- latrend(method, latrendData)
idVariable(model) # "Id"

Description

Initialization of lcMethod objects, converting arbitrary arguments to arguments as part of an lcMethod object.

Usage

## S4 method for signature 'lcMethod'
initialize(.Object, ...)

Arguments

Examples

new("lcMethodLMKM", formula = Y ~ Time, id = "Id", time = "Time")

Description

Virtual class for internal use. Do not use.

Usage

## S4 method for signature 'lcMetaMethod'
compose(method, envir = NULL)

## S4 method for signature 'lcMetaMethod'
getLcMethod(object, ...)

## S4 method for signature 'lcMetaMethod'
getName(object, ...)

## S4 method for signature 'lcMetaMethod'
getShortName(object, ...)

## S4 method for signature 'lcMetaMethod'
idVariable(object, ...)

## S4 method for signature 'lcMetaMethod'
preFit(method, data, envir, verbose)

## S4 method for signature 'lcMetaMethod'
prepareData(method, data, verbose)

## S4 method for signature 'lcMetaMethod'
fit(method, data, envir, verbose)

## S4 method for signature 'lcMetaMethod'
postFit(method, data, model, envir, verbose)

## S4 method for signature 'lcMetaMethod'
responseVariable(object, ...)

## S4 method for signature 'lcMetaMethod'
timeVariable(object, ...)

## S4 method for signature 'lcMetaMethod'
validate(method, data, envir = NULL, ...)

## S3 method for class 'lcMetaMethod'
update(object, ...)

## S4 method for signature 'lcFitConverged'
fit(method, data, envir, verbose)

## S4 method for signature 'lcFitConverged'
validate(method, data, envir = NULL, ...)

## S4 method for signature 'lcFitRep'
fit(method, data, envir, verbose)

## S4 method for signature 'lcFitRep'
validate(method, data, envir = NULL, ...)

Arguments

Description

An overview of the latrend package and its capabilities can be found here.

The latrend() function fits a specified longitudinal cluster method to the given data comprising the trajectories.

This function runs all steps of the standardized method estimation procedure, as implemented by the given lcMethod object. The result of this procedure is the estimated lcModel.

Usage

latrend(
  method,
  data,
  ...,
  envir = NULL,
  verbose = getOption("latrend.verbose")
)

Arguments

Details

If a seed value is specified in the lcMethod object or arguments to latrend, this seed is set using set.seed prior to the preFit step.

Value

A lcModel object representing the fitted solution.

See Also

Other longitudinal cluster fit functions: latrendBatch(), latrendBoot(), latrendCV(), latrendRep()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, data = latrendData)

model <- latrend("lcMethodLMKM", formula = Y ~ Time, id = "Id", time = "Time", data = latrendData)

model <- latrend(method, data = latrendData, nClusters = 3, seed = 1)

Description

This page provides high-level guidelines on which methods are applicable to your dataset. Note that this is intended as a quick-start.

Recommended overview and comparison papers:

• (Den Teuling et al. 2021): A tutorial and overview on methods for longitudinal clustering.

• Den Teuling et al. (2021) compared KmL, MixTVEM, GBTM, GMM, and GCKM.

• Twisk and Hoekstra (2012) compared KmL, GCKM, LLCA, GBTM and GMM.

• Verboon and Pat-El (2022) compared the kml, traj and lcmm packages in R.

• Martin and von Oertzen (2015) compared KmL, LCA, and GMM.

Approaches

Disclaimer: The table below has been adapted from a pre-print of (Den Teuling et al. 2021).

It is strongly encouraged to evaluate and compare several candidate methods in order to identify the most suitable method.

References

Den Teuling N, Pauws S, Heuvel Evd (2021). “Clustering of longitudinal data: A tutorial on a variety of approaches.” doi:10.48550/ARXIV.2111.05469, https://arxiv.org/abs/2111.05469.

Den Teuling NGP, Pauws SC, van den Heuvel ER (2021). “A comparison of methods for clustering longitudinal data with slowly changing trends.” Communications in Statistics - Simulation and Computation. doi:10.1080/03610918.2020.1861464.

Martin DP, von Oertzen T (2015). “Growth mixture models outperform simpler clustering algorithms when detecting longitudinal heterogeneity, even with small sample sizes.” Struct. Equ. Model., 22(2), 264–275. ISSN 1070-5511, doi:10.1080/10705511.2014.936340.

Twisk J, Hoekstra T (2012). “Classifying developmental trajectories over time should be done with great caution: A comparison between methods.” Journal of Clinical Epidemiology, 65(10), 1078–1087. ISSN 0895-4356, doi:10.1016/j.jclinepi.2012.04.010.

Verboon P, Pat-El R (2022). “Clustering Longitudinal Data Using R: A Monte Carlo Study.” Methodology, 18(2), 144-163. doi:10.5964/meth.7143.

See Also

latrend-methods latrend-estimation latrend-metrics

Description

The latrend estimation functions expect univariate longitudinal data that can be represented in a data.frame with one row per trajectory observation:

• Trajectory identifier: numeric, character, or factor

• Observation time: numeric

• Observation value: numeric

In principle, any type of longitudinal data structure is supported, given that it can be transformed to the required data.frame format using the generic trajectories function. Support can be added by implementing the trajectories function for the respective signature. This means that users can implement their own data adapters as needed.

Included longitudinal datasets

The following datasets are included with the package:

• latrendData

• PAP.adh

• PAP.adh1y

Description

This page presents an overview of the different functions that are available for estimating one or more longitudinal cluster methods. All functions are prefixed by "latrend".

latrend estimation functions

• latrend(): estimate a method on a longitudinal dataset, returning the resulting model.

• latrendBatch(): estimate multiple methods on multiple longitudinal datasets, returning a list of models.

• latrendRep(): repeatedly estimate a method on a longitudinal dataset, returning a list of models.

• latrendBoot(): repeatedly estimate a method on bootstrapped longitudinal dataset, returning a list of models.

• latrendCV(): repeatedly estimate a method using cross-validation on a longitudinal dataset, returning a list of models.

Parallel estimation

The functions involving repeated estimation support parallel computation. See here.

See Also

latrend-package lcMethod-estimation

Description

Generics used by latrend for different classes

Description

This page provides an overview of the currently supported methods for longitudinal clustering. For general recommendations on which method to apply to your dataset, see here.

Supported methods

In addition, the functionality of any method can be extended via meta methods. This is used for extending the estimation procedure of a method, such as repeated fitting and selecting the best result, or fitting until convergence.

It is strongly encouraged to evaluate and compare several candidate methods in order to identify the most suitable method.

References

Adepeju M, Langton S, Bannister J (2020). akmedoids: Anchored Kmedoids for Longitudinal Data Clustering. R package version 0.1.5, https://CRAN.R-project.org/package=akmedoids.

Benaglia T, Chauveau D, Hunter DR, Young D (2009). “mixtools: An R Package for Analyzing Finite Mixture Models.” Journal of Statistical Software, 32(6), 1–29. doi:10.18637/jss.v032.i06.

Bouveyron C (2015). funFEM: Clustering in the Discriminative Functional Subspace. R package version 1.1, https://CRAN.R-project.org/package=funFEM.

Genolini C, Alacoque X, Sentenac M, Arnaud C (2015). “kml and kml3d: R Packages to Cluster Longitudinal Data.” Journal of Statistical Software, 65(4), 1–34. doi:10.18637/jss.v065.i04.

Grün B, Leisch F (2008). “FlexMix Version 2: Finite Mixtures with Concomitant Variables and Varying and Constant Parameters.” Journal of Statistical Software, 28(4), 1–35. doi:10.18637/jss.v028.i04.

Nielsen JD (2018). crimCV: Group-Based Modelling of Longitudinal Data. R package version 0.9.6, https://CRAN.R-project.org/package=crimCV.

Proust-Lima C, Philipps V, Liquet B (2017). “Estimation of Extended Mixed Models Using Latent Classes and Latent Processes: The R Package lcmm.” Journal of Statistical Software, 78(2), 1–56. doi:10.18637/jss.v078.i02.

Sardá-Espinosa A (2019). “Time-Series Clustering in R Using the dtwclust Package.” The R Journal. doi:10.32614/RJ-2019-023.

Scrucca L, Fop M, Murphy TB, Raftery AE (2016). “mclust 5: clustering, classification and density estimation using Gaussian finite mixture models.” The R Journal, 8(1), 205–233.

See Also

latrend-approaches latrend-estimation latrend-metrics

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
model <- latrend(method, data = latrendData)

Description

The package supports a variety of metrics that help to evaluate and compare estimated models.

• Internal metrics: metrics that assess the adequacy of the model with respect to the data.

• External metrics: metrics that compare two models.

Users can implement new metrics through defineInternalMetric() and defineExternalMetric(). Custom-defined metrics are accessible using the same by-name mechanism as the other metrics.

Supported internal metrics

Supported external metrics

See Also

metric externalMetric

Description

The model estimation functions support parallel computation through the use of the foreach mechanism. In order to make use of parallel execution, a parallel back-end must be registered.

Windows

On Windows, the parallel-package can be used to define parallel socket workers.

nCores <- parallel::detectCores(logical = FALSE)
cl <- parallel::makeCluster(nCores)

Then, register the cluster as the parallel back-end using the doParallel package:

doParallel::registerDoParallel(cl)

If you defined your own lcMethod or lcModel extension classes, make sure to load them on the workers as well. This can be done, for example, using:

parallel::clusterEvalQ(cl,
  expr = setClass('lcMethodMyImpl', contains = "lcMethod"))

Unix

On Unix systems, it is easier to setup parallelization as the R process is forked. In this example we use the doMC package:

nCores <- parallel::detectCores(logical = FALSE)
doMC::registerDoMC(nCores)

See Also

latrendRep, latrendBatch, latrendBoot, latrendCV

Examples

data(latrendData)

# parallel latrendRep()
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
models <- latrendRep(method, data = latrendData, .rep = 5, parallel = TRUE)

# parallel latrendBatch()
methods <- lcMethods(method, nClusters = 1:3)
models <- latrendBatch(methods, data = latrendData, parallel = TRUE)

Description

Fit a list of longitudinal cluster methods on one or more datasets.

Usage

latrendBatch(
  methods,
  data,
  cartesian = TRUE,
  seed = NULL,
  parallel = FALSE,
  errorHandling = "stop",
  envir = NULL,
  verbose = getOption("latrend.verbose")
)

Arguments

Details

Methods and datasets are evaluated and validated prior to any fitting. This ensures that the batch estimation fails as early as possible in case of errors.

Value

A lcModels object. In case of a model fit error under errorHandling = pass, a list is returned.

See Also

lcMethods

Other longitudinal cluster fit functions: latrend(), latrendBoot(), latrendCV(), latrendRep()

Examples

data(latrendData)
refMethod <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
methods <- lcMethods(refMethod, nClusters = 1:2)
models <- latrendBatch(methods, data = latrendData)

# different dataset per method
models <- latrendBatch(
   methods,
   data = .(
     subset(latrendData, Time > .5),
     subset(latrendData, Time < .5)
   )
)

Description

Performs bootstrapping, generating samples from the given data at the id level, fitting a lcModel to each sample.

Usage

latrendBoot(
  method,
  data,
  samples = 50,
  seed = NULL,
  parallel = FALSE,
  errorHandling = "stop",
  envir = NULL,
  verbose = getOption("latrend.verbose")
)

Arguments

Value

A lcModels object of length samples.

See Also

Other longitudinal cluster fit functions: latrend(), latrendBatch(), latrendCV(), latrendRep()

Other validation methods: createTestDataFold(), createTestDataFolds(), createTrainDataFolds(), latrendCV(), lcModel-data-filters

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
bootModels <- latrendBoot(method, latrendData, samples = 10)

bootMAE <- metric(bootModels, name = "MAE")
mean(bootMAE)
sd(bootMAE)

Description

Apply k-fold cross validation for internal cluster validation. Creates k random subsets ("folds") from the data, estimating a model for each of the k-1 combined folds.

Usage

latrendCV(
  method,
  data,
  folds = 10,
  seed = NULL,
  parallel = FALSE,
  errorHandling = "stop",
  envir = NULL,
  verbose = getOption("latrend.verbose")
)

Arguments

Value

A lcModels object of containing the folds training models.

See Also

Other longitudinal cluster fit functions: latrend(), latrendBatch(), latrendBoot(), latrendRep()

Other validation methods: createTestDataFold(), createTestDataFolds(), createTrainDataFolds(), latrendBoot(), lcModel-data-filters

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")

if (require("caret")) {
  model <- latrendCV(method, latrendData, folds = 5, seed = 1)

  model <- latrendCV(method, subset(latrendData, Time < .5), folds = 5)
}

Description

An artificial longitudinal dataset comprising 200 trajectories belonging to one of 3 classes. Each trajectory deviates in intercept and slope from its respective class trajectory.

Usage

latrendData

Format

A data.frame comprising longitudinal observations from 200 trajectories. Each row represents the observed value of a trajectory at a specific moment in time.

Id

integer: The trajectory identifier.

Time

numeric: The measurement time, between 0 and 2.

Y

numeric: The observed value at the respective time Time for trajectory Id.

Class

factor: The reference class.

data(latrendData)
head(latrendData)
#>   Id      Time           Y   Class
#> 1  1 0.0000000 -1.08049205 Class 1
#> 2  1 0.2222222 -0.68024151 Class 1
#> 3  1 0.4444444 -0.65148373 Class 1
#> 4  1 0.6666667 -0.39115398 Class 1
#> 5  1 0.8888889 -0.19407876 Class 1
#> 6  1 1.1111111 -0.02991783 Class 1

Source

This dataset was generated using generateLongData.

See Also

latrend-data generateLongData

Examples

data(latrendData)

if (require("ggplot2")) {
  plotTrajectories(latrendData, id = "Id", time = "Time", response = "Y")

  # plot according to the reference class
  plotTrajectories(latrendData, id = "Id", time = "Time", response = "Y", cluster = "Class")
}

Description

Performs a repeated fit of the specified latrend model on the given data.

Usage

latrendRep(
  method,
  data,
  .rep = 10,
  ...,
  .errorHandling = "stop",
  .seed = NULL,
  .parallel = FALSE,
  envir = NULL,
  verbose = getOption("latrend.verbose")
)

Arguments

Details

This method is faster than repeatedly calling latrend as it only prepares the data via prepareData() once.

Value

A lcModels object containing the resulting models.

See Also

Other longitudinal cluster fit functions: latrend(), latrendBatch(), latrendBoot(), latrendCV()

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time")
models <- latrendRep(method, data = latrendData, .rep = 5) # 5 repeated runs

models <- latrendRep(method, data = latrendData, .seed = 1, .rep = 3)

Description

approx models have defined cluster trajectories at fixed moments in time, which should be interpolated For a correct implementation, lcApproxModel requires the extending class to implement clusterTrajectories(at=NULL) to return the fixed cluster trajectories

Usage

## S3 method for class 'lcApproxModel'
fitted(object, ..., clusters = trajectoryAssignments(object))

## S4 method for signature 'lcApproxModel'
predictForCluster(
  object,
  newdata,
  cluster,
  what = "mu",
  approxFun = approx,
  ...
)

Arguments

Description

A collection of special methods that adapt the fitting procedure of the underlying longitudinal cluster method.

NOTE: the underlying implementation is experimental and may change in the future.

Supported fit methods:

• lcFitConverged: Fit a method until a converged result is obtained.

• lcFitRep: Repeatedly fit a method and return the best result based on a given internal metric.

• lcFitRepMin: Repeatedly fit a method and return the best result that minimizes the given internal metric.

• lcFitRepMax: Repeatedly fit a method and return the best result that maximizes the given internal metric.

Usage

lcFitConverged(method, maxRep = Inf)

lcFitRep(method, rep = 10, metric, maximize)

lcFitRepMin(method, rep = 10, metric)

lcFitRepMax(method, rep = 10, metric)

Arguments

Details

Meta methods are immutable and cannot be updated after instantiation. Calling update() on a meta method is only used to update arguments of the underlying lcMethod object.

Examples

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time", nClusters = 2)
metaMethod <- lcFitConverged(method, maxRep = 10)
metaMethod
model <- latrend(metaMethod, latrendData)

data(latrendData)
method <- lcMethodLMKM(Y ~ Time, id = "Id", time = "Time", nClusters = 2)
repMethod <- lcFitRep(method, rep = 10, metric = "RSS", maximize = FALSE)
repMethod
model <- latrend(repMethod, latrendData)

minMethod <- lcFitRepMin(method, rep = 10, metric = "RSS")

maxMethod <- lcFitRepMax(method, rep = 10, metric = "ASW")

Description

lcMethod objects represent the specification of a method for longitudinal clustering. Furthermore, the object class contains the logic for estimating the respective method.

You can specify a longitudinal cluster method through one of the method-specific constructor functions, e.g., lcMethodKML(), lcMethodLcmmGBTM(), or lcMethodDtwclust(). Alternatively, you can instantiate methods through methods::new(), e.g., by calling new("lcMethodKML", response = "Value"). In both cases, default values are specified for omitted arguments.

Details

Because the lcMethod arguments may be unevaluated, argument retrieval functions such as [[ accept an envir argument. A default environment can be assigned or obtained from a lcMethod object using the environment() function.

Slots

arguments

A list representing the arguments of the lcMethod object. Arguments are not evaluated upon creation of the method object. Instead, arguments are stored similar to a call object, and are only evaluated when a method is fitted. Do not modify or access.

sourceCalls

A list of calls for tracking the original call after substitution. Used for printing objects which require too many characters (e.g. ,function definitions, matrices). Do not modify or access.

Method arguments

An lcMethod objects represent the specification of a method with a set of configurable parameters (referred to as arguments).

Arguments can be of any type. It is up to the lcMethod implementation of validate() to ensure that the required arguments are present and are of the expected type.

Arguments can have almost any name. Exceptions include the names "data", "envir", and "verbose". Furthermore, argument names may not start with a period (".").

Arguments cannot be directly modified, i.e., lcMethod objects are immutable. Modifying an argument involves creating an altered copy through the update.lcMethod method.

Implementation

The base class lcMethod provides the logic for storing, evaluating, and printing the method parameters.

Subclasses of lcMethod differ only in the fitting procedure logic.

To implement your own lcMethod subclass, you'll want to implement at least the following functions:

• fit(): The main function for estimating your method.

• getName(): The name of your method.

• getShortName(): The abbreviated name of your method.

• getArgumentDefaults(): Sensible default argument values to your method.

For more complex methods, the additional functions as part of the fitting procedure will be of use.

See Also

environment

Other lcMethod implementations: getArgumentDefaults(), getArgumentExclusions(), lcMethodAkmedoids, lcMethodCrimCV, lcMethodDtwclust, lcMethodFeature, lcMethodFunFEM, lcMethodFunction, lcMethodGCKM, lcMethodKML, lcMethodLMKM, lcMethodLcmmGBTM, lcMethodLcmmGMM, lcMethodMclustLLPA, lcMethodMixAK_GLMM, lcMethodMixtoolsGMM, lcMethodMixtoolsNPRM, lcMethodRandom, lcMethodStratify