Type: Package
Version: 0.7
Title: Tukeys Trend Test via Multiple Marginal Models
Date: 2020-03-13
Author: Frank Schaarschmidt [aut, cre], Christian Ritz [aut], Ludwig Hothorn [ctb]
Maintainer: Frank Schaarschmidt <schaarschmidt@biostat.uni-hannover.de>
Depends: multcomp
Imports: stats, pbkrtest, mgcv, lme4, nlme, Matrix
Suggests: knitr, xtable, reshape2, sandwich, CorrBin, SASmixed, SimComp, HSAUR3
VignetteBuilder: knitr
Description: Provides wrapper functions to the multiple marginal model function mmm() of package 'multcomp' to implement the trend test of Tukey, Ciminera and Heyse (1985) <doi:10.2307/2530666> for general parametric models.
License: GPL-2
NeedsCompilation: no
Packaged: 2020-03-13 13:42:32 UTC; Schaarschmidt
Repository: CRAN
Date/Publication: 2020-03-13 15:30:02 UTC

Coerce object of class 'tukeytrend' to 'glht'

Description

Transfers output of functions tukeytrendfit and tukeytrendformula to glht.

Usage

asglht(object, df = "mean", ...)

Arguments

object

an object of class 'tukeytrend' as results from functions tukeytrendfit, or tukeytrendformula

df

defines whether and how/which degrees of freedom are passed to glht for the computation of multivariate quantile. Can be a single character string, that names a function ("mean", "min", ...) to summarize the individual models' degrees of freedom to a single degree of freedom, defaults to computing the mean df of all the input models. Setting df=NULL invokes that no degree of freedom is passed to glht, i.e. asymptotic inference by use of multivariate normal quantiles. You may also specify a single integer df in this argument, which is then passed to glht.

...

further arguments to be passed to glht, e.g. alternative

Details

Passes the elements $mmm from tukeytrend output to glht, argument model, and $mlf to argument linfct, computes summary statistics for the vector of degrees of freedom in tukeytrend and passes it to glht, argument df. All other arguments are passed via ... to glht; be aware that mis-spelled arguments may be lost in glht.

Value

An object of class glht.

Examples

data(litter, package="multcomp")
dl <- litter
dl$dosen <- as.numeric(as.character(dl$dose))
fit <- lm(weight ~ dosen + number, data=dl)
ttlitter <- tukeytrendfit(fit, dose="dosen", 
 scaling=c("ari", "ord", "log"))

# instead of transferring individual elements from the
# tukeytrend output into the arguments of glht , ...
# comp1 <- glht(model=ttlitter$mmm, linfct=ttlitter$mlf,
# df=round(mean(ttlitter$df)), alternative="less")
# summary(comp1)

# ... you can just use:
comp2 <- asglht(ttlitter, alternative="less")
summary(comp2)

Combine several pobjects of class 'tukeytrend'

Description

Concatenate several objects of class 'tukeytrend', for example to perform inference for multiple marginal models with different endpoints or including different covariates.

Usage

combtt(...)

Arguments

...

names of tukeytrend objects (for multiple endpoinst, or with different covariates), separated by comma

Value

Same structure as output of tuketrendfit, see tukeytrendfit, tukeytrendformula

Examples


# Simulated data for normal and binomial response

dat <- data.frame(y = rnorm(20,0,1), 
 succ=rbinom(n=20, size=10, prob=0.3), 
 dose=rep(c(0,1,2,5,10), each=4))

# linear models with 3 different 
# scalings of the dose variable

fitn <- lm(y~dose, data=dat)
ttn <- tukeytrendfit(fitn, dose="dose",
 scaling=c("ari", "ord", "arilog"))

# generalized linear models with 3 
# different scalings of the dose variable
fitb <- glm(cbind(succ, 10-succ)~dose, data=dat, family=binomial)
ttb <- tukeytrendfit(fitb, dose="dose", 
 scaling=c("ari", "ord", "arilog"))

# concatenate the normal and binomial models
ttnb <- combtt(ttn, ttb)

# joint inference for the 6 regression slopes
summary(asglht(ttnb))

Rescaling dose variables acc. to Tukey et al. (1985)

Description

Add rescaled dose variables to a data.frame.

Usage

dosescalett(data, dose, 
scaling = c("ari", "ord", "log", "arilog"),
sep = "", d0shift = 1)

Arguments

data

a data.frame

dose

a single charcater string, naming the (numeric) variable in data that is to be rescaled

scaling

A vector of character strings, naming the options for rescaling the variable specified in dose: "ari": no rescaling, "ord": ranks of dose levels, "log": log-transformed dose levels, "arilog": log-transformned dose levels, with interpolated dose score for 0, "high.vs.low": dose coerced to a factor, and only highest and lowest dose level retained, all others set NA, "treat": dose coerced to a factor, all levels retained with the option to apply multiple contrast tests to the treatment levels

sep

an optional separator for the names of the rescaled variables

d0shift

an optional factor, that is multiplied with the interpolated dose score for dose = 0 in option scaling="arilog"; ignored in all other options for rescaling

Value

A list containing

data

the input data.frame, with rescaled variables added as colummns

transnam

a vector of names of the re-scaled variables

scaling

the scaling options, as input

Coerce objects of class lmerMod or lme to lm

Description

Coerce fitted mixed effect models of class lmerMod or lme to an lm-like object using a pseudo data approach (Ritz et al., 2017)

Usage

lmer2lm(lmerFit)

Arguments

lmerFit

a fitted object of class "lmerMod" or "lme", as can be obtained from packages "lme4" and "nlme"

Details

The returned object resembles a fitted model of class "lm" such that its asymptotic representation corresponds to that of the originally fitted mixed model, see Ritz et al. (2017) for details.

Author(s)

Christian Ritz

References

Christian Ritz, Rikke Pilmann Laursen and Camilla Trab Damsgaard (2017): Simultaneous inference for multilevel linear mixed models - with an application to a large-scale school meal study: Appl. Statist. 66, Part 2, pp. 295-311.

Fit multiple marginal models by updating a given fitted model object with re-scaled dose variable.

Description

Wrapper function to re-fit a given model after different rescalings of a single dose variable. The refitted models are combined into a list that is suitable as input to the multiple marginal model function of package multcomp, mmm.

Usage

tukeytrendfit(fit, dose, 
scaling = c("ari", "ord", "log", "arilog", "highvslow", "treat"),
ctype = NULL, ddf = c("residual", "KR", "PB"), d0shift = 1)

Arguments

fit

A fitted model object, currently, the classes lm, glm, lmer, and nlme are supported. The left hand side of the models formula must contain a single (numeric) variable that is treated as a dose variable in Tukeys trend test. It may contain further variables that are not changed when refitting the model.

dose

A single character string, naming a numeric variable in the models formula. This variable is rescaled acc. to the options in scaling and the model in fit is then refitted with the rescaled dose variable.

scaling

A vector of character strings, naming the options for rescaling the variable specified in dose: "ari": no rescaling, "ord": ranks of dose levels, "log": log-transformed dose levels, "arilog": log-transformnd dose levels, with interpolated dose score for 0, "high.vs.low": dose coerced to a factor, and only highest and lowest dose level retained, all others set NA, "treat": dose coerced to a factor, all levels retained with the option to apply multiple contrast tests to the treatment levels

ctype

optional character string naming a contrast type for multiple comparisons between dose levels, when scaling="treat". Options are "Dunnett", "William" etc., see ?contrMat in package multcomp. Argument ctype is ignored if scaling does not involve option "treat".

ddf

single character string, defining the option for the degree of freedom in inference after model fitting. By default, "residual" degrees of freedom will be used for all models. "KR": For models of class "lmerMod" (fitted by "lmer" from package "lme4"), Kenward-Roger degrees of freedom can be computed (based on methods from package "pbkrtest"); "PB": For models of class "lme" (fitted by "lme" from package "nlme"), containment degrees of freedom as defined by Pinheiro and Bates can be extracted.

d0shift

an optional factor, that is multiplied with the interpolated dose score for dose = 0 in option scaling="arilog"; ignored in all other options for rescaling

Value

A list with elements

mmm

a list of fitted models, after rescaling the dose variable

mlf

a list of matrices defining a linear functions of model parameters for each model in mmm, defining the parameter of interest for inference in function mlf and glht

df

a vector of degrees of freedom, one for each model in mmm

and information of the model typ and call of the initial model

Author(s)

Frank Schaarschmidt and Christian Ritz (providing internal functions to interface objects of class "lmerMod" and "lme")

References

Tukey JW, Ciminera JL, Heyse JF (1985). Testing the statistical certainty of a response to increasing doses of a drug. Biometrics 41(1), 295-301.

Pipper CB, Ritz C, Bisgaard H (2012). A versatile methode for confirmatory evaluation of the effects of a covariate in multiple models. JRSSC - Applied Statistics 61, 315-326.

See Also

Functions glht and mmm in package multcomp; tukeytrendformula for starting with a model formula and data.frame; combtt for concatenating several objects resulting from this function, e.g. for multiple endpoints or with different covariates; asglht for direct conversion to a glht-object

Examples


data(litter, package="multcomp")

# variable of interest is 'dose', but
# we may want to include 'number' as a covariate

dl <- litter
dl$dosen <- as.numeric(as.character(dl$dose))

fit <- lm(weight ~ dosen + number, data=dl)

# as it is unclear on which scale of dosage, 
# dose-response-shape is met best, we may try different
# re-scalings of the dose variable, including Dunnett- type multiple contrast test

ttlitter <- tukeytrendfit(fit, dose="dosen", 
 scaling=c("ari", "ord", "log", "treat"), ctype="Dunnett")

summary(asglht(ttlitter))

Fit multiple marginal models with differently re-scaled dose variable.

Description

Wrapper function to fit a given model after different rescalings of a single dose variable. The fitted models are combined into a list that is suitable as input to the multiple marginal model function of package multcomp, mmm.

Usage

tukeytrendformula(formula, data, model = "lm", dose,
scaling = c("ari", "ord", "log", "arilog", "treat", "treatHL"),
ctype = NULL, ddf = c("residual", "KR", "PB"), d0shift = 1, ...)

Arguments

formula

formula object suitable for the model function specified in model, the left hand side of the formual should contain at least one (numeric) variable, that is to be re-scaled in the model fits

data

data.frame containing the variables of interest

model

character string, naming the function for model fitting, currently "lm", c"glm", "lmer", "lme" are supported

dose

A single character string, naming a numeric variable in the models formula. This variable is rescaled acc. to the options in scaling and the model in fit is then refitted with the rescaled dose variable.

scaling

A vector of character strings, naming the options for rescaling the variable specified in dose: "ari": no rescaling, "ord": ranks of dose levels, "log": log-transformed dose levels, "arilog": log-transformned dose levels, with interpolated dose score for 0, "high.vs.low": dose coerced to a factor, and only highest and lowest dose level retained, all others set NA, "treat": dose coerced to a factor, all levels retained with the option to apply multiple contrast tests to the treatment levels

ctype

optional character string naming a contrast type for multiple comparisons between dose levels, when scaling="treat". Options are "Dunnett", "William" etc., see ?contrMat in package multcomp. Argument ctype is ignored if scaling does not involve option "treat".

ddf

single character string, defining the option for the degree of freedom in inference after model fitting. By default, "residual" degrees of freedom will be used for all models. "KR": For models of class "lmerMod" (fitted by "lmer" from package "lme4"), Kenward-Roger degrees of freedom can be computed (based on methods from package "pbkrtest"); "PB": For models of class "lme" (fitted by "lme" from package "nlme"), containment degrees of freedom as defined by Pinheiro and Bates can be extracted.

d0shift

an optional factor, that is multiplied with the interpolated dose score for dose = 0 in option scaling="arilog"; ignored in all other options for rescaling

...

arguments passed to the model fitting function named in model

Value

A list with elements

mmm

a list of fitted models, after rescaling the dose variable

mlf

a list of matrices defining a linear functions of model parameters for each model in mmm, defining the parameter of interest for inference in function mlf and glht

df

a vector of degrees of freedom, one for each model in mmm

and information of the model type and call of the initial model

Author(s)

Frank Schaarschmidt and Christian Ritz (providing internal functions to interface objects of class "lmerMod" and "lme")

References

Tukey JW, Ciminera JL, Heyse JF (1985). Testing the statistical certainty of a response to increasing doses of a drug. Biometrics 41(1), 295-301.

Pipper CB, Ritz C, Bisgaard H (2012). A versatile methode for confirmatory evaluation of the effects of a covariate in multiple models. JRSSC - Applied Statistics 61, 315-326.

Examples

data(litter, package="multcomp")

# compare

dl <- litter
dl$dosen <- as.numeric(as.character(dl$dose))

ttlitter <- tukeytrendformula(weight ~ dosen + number, data=dl, model="lm", dose="dosen", 
 scaling=c("ari", "ord", "log", "treat"), ctype="Dunnett")

summary(asglht(ttlitter))