Skip to contents

Help for old friends

Source: vignettes/oldfriends.Rmd
oldfriends.Rmd

Background

The brokenstick package has three major interfaces:

  1. Up to version brokenstick 0.62.1 (before May 2020)
  2. Up to version brokenstick 1.1.1 (May 2020 - Nov 2021)
  3. Versions higher than brokenstick 2.0.0 (Nov 2021 - now)

This document summarises the main changes in brokenstick 2.0.0. See “Help for old friends” in brokenstick 1.1.1 for an overview of the previous changes from 0.75.0 to 1.1.1.

Main changes

  1. Function brokenstick() in version 2.0.0 sets the Kasim-Raudenbush sampler as the default method. The former method lme4::lmer() remains available by setting method = "lmer" argument.

  2. Version 2.0.0 adopts the variable names of the coda package (e.g., start, end, thin, niter, and so on) and stores the results of the Kasim-Raudenbush sampler as objects of class mcmc.

  3. For method = "kr" one may now inspect the solution of the sampler by standard functions from the coda package. For method = "lmer" we can apply functions from the lme4 package for merMod objects.

  4. Version 2.0.0 redefines the brokenstick class. New entries include call, formula, internal, sample, light, data, imp and mod. Removed entries are knots (renamed to internal) and draws (renamed to imp). We may omit the newdata argument for the training data. Setting light = TRUE creates a small version of the brokenstick object. Objects of class brokenstick are not backwards compatible, so one should regenerate objects of class brokenstick in order use newer features in 2.0.0.

  5. Version 2.0.0 conforms to classic model fitting interface in R. Renames the new_data argument to newdata to conform to predict.lm(). Methods plot() and predict() no longer require a newdata argument. All special cases of predict() updated and explained in documentation and examples.

  6. Version 2.0.0 adds methods coef(), fitted(), model.frame(), model.matrix(), print() and summary() for the brokenstick object.

  7. Simplifies algorithmic control. Renames control_brokenstick() to set_control() and removes a layer in the control list.

  8. Added support for hide argument in user-oriented functions. Automatic suppression of last knot.

Minor changes

  • Stabilises the rgamma() calls in KR-algorithm for edge cases.
  • predict_brokenstick() can now work with the both (internal) training and (external) test data.
  • Removes the superfluous type argument from predict.brokenstick()
  • Adds a function get_omega() to extract the variance-covariance matrix of the broken stick estimates
  • Improves error messages of edge cases in test-brokenstick_edge.R
  • Perform stricter tests on arguments of brokenstick()
  • Introduces argument warn_splines in make_basis() to suppress uninteresting warns from splines::bs()
  • Removes superfluous knotnames argument in make_basis()
  • Argument x in make_basis() is now a vector instead of a column vector
  • Introduces new xname argument in make_basis() to set the xname

Install legacy version

We recommend changing your code to reflect the above changes and run brokenstick 2.4.0 or higher. If needed, version 1.1.1 can be installed as

library("devtools")
install_github("growthcharts/brokenstick@9b969af")

Examples

Example 1: Fit model

Fit model, brokenstick package version 0.75.0 - 1.1.1:

library(brokenstick)
data <- brokenstick::smocc_200

# formula interface
fit1 <- brokenstick(hgt.z ~ age | id, data)

# XY interface - numeric vector
# Deprecated in v2.0.0
fit2 <- with(data, brokenstick(age, hgt.z, id))

# XY interface - data.frame
# Deprecated in v2.0.0
fit3 <- with(data, brokenstick(data.frame(age), hgt.z, id))

# XY interface - matrix
# Deprecated in v2.0.0
tt <- as.matrix(data[, c(1, 2, 7)])
fit4 <- brokenstick(tt[, "age", drop = FALSE],
                    tt[, "hgt.z", drop = FALSE],
                    tt[, "id", drop = FALSE])

Fit model, brokenstick package version 2.4.0:

library(brokenstick)
data <- brokenstick::smocc_200

# formula interface
fit1 <- brokenstick(hgt_z ~ age | id, data)

Example 2: Predict model

Predict model, brokenstick package version 0.75.0 - 1.1.1:

# predict at observed data
p1 <- predict(fit1, data)

# predict at knots
p2 <- predict(fit1, data, x = "knots")

# predict at both observed data and knots
p3 <- predict(fit1, data, x = "knots", strip_data = FALSE)

# predict knots, broad matrix
p4 <- predict(fit1, data, x = "knots", shape = "wide")

Predict model, brokenstick package version 2.4.0:

# predict at observed data
p1 <- predict(fit1)

# predict at knots
p2 <- predict(fit1, x = "knots", include_data = FALSE)

# predict at both observed data and knots
p3 <- predict(fit1, x = "knots")

# predict knots, broad matrix
p4 <- predict(fit1, x = "knots", shape = "wide")

Example 3: Plot model

Plot trajectories, brokenstick package version 0.75.0 - 1.1.1:

ids <- c(10001, 10005, 10022)
plot(fit1, data, group = ids, what = "all")

Plot trajectories, brokenstick package version 2.4.0:

ids <- c(10001, 10005, 10022)
plot(fit1, group = ids, hide = "none")