Package 'tramME'

Description

Calculates information criteria and LR ratio test for nested tramME models. The calculation of the degrees of freedom is problematic, because the parameter space is restricted.

Usage

## S3 method for class 'tramME'
anova(object, object2, ...)

Arguments

Details

Currently only supports the comparison of two models. Additional arguments will be ignored.

The nestedness of the models is not checked.

Value

A data.frame with the calculated statistics.

Examples

data("sleepstudy", package = "lme4")
mod1 <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
mod2 <- LmME(Reaction ~ Days + (Days || Subject), data = sleepstudy)
anova(mod1, mod2)

Description

Estimates a mixed-effects additive transformation model with flexible smooth parameterization for the baseline transformation and the inverse link set to the CDF of the standard Gaussian distribution (see Hothorn et al., 2018).

Usage

BoxCoxME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The model extends tram::BoxCox with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with negative parameters (i.e. negative = TRUE in tram).

Value

A BoxCoxME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

data("sleepstudy", package = "lme4")
m <- BoxCoxME(Reaction ~ s(Days) + (Days | Subject), data = sleepstudy)
summary(m)

Description

Extracts the fixed effects coefficents (default behavior), the baseline parameters or all (baseline, fixed and random) coefficients of the model.

Usage

## S3 method for class 'LmME'
coef(object, as.lm = FALSE, fixed = TRUE, ...)

Arguments

Details

See also the documentation of coef.tramME.

Value

A numeric vector of the transformed coefficients.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
coef(fit, as.lm = TRUE)

Description

Extract the coefficients of the fixed effects terms of an SurvregME model.

Usage

## S3 method for class 'SurvregME'
coef(object, as.survreg = FALSE, ...)

Arguments

Value

A numeric vector of the transformed coefficients.

Examples

library("survival")
fit <- SurvregME(Surv(time, status) ~ rx + (1 | litter), data = rats)
coef(fit, as.survreg = TRUE)

Description

Extracts the fixed effects coefficents (default behavior), the baseline parameters or all (baseline, fixed and random) coefficients of the model.

Usage

## S3 method for class 'tramME'
coef(object, with_baseline = FALSE, fixed = TRUE, complete = FALSE, ...)

Arguments

Value

Numeric vector of parameter values.

Examples

library("survival")
mod <- SurvregME(Surv(time, status) ~ rx + (1 | litter/rx), data = rats,
                 dist = "exponential", nofit = TRUE)
coef(mod, with_baseline = TRUE)
coef(mod, with_baseline = TRUE, fixed = FALSE)

data("sleepstudy", package = "lme4")
mod2 <- BoxCoxME(Reaction ~ s(Days) + (Days || Subject), data = sleepstudy,
                 nofit = TRUE)
coef(mod2, complete = TRUE)

Description

Sets the whole vector of fixed-effects coefficients of a tramME model. The parameters of the baseline transformation function should respect the restrictions of the parameter space. This is checked before setting the new parameter values provided that the parameters for the variance components has already been set. If the model contains fixed coefficient parameters, the input should also respect that. When called on a fitted tram object, the function sets it to unfitted and removes all parts that come from the estimation.

Usage

## S3 replacement method for class 'tramME'
coef(object) <- value

Arguments

Value

A tramME object with the new coefficient values.

Examples

data("sleepstudy", package = "lme4")
mod <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy, nofit = TRUE)
coef(mod) <- c(-1, 0.5, 1)

Description

Estimates a mixed-effects additive transformation model with flexible smooth parameterization for the baseline transformation and the inverse link set to the CDF of the standard logistic distribution (see Hothorn et al., 2018).

Usage

ColrME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The model extends tram::Colr with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with positive parameters (i.e. negative = FALSE in tram).

Value

A ColrME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

data("neck_pain", package = "ordinalCont")
m <- ColrME(vas ~ time * laser + (1 | id), data = neck_pain,
            bounds = c(0, 1), support = c(0, 1), order = 6)
summary(m)

Description

Pointwise confidence intervals or multiplicity-adjusted confidence bands for transformation, distribution, survivor or cumulative hazard functions.

Usage

## S3 method for class 'tramME'
confband(
  object,
  newdata,
  level = 0.95,
  type = c("trafo", "distribution", "survivor", "cumhazard"),
  adjust = FALSE,
  K = 40,
  cheat = K,
  q = NULL,
  baseline_only = FALSE,
  ...
)

Arguments

Details

Similarly to confband, this method evaluates the conditional distribution of the outcome on a selected scale given a number of grid-points and claculates the corresponding confidence intervals or bands (adjusting for multiplicity).

The point estimates retured by this function could also be calculated with predict.tramME (when newdata does not contain response values and K is set to the number of grid points). While predict.tramME is designed to calculate a potentially large number of point estimates on a wider range of available scales, confband calculates the asymptotic intervals from the joint covariance matrix of the fixed and random effects. For technical reasons, a smaller set of type options are available, and the calculations are slower than with predict.tramME. The handling of random effects is currently stricter than in predict.tramME: No ranef option is available, and grouping factors for random effects supplied in newdata must have the same levels as the dataset used to fit the model.

The multiplicity adjustment is done using confint.glht. The cheat argument reduces the dimensionality of the multivariate root-finding problem (see qmvt) for speed and (occasionally) numerical stability. The critical value for the confidence bands are obtained for cheat < K grid points, but the confidence bands are calculated for K grid points. As a result, the nominal level of the returned confidence band is not maintained, but the deviation is expected to be small if cheat is reasonably large. It is the user's responsibility to set this value, and by default cheat = K.

Value

A matrix (in the case when newdata has a single row) or a list of matrices for each row of newdata.

Warning

This method implements new functionality. Its user interface may be subject to change.

Description

Confidence intervals for model parameters on their original scale, optionally consistent with the linear mixed-model specification. When as.lm = TRUE, only Wald CIs are available.

Usage

## S3 method for class 'LmME'
confint(
  object,
  parm = NULL,
  level = 0.95,
  as.lm = FALSE,
  pargroup = c("all", "fixef", "ranef"),
  type = c("Wald", "wald", "profile"),
  estimate = FALSE,
  ...
)

Arguments

Value

A matrix with lower and upper bounds.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
confint(fit) ## transformation model parameterization
confint(fit, as.lm = TRUE) ## LMM parameterization
confint(fit, as.lm = TRUE, pargroup = "fixef", estimate = TRUE)
confint(fit, as.lm = TRUE, parm = "(Sigma)") ## error SD

Description

Confidence intervals for model parameters on their original scale. Either Wald CI or profile CI by root finding. Multicore computations are supported in the case of profile confidence intervals, but snow support is yet to be implemented.

Usage

## S3 method for class 'tramME'
confint(
  object,
  parm = NULL,
  level = 0.95,
  pargroup = c("all", "fixef", "shift", "baseline", "ranef", "smooth"),
  type = c("Wald", "wald", "profile"),
  estimate = FALSE,
  pmatch = FALSE,
  parallel = c("no", "multicore", "snow"),
  ncpus = getOption("profile.ncpus", 1L),
  ...
)

Arguments

Value

A matrix with lower and upper bounds.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
confint(fit)
confint(fit, pargroup = "shift", estimate = TRUE)
exp(confint(fit, 1:2, pargroup = "ranef")) ## CIs for the SDs of the REs

Description

Estimates a mixed-effects additive transformation model with flexible smooth parameterization for the baseline transformation (log-cumulative baseline hazard) and the inverse link set to the CDF of the standard minimum extreme value distribution (see Hothorn et al., 2018).

Usage

CoxphME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The model extends tram::Coxph with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with positive parameters (i.e. negative = FALSE in tram).

Value

A CoxphME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

library("survival")
rats$litter <- factor(rats$litter)
m <- CoxphME(Surv(time, status) ~ rx + (1 | litter), data = rats,
             log_first = TRUE)
summary(m)

Description

Returns an estimate of effective degrees of freedom associated with each smooth term.

Usage

## S3 method for class 'tramME'
edf_smooth(object, ...)

Arguments

Details

The EDFs are calculated by summing up the elements of

$diag(V_{\vartheta}I)$

term-by-term. $V_{\vartheta}$ is the joint covariance matrix of fixed and random parameters (the inverse of the joint precision, i.e., Hessian of the negative log-likelihood), and $I$ is the joint precision of the unpenalized negative log-likelihood function. See Wood et al. (2016) or Wood (2017, Chapter 6) for references.

Value

A named vector with the edf values.

References

Wood, Simon N., Natalya Pya, and Benjamin Saefken (2016). "Smoothing Parameter and Model Selection for General Smooth Models." Journal of the American Statistical Association 111, <doi:10.1080/01621459.2016.1180986>

Wood, Simon N. (2017). Generalized Additive Models: An Introduction with R. Second edition. Chapman & Hall/CRC Texts in Statistical Science.

Examples

data("mcycle", package = "MASS")
fit <- LmME(accel ~ s(times), data = mcycle)
edf_smooth(fit)

Description

Estimates a mixed-effects additive transformation model with flexible smooth parameterization for the baseline transformation and the inverse link set to the CDF of the standard maximum extreme value distribution (see Hothorn et al., 2018).

Usage

LehmannME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The model extends tram::Lehmann with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with negative parameters (i.e. negative = TRUE in tram).

Value

A LehmannME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

data("sleepstudy", package = "lme4")
m <- LehmannME(Reaction ~ s(Days) + (Days | Subject), data = sleepstudy)
summary(m)

Description

Estimates the normal linear model parameterized as a linear transformation model.

Usage

LmME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The additive mixed-effects normal linear model is a special case of the mixed-effects additive transformation model family, with the transformation function restricted to be linear and the inverse link set to the standard Gaussian CDF (see Hothorn et al., 2018). This function estimates this model with the transformation model parameterization, and offers features that are typically not available in other mixed-effects additive implementations, such as stratum-specific variances, and censored and/or truncated observations.

The model extends tram::Lm with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with negative parameters (i.e. negative = TRUE in tram).

The results can be transformed back to the usual linear mixed/additive model parametrization with specific methods provided by tramME. The differences between the two parametrizations are discussed in Tamasi and Hothorn (2021).

Value

A LmME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

library("survival")
data("sleepstudy", package = "lme4")
## Create a version of the response with 200 ms detection limit and 50 ms
## step sizes
ub <- ceiling(sleepstudy$Reaction / 50) * 50
lb <- floor(sleepstudy$Reaction / 50) * 50
lb[ub == 200] <- 0
sleepstudy$Reaction_ic <- Surv(lb, ub, type = "interval2")
m <- LmME(Reaction_ic ~ Days + (Days | Subject), data = sleepstudy)
summary(m)
coef(m, as.lm = TRUE)

Description

Evaluates the log-likelihood function. New parameter values and data can optionally be supplied. In the latter case, the function returns the out-of-sample log-likelihood.

Usage

## S3 method for class 'tramME'
logLik(
  object,
  param = NULL,
  newdata = NULL,
  type = c("integrated", "fix_smooth", "penalized"),
  ...
)

Arguments

Details

By default, param is set to the estimated (or previously set) parameters. If the parameter vectors in the model are incomplete (contain NA elemets), the returned log-likelihood will also be NA, unless the user provides new values.

Setting type = "fix_smooth" fixes the random effects terms that correspond to penalized smooths at their estimated values, so that they are not refitted when newdata is supplied. This is consistent with treating these parameter regularized fixed terms, i.e. as 'new-style' random effects described by Hodges (2014, Chapter 13).

The "fix_smooth" and "penalized" options for type are just for convenience. The same functionality can be achieved by setting param$gamma to the desired values. "penalized" respects the values of param$gamma if both are supplied, while "fix_smooth" overwrites them with the fitted values if there are ambiguities.

Value

A numeric value of the log-likelihood.

Type of the log-likelihood

By default, logLik calculates the _integrated_ (or marginal) log-likelihood by integrating over the random effects. By fixing the random effects, the value of the log-likelihood changes, because TMB won't integrate over these random effects. This will result in the _penalized_ log-likelihood (conditional log-likelihood + penalty for smooth terms and random effects, see example).

By setting type = "penalized", the function will 'fix' all random effects and penalized parameters of the smooth terms at their predicted levels, and calcualte the penalized log-likelihood. In this sense, setting type = "fix_smooth" will result in a hybrid log-likelihood value, where the 'true' random effects (c.f. Hodges 2014, Ch. 13) are integrated out, while it includes the penalty values for the penalized parameters of the smooths terms.

In general, it is not clear which type of log-likelihood we should calculate when we want to evaluate models based on their out-of-sample log-likelihood values. The context and the model setup are key in these cases. Please make sure you know what you want to calculate to avoid misunderstandings.

References

Hodges, James S. (2014). Richly Parameterized Linear Models: Additive, Time Series, and Spatial Models Using Random Effects. Chapman & Hall/CRC Texts in Statistical Science Series.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
logLik(fit)

data("mcycle", package = "MASS")
fit <- LmME(accel ~ s(times), data = mcycle)
logLik(fit) < logLik(fit, type = "penalized")

Description

Extract model frame from a tramME model

Usage

## S3 method for class 'tramME'
model.frame(
  formula,
  data = NULL,
  group_as_factor = FALSE,
  ignore_response = FALSE,
  ...
)

Arguments

Details

In mlt, the basis functions expect the response variables in the data to be evaluated, i.e. instead of x and y columns we should have a `Surv(x, y)` column when the response is a Surv object. model.frame.tramME builds the model frame accordingly, assigning to the resulting object the class tramME_data to indicate this structure to other functions that use its results. If the input data is a tramME_data is also expects this structure.

Value

A tramME_data object, which is also a data.frame.

Examples

data("sleepstudy", package = "lme4")
mod <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy, nofit = TRUE)
model.frame(mod)

Description

Model matrix for fixed effects, random effects, and baseline transformations (with interacting terms if present).

Usage

## S3 method for class 'tramME'
model.matrix(
  object,
  data = model.frame(object),
  type = c("Y", "X", "Zt"),
  drop_unused_groups = FALSE,
  keep_sign = TRUE,
  simplify = FALSE,
  ...
)

Arguments

Details

Creates model matrices for fixed effects (type = "X") and random effects (type = "Zt") and baseline transfromation (type = "Y"), by evaluating the respective basis functions given a new dataset.

The response values may be exact, censored (left, right, interval) and truncated (left, right, interval), and the function returns several, potentially empty, model matrices:

• Ye: Exact observations.

• Yeprime: The model matrix corresponding to the first derivative of the baseline transformation, evaluated at exact observations.

• Yl: Left-censored observations.

• Yr: Rigt-censored observations.

• Yil and Yir: Interval-censored observations evaluated at the left and right bounds of the interval.

• Ytl: Left-truncated observations.

• Ytr: Rigt-truncated observations.

• Ytil and Ytir: Interval-truncated observations evaluated at the left and right bounds of the interval.

for the baseline transfromations (unless simplify = TRUE).

Value

List of requested model matrices.

Note

The model matrix of the random effects is a sparse matrix and it is transposed to be directly used with Matrix::crossprod which is faster than transposing and multiplying ("Zt" instead of "Z").

Examples

library("survival")
rats$litter <- factor(rats$litter)
m <- CoxphME(Surv(time, status) ~ rx + (1 | litter), data = rats,
             log_first = TRUE, nofit = TRUE)
mm <- model.matrix(m)
nd <- model.frame(m)[rep(1, 100), ]
nd[[1]] <- seq(1, 120, length.out = 100)
mm2 <- model.matrix(m, data = nd, simplify = TRUE)
mm3 <- model.matrix(m, data = nd, simplify = TRUE, drop_unused_groups = TRUE)
## compare mm2$Zt & mm3$Zt

Description

Set up and control optimization parameters

Usage

optim_control(
  method = c("nlminb", "BFGS", "CG", "L-BFGS-B"),
  scale = TRUE,
  trace = FALSE,
  ntry = 5,
  ok_warnings = "NA/NaN function evaluation",
  ...
)

Arguments

Note

Irrespective of the value of the ok_warnings argument, all warnings are collected in the opt$warnings element of the tramME object.

Description

Plotting method for confband.tramME objects.

Usage

## S3 method for class 'confband.tramME'
plot(
  x,
  col,
  lty,
  fill,
  add = FALSE,
  single_plot = FALSE,
  trafo_x = identity,
  trafo_y = identity,
  align_xlim = FALSE,
  align_ylim = FALSE,
  ...
)

Arguments

Description

Plot smooth terms of a tramME model.

Usage

## S3 method for class 'smooth.tramME'
plot(
  x,
  which = seq_along(x),
  col = 1,
  fill = grey(0.5, 0.25),
  trafo = I,
  add = FALSE,
  ...
)

Arguments

Examples

data("mcycle", package = "MASS")
fit <- LmME(accel ~ s(times), data = mcycle)
plot(smooth_terms(fit, as.lm = TRUE))

Description

Plot the conditional distribution evaluated at a grid of possible response values and a set of covariate and random effects values on a specified scale.

Usage

## S3 method for class 'tramME'
plot(
  x,
  newdata = model.frame(x),
  ranef = NULL,
  fix_smooth = TRUE,
  type = c("trafo", "distribution", "logdistribution", "survivor", "logsurvivor",
    "density", "logdensity", "hazard", "loghazard", "cumhazard", "logcumhazard", "odds",
    "logodds", "quantile"),
  ...
)

Arguments

Details

When ranef is equal to "zero", a vector of zeros with the right size is substituted. For more details, see predict.tramME.

For more information on how to control the grid on which the functions are evaluated, see the documentation of predict.mlt.

Value

A numeric matrix of the predicted values invisibly.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
plot(fit, K = 100, type = "density")

Description

Estimates mixed-effects additive transformation models for ordered categorical responses with various link functions.

Usage

PolrME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  method = c("logistic", "probit", "loglog", "cloglog"),
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The transformation function is parameterized as a step function on a scale defined by the link function (see Hothorn et al., 2018).

The model extends tram::Polr with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with negative parameters (i.e. negative = TRUE in tram).

Value

A PolrME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

data("soup", package = "ordinal")
m <- PolrME(SURENESS | SOUPFREQ ~ PROD + (1 | RESP/PROD),
            data = soup, method = "probit")
summary(m)

Description

Evaluates the _conditional_ distribution implied by a tramME model, given by a set of covariates and random effects on a selected scale.

Usage

## S3 method for class 'tramME'
predict(
  object,
  newdata = model.frame(object),
  ranef = NULL,
  fix_smooth = TRUE,
  type = c("lp", "trafo", "distribution", "logdistribution", "survivor", "logsurvivor",
    "density", "logdensity", "hazard", "loghazard", "cumhazard", "logcumhazard", "odds",
    "logodds", "quantile"),
  ...
)

Arguments

Details

When newdata contains values of the response variable, prediction is only done for those values. In this case, if random effects vector (ranef) is not supplied by the user, the function predicts the random effects from the model using newdata.

When no response values are supplied in newdata, the prediction is done on a grid of values for each line of the dataset (see predict.mlt for information on how to control the setup of this grid). In this case, the user has to specify the vector of random effects to avoid ambiguities.

The linear predictor (type = "lp") equals to the shift terms plus the random effects terms _without the baseline transfromation function_.

The linear predictor (type = "lp") and the conditional quantile function (type = "quantile") are special in that they do not return results evaluated on a grid, even when the response variable in newdata is missing. The probabilities for the evaluation of the quantile function can be supplied with the prob argument of predict.mlt.

In the case of type = "quantile", when the some of the requested conditonal quantiles fall outside of the support of the response distribution (specified when the model was set up), the inversion of the CDF cannot be done exactly and tramME returns censored values.

ranef can be different objects based on what we want to calculate and what the other inputs are. If ranef is a ranef.tramME, we assume that it contains the full set of random effects, but not the penalized coefficients of the smooth terms. In this case fix_smooth must be TRUE. If ranef is a named vector, we are fixing the supplied random effects (and penalized coefficients) and predict the rest from newdata (fix_smooth may also be used in this case). In this case, the random effects are identified with the same naming convention as in object$param$gamma.

If ranef is an unnamed vector, the function expects the full set of necessary random effects (with or without penalized coefficients, depending on fix_smooth). If ranef = NULL (the default), all random effects and optionally penalized parameters (although this is not recommended) are predicted from newdata. Finally, if ranef is equal to "zero", a vector of zeros with the right size is used.

Value

A numeric vector/matrix of the predicted values (depending on the inputs) or a response object, when the some of the requested conditonal quantiles fall outside of the support of the response distribution specified when the model was set up (only can occur with type = "quantile").

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
predict(fit, type = "trafo") ## evaluate on the transformation function scale
nd <- sleepstudy
nd$Reaction <- NULL
pr <- predict(fit, newdata = nd, ranef = ranef(fit), type = "distribution",
              K = 100)

Description

Post-estimation calculations in a tramTMB model

Usage

## S3 method for class 'tramTMB'
predict(
  object,
  newdata,
  parameters = .get_par(object, full = TRUE),
  scale = c("lp", "trafo"),
  cov = FALSE,
  as.lm = FALSE,
  ...
)

Arguments

Description

Printing anova.tramME table

Usage

## S3 method for class 'anova.tramME'
print(
  x,
  digits = max(getOption("digits") - 2L, 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

Arguments

Value

Invisibly retrurns the anova.tramME object.

Description

Print method for tramME model summary

Usage

## S3 method for class 'summary.tramME'
print(
  x,
  fancy = !isTRUE(getOption("knitr.in.progress")) && interactive(),
  digits = max(getOption("digits") - 2L, 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

Arguments

Value

The input summary.tramME object, invisibly.

Description

Print tramME model

Usage

## S3 method for class 'tramME'
print(x, digits = max(getOption("digits") - 2L, 3L), ...)

Arguments

Value

The original tramME object invisibly

Description

Print method for the variance-correlation parameters of a tramME object

Usage

## S3 method for class 'VarCorr.tramME'
print(x, sd = TRUE, digits = max(getOption("digits") - 2L, 3L), ...)

Arguments

Value

Invisibly returns the input VarCorr.tramME object.

Description

The condVar option is not implemented for ranef.LmME. Setting raw=TURE will return the raw random effects estimates from the transformation model parameterization.

Usage

## S3 method for class 'LmME'
ranef(object, as.lm = FALSE, ...)

Arguments

Value

A numeric vector or a ranef.tramME object depending on the inputs.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
ranef(fit, raw = TRUE) ## transformation model parameterization!
ranef(fit, as.lm = TRUE)

Description

Extract the conditional modes and conditional variances of random effects in a formatted or unformatted way.

Usage

## S3 method for class 'tramME'
ranef(
  object,
  param = NULL,
  newdata = NULL,
  fix_smooth = !is.null(newdata),
  condVar = FALSE,
  raw = FALSE,
  ...
)

Arguments

Details

raw = TRUE returns the whole vector of random effects (i.e. with parameters of smooth shift terms), while raw = FALSE only returns the formatted list of actual random effects (i.e. for grouped observations) values. For the conceptual differences between the two types of random effects, see Hodges (2014, Chapter 13).

The conditional variances of the fixed random effects are set to NA.

Value

Depending on the value of raw, either a numeric vector or a ranef.tramME object which contains the conditional mode and variance estimates by grouping factors.

Warning

The function has several optional arguments that allow great flexibilty beyond its most basic usage. The user should be careful with setting these, because some combinations might not return sensical results. Only limited sanity checks are performed.

References

Hodges, James S. (2014). Richly Parameterized Linear Models: Additive, Time Series, and Spatial Models Using Random Effects. Chapman & Hall/CRC Texts in Statistical Science Series.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy, order = 5)
ranef(fit, raw = TRUE)
ranef(fit)

Description

Calculates the score residuals of an intercept term fixed at 0. In the case of an LmME model, this is equal to the residual of an LMM.

Usage

## S3 method for class 'LmME'
residuals(object, as.lm = FALSE, ...)

Arguments

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
resid(fit)

Description

Calculates the score residuals of an intercept term fixed at 0.

Usage

## S3 method for class 'tramME'
residuals(
  object,
  param = NULL,
  newdata = NULL,
  fix_smooth = !is.null(newdata),
  ...
)

Arguments

Examples

library("survival")
fit <- SurvregME(Surv(time, status) ~ rx + (1 | litter), data = rats)
resid(fit)

Description

Response objects to represent censored and truncated observations

Usage

Resp(
  cleft,
  cright,
  tleft,
  tright,
  bounds = c(-Inf, Inf),
  open_lwr_bnd = TRUE,
  tol = sqrt(.Machine$double.eps)
)

## S3 method for class 'Resp'
R(object, ...)

## S3 method for class 'Resp'
print(x, ...)

## S3 method for class 'Resp'
x[i, j, drop = FALSE]

## S3 method for class 'Resp'
is.na(x)

## S3 method for class 'Resp'
length(x)

## S3 method for class 'Resp'
format(x, ...)

Arguments

Details

Resp extends the functionality of Surv class by allowing cases that cannot be defined with it. An example is an interval-censored outcome with left truncatation (see Examples).

Censored and exactly observed data can be defined similarly to type = "interval2" objects in Surv. NA values for left or right censoring borders mean left- or right-censored observations, respectively. If both borders are NA, the observation is considered NA by is.na(). Truncation times (tleft and tright arguments) can be omitted or take NA values, which means no truncation. If only the censoring intervals are provided, i.e., no trunction is present, the function returns a Surv object.

Resp also provides a limited interface between tramME and the response class (technically, inherits from it) of mlt (see R), which uses an internal representation that is not compatible with tramME.

The optional argument open_lwr_bnd can be used to enforce lower boundaries of the outcome. Left boundaries in the Resp object (cleft and tleft) that are equal to the first element of bounds will be increased with one tol value to avoid downstream numerical problems in mlt. This adjustment is recorded and reversed when we print the object.

Value

A Resp object or a Surv object

Methods (by generic)

• R(Resp): Converting Resp objects to response (from mlt) objects (see R)

• print(Resp): Print method for the Resp class

• [: Subsetting Resp objects

• is.na(Resp): Missing values

• length(Resp): Length of a Resp object

• format(Resp): format method for a Resp object

Warning

This function is experimental and currently limited to continuous outcome types. It may be subject to change.

Examples

dat <- data.frame(x1 = 1:10, x2 = c(2:10, NA), x3 = c(NA, 0:8))
dat$r <- with(dat, Resp(x1, x2, x3))

dat$r
dat[1:3, ]$r
dat$r[1:3]

is.na(dat$r)

model.frame(r ~ 1, data = dat, na.action = na.omit)

Description

Extract the SD of the error term of an LmME model.

Usage

## S3 method for class 'LmME'
sigma(object, ...)

Arguments

Value

A numeric value of the transformed sigma parameter.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
sigma(fit)

Description

Simulate from a tramME model

Usage

## S3 method for class 'tramME'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  newdata = model.frame(object),
  type = c("ranef", "response", "joint"),
  ...
)

Arguments

Value

A length nsim list of draws.

Warning

This method is under active development and may be subject to change. It is currently limited to simulating random effects.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
sim <- simulate(fit, nsim = 10, seed = 123)

Description

Evaluate smooth terms of a LmME model.

Usage

## S3 method for class 'LmME'
smooth_terms(object, as.lm = FALSE, k = 100, newdata = NULL, ...)

Arguments

Value

A list of results from evaluating the smooth terms of the model.

Examples

data("mcycle", package = "MASS")
fit <- LmME(accel ~ s(times), data = mcycle)
plot(smooth_terms(fit, as.lm = TRUE))

Description

Extract and evaluate the smooth terms of a tramME model

Usage

## S3 method for class 'tramME'
smooth_terms(object, k = 100, newdata = NULL, ...)

Arguments

Value

A list of results from evaluating the smooth terms of the model.

Examples

data("mcycle", package = "MASS")
fit <- LmME(accel ~ s(times), data = mcycle)
plot(smooth_terms(fit))

Description

Summary method for tramME model

Usage

## S3 method for class 'tramME'
summary(object, ...)

Arguments

Value

A summary.tramME object.

Description

Estimates various mixed-effects additive parametric models (not exclusively) for survival analysis.

Usage

SurvregME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action = na.omit,
  dist = c("weibull", "logistic", "gaussian", "exponential", "rayleigh", "loggaussian",
    "lognormal", "loglogistic"),
  scale = 0,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The parameterization is slightly different from survival::survreg, see Hothorn et al. (2018). The results can be transformed back to the survreg parameterization with specific methods provided by tramME.

The model extends tram::Survreg with random effects and (optionally penalized) additive terms. For details on mixed-effect transformation models, see Tamasi and Hothorn (2021).

The elements of the linear predictor are parameterized with negative parameters (i.e. negative = TRUE in tram).

Value

A SurvregME model object.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Examples

library("survival")
rats$litter <- factor(rats$litter)
m <- SurvregME(Surv(time, status) ~ rx + (1 | litter), data = rats,
               dist = "weibull")
summary(m)
coef(m, as.survreg = TRUE)

Description

A general function to define and fit tramME models.

Usage

tramME(
  formula,
  data,
  subset,
  weights,
  offset,
  na.action,
  tram = NULL,
  call = NULL,
  ctm = NULL,
  smooth = NULL,
  negative = NULL,
  silent = TRUE,
  resid = FALSE,
  do_update = FALSE,
  estinit = TRUE,
  initpar = NULL,
  fixed = NULL,
  nofit = FALSE,
  control = optim_control(),
  ...
)

Arguments

Details

The specific model functions (LmME, BoxCoxME, ColrME, etc.) are wrappers around this function.

For a general description of the transformation model family, see Hothorn et al. (2018), for details on the mixed-effects extension, see Tamasi and Hothorn (2021).

Warning

Typically, the tramME function shouldn't be called directly; it is only exported to allow the advanced users to define their tramME models in a more flexible way from their basic building blocks.

References

Hothorn, Torsten, Lisa Möst, and Peter Bühlmann. "Most Likely Transformations." Scandinavian Journal of Statistics 45, no. 1 (March 2018): 110–34. <doi:10.1111/sjos.12291>

Tamasi, Balint, and Torsten Hothorn. "tramME: Mixed-Effects Transformation Models Using Template Model Builder." The R Journal 13, no. 2 (2021): 398–418. <doi:10.32614/RJ-2021-075>

Description

Create a tramTMB object

Usage

tramTMB(
  data,
  parameters,
  constraint,
  negative,
  map = list(),
  resid = FALSE,
  do_update = FALSE,
  check_const = TRUE,
  no_int = FALSE,
  ...
)

Arguments

Value

A tramTMB object.

Note

The post-estimation parameters are supplied as a part of data

Description

The returned parameters are the transformed versions of the original parameters that correspond to the normal linear mixed model parameterization.

Usage

## S3 method for class 'LmME'
VarCorr(x, sigma = 1, as.lm = FALSE, ...)

Arguments

Details

The function only returns the correlation matrices that belong to actual random effects (defined for groups in the data) and ignores the random effects parameters of the smooth shift terms. To extract these, the user should use varcov with full = TRUE.

Value

A list of vectors with variances and correlation matrices corresponding to the various grouping variables.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
VarCorr(fit) ## tranformation model parameterization
VarCorr(fit, as.lm = TRUE) ## LMM parameterization

Description

This function calculates the variances and correlations from varcov.tramME.

Usage

## S3 method for class 'tramME'
VarCorr(x, ...)

Arguments

Details

The function only returns the correlation matrices that belong to actual random effects (defined for groups in the data) and ignores the random effects parameters of the smooth shift terms. To extract these, the user should use varcov with full = TRUE.

Note that, by default, print.VarCorr.tramME prints the standard deviations of the random effects, similarly to lme4.

Value

A list of vectors with variances and correlation matrices corresponding to the various grouping variables.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
VarCorr(fit)

Description

Generic method for varcov

Usage

varcov(object, ...)

Arguments

Value

A variance-covariance matrix.

Description

Extract the variance-covariance matrix of the random effects of an LmME model

Usage

## S3 method for class 'LmME'
varcov(object, as.lm = FALSE, as.theta = FALSE, full = FALSE, ...)

Arguments

Value

A list of the covariance matrices or a vector of theta values.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
varcov(fit, as.lm = TRUE)
varcov(fit, as.theta = TRUE, as.lm = TRUE)

Description

Returns the covariance matrix of the random effects as saved in the tramME object. The returned values correspond to the transformation model parametrization.

Usage

## S3 method for class 'tramME'
varcov(object, as.theta = FALSE, full = FALSE, ...)

Arguments

Value

A list of the covariance matrices or a vector of theta values.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
varcov(fit)
varcov(fit, as.theta = TRUE)

Description

Generic method for "varcov<-"

Usage

varcov(object, ...) <- value

Arguments

Value

An object with the same class as object, with updated variance-covariance matrix of random effects.

Description

Sets the list containing the covariance matrices of a tramME model. The matrices have to be positive definite. Just as in "coef<-", when the function is called on a fitted object, the function will remove the infromation about the optimization.

Usage

## S3 replacement method for class 'tramME'
varcov(object, as.theta = FALSE, ...) <- value

Arguments

Details

The supplied list has to be named with the same names as implied by the model. Hence, it might be a good idea to call varcov first, and modify this list to make sure that the input has the right structure.

The new values can also be supplied in a form that corresponds to the reparametrization used by the tramTMB model (see the option as.theta = TRUE).

All random effects variance parameters must be supplied. When there are penalized smooth terms in the model variance parameters corresponding to these should also be part of the input list.

Value

A new tramME object with the new coefficient values.

Examples

data("sleepstudy", package = "lme4")
mod <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy, nofit = TRUE)
vc <- varcov(mod)
vc[[1]] <- matrix(c(1, 0, 0, 2), ncol = 2)
varcov(mod) <- vc

Description

Returns the variable names corresponding to different variable groups in a tramME model.

Usage

## S3 method for class 'tramME'
variable.names(
  object,
  which = c("all", "response", "grouping", "shifting", "interacting", "smooth", "ranef"),
  ...
)

Arguments

Details

The returned names are the names as they are used by tramME. For example, when the response is a Surv object, variable.names returns the name of that object, and not the names of the variables used to create it.

Value

A vector of variable names.

Examples

data("sleepstudy", package = "lme4")
mod <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy, nofit = TRUE)
variable.names(mod)
variable.names(mod, "response")

Description

Get the variance-covariance matrix of the parameters of an LmME model

Usage

## S3 method for class 'LmME'
vcov(
  object,
  as.lm = FALSE,
  parm = NULL,
  pargroup = c("all", "fixef", "ranef"),
  ...
)

Arguments

Value

A numeric covariance matrix.

Examples

data("sleepstudy", package = "lme4")
fit <- LmME(Reaction ~ Days + (Days | Subject), data = sleepstudy)
vcov(fit) ## transformation model parameterization
vcov(fit, as.lm = TRUE) ## LMM parameterization
vcov(fit, as.lm = TRUE, pargroup = "fixef") ## cov of fixed effects

Description

Extracts the covariance matrix of the selected parameters. The returned values are on the same scale as the estimated parameter values, i.e. the standard deviations of the random effect terms are on log scale.

Usage

## S3 method for class 'tramME'
vcov(
  object,
  parm = NULL,
  pargroup = c("all", "fixef", "shift", "baseline", "ranef", "smooth"),
  pmatch = FALSE,
  ...
)

Arguments

Details

Access to variances and covariances of penalized parameters is currently provided by the parm argument. Parameter names must be consistent with names in object$param.

Value

A numeric covariance matrix.

Examples

data("sleepstudy", package = "lme4")
fit <- BoxCoxME(Reaction ~ Days + (Days | Subject), data = sleepstudy, order = 10)
vcov(fit)
vcov(fit, pargroup = "ranef")
vcov(fit, pargroup = "baseline")
vcov(fit, parm = "Reaction") ## same as previous