Help for package rmt

Type:

Package

Title:

Restricted Mean Time in Favor of Treatment

Version:

1.0

Author:

Lu Mao

Maintainer:

Lu Mao <lmao@biostat.wisc.edu>

URL:

https://sites.google.com/view/lmaowisc/

Description:

Contains inferential and graphical routines for comparing two treatment arms in terms of the restricted mean time in favor of treatment.

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Encoding:

UTF-8

LazyData:

true

RoxygenNote:

7.1.1

Suggests:

knitr, rmarkdown

VignetteBuilder:

knitr

Depends:

R (≥ 2.10)

NeedsCompilation:

Packaged:

2021-05-21 12:41:32 UTC; lmao

Repository:

CRAN

Date/Publication:

2021-05-25 06:40:03 UTC

Bouquet plot

Description

Construct the bouquet plot based on the estimated stage-wise restricted mean win/loss times.

Usage

bouquet(
  x,
  Kmax = NULL,
  xlim = NULL,
  ylim = NULL,
  xlab = "Restricted mean win/loss time",
  ylab = "Follow-up time",
  group.label = TRUE,
  cex.group = 1,
  ...
)

Arguments

x

An object returned by rmtfit.

Kmax

A positive integer; If specified, the stage-wise estimates over Kmax,\ldots,K will be aggregated.

xlim

The x limits of the plot.

ylim

The y limits of the plot.

xlab

A label for the x axis, defaults to a description of x.

ylab

A label for the y axis, defaults to a description of x.

group.label

If TRUE, group labels will appear on the two sides of the plot.

cex.group

Font size of the group labels if group.label=TRUE.

...

Other arguments that can be passed to the underlying plot method.

Value

No return value, called for side effects.

Examples

# load the colon cancer trial data
library(rmt)
head(colon_lev)
# fit the data
obj=rmtfit(ms(id,time,status)~rx,data=colon_lev)
# bouquet plot
bouquet(obj)

A dataset from a landmark colon cancer trial

Description

A landmark colon cancer trial on the efficacy of levamisole and fluorouracil was reported by Moertel et al. (1990). The trial recruited 929 patients with stage C disease and randomly assigned them to levamisole treatment alone, levamisole combined with fluorouracil, and the control. The dataset here is restricted to the comparison between the combined treatment and control groups, consisting of 304 and 314 patients, respectively.

Usage

colon_lev

Format

A data frame with 915 rows and 6 variables:

id: Unique patient ID.
time: Event time (years).
status: Event type; 1 = cancer relapse, 2 = death.
rx: "Lev+5FU" = combined treatment, "Control" = control.
age: Patient age (years) at randomization.
sex: 0 = female, 1 = male.

References

MOERTEL, C. G., FLEMING, T. R., MACDONALD, J. S., HALLER, D. G., LAURIE, J. A., GOODMAN, P. J., UNGERLEIDER, J. S., EMERSON, W. A., TORMEY, D. C., GLICK, J. H. et al. (1990). Levamisole and fluorouracil for adjuvant therapy of resected colon carcinoma. New Engl. J. Med. 322, 352–358.

A dataset from the HF-ACTION trial

Description

Over two thousand heart failure patients across the USA, Canada, and France participated in the Heart Failure: A Controlled Trial Investigating Outcomes of Exercise Training (HF-ACTION) between 2003–2007 (O'Connor et al., 2009). The primary objective of the trial was to evaluate the effect of adding exercise training to the usual patient care on the composite endpoint of all-cause hospitalization and death. The dataset here contains a subgroup of 426 non-ischemic patients with baseline cardio-pulmonary exercise test less than or equal to nine minutes.

Usage

hfaction

Format

A data frame with 1,448 rows and 5 variables:

patid: Unique patient ID.
time: Event time (years).
status: Event type; 1 = hospitalization, 2 = death.
trt_ab: 1 = exercise training, 0 = usual care.
age60: 1 = 60 years or older, 0 = otherwise.

References

O'CONNOR, C. M., WHELLAN, D. J., LEE, K. L., KETEYIAN, S. J., COOPER, L. S., ELLIS, S. J., LEIFER, E. S., KRAUS, W. E., KITZMAN, D. W., BLUMENTHAL, J. A. et al. (2009). Efficacy and safety of exercise training in patients with chronic heart failure: Hf-action randomized controlled trial. J. Am. Med. Assoc. 301, 1439–1450.

Create a multistate event object

Description

Create a multistate event object

Usage

ms(id, time, status)

Arguments

id

A vector of id variable.

time

A vector of follow-up times.

status

A vector of event type, k if transitioning to state k, 0 if censored and K+1 represents death.

Value

An object of class ms used as an argument for rmtfit.

Plot the estimated treatment effect curve

Description

Plot the estimated overall or stage-wise restricted mean times in favor of treatment as a function of follow-up time.

Usage

## S3 method for class 'rmtfit'
plot(
  x,
  k = NULL,
  conf = FALSE,
  main = NULL,
  xlim = NULL,
  ylim = NULL,
  xlab = "Follow-up time",
  ylab = "Restricted mean time in favor",
  conf.col = "black",
  conf.lty = 3,
  ...
)

Arguments

x

An object returned by rmtfit.

k

If specified, \mu_k(\tau) is plotted; otherwise, \mu(\tau) is plotted.

conf

If TRUE, 95% confidence limits for the target curve are overlaid.

main

A main title for the plot

xlim

The x limits of the plot.

ylim

The y limits of the plot.

xlab

A label for the x axis, defaults to a description of x.

ylab

A label for the y axis, defaults to a description of y.

conf.col

Color for the confidence limits if conf=TRUE.

conf.lty

Line type for the confidence limits if conf=TRUE.

...

Other arguments that can be passed to the underlying plot method.

Value

No return value, called for side effects.

Examples

# load the colon cancer trial data
library(rmt)
head(colon_lev)
# fit the data
obj=rmtfit(ms(id,time,status)~rx,data=colon_lev)
# plot overal effect mu(tau)
plot(obj)
# set-up plot parameters
oldpar <- par(mfrow = par("mfrow"))
par(mfrow=c(1,2))
# Plot of component-wise RMT in favor of treatment over time
plot(obj,k=2,conf=TRUE,col='red',conf.col='blue', xlab="Follow-up time (years)",
    ylab="RMT in favor of treatment (years)",main="Survival")
plot(obj,k=1,conf=TRUE,col='red',conf.col='blue', xlab="Follow-up time (years)",
    ylab="RMT in favor of treatment (years)",main="Pre-relapse")
par(oldpar)

Print a short summary of rmtfit objects

Description

Print the results for the restricted mean times in favor of treatment.

Usage

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

Arguments

x

An object returned by rmtfit.

...

Further arguments passed to or from other methods

Value

No return value, called for side effects.

Print method for summary.rmtfit objects

Description

Produces a printed summary of the results for the restricted mean times in favor of treatment

Usage

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

Arguments

x

An object returned by summary.rmtfit.

...

Further arguments passed to or from other methods

Value

No return value, called for side effects.

Create a recurrent event object

Description

Create a recurrent event object

Usage

rec(id, time, status)

Arguments

id

A vector of id variable.

time

A vector of follow-up times.

status

A vector of event type, 1 = recurrent event, 2 = death, and 0 = censoring;

Value

An object of class rec used as an argument for rmtfit.

Estimate restricted mean times in favor of treatment

Description

Estimate and make inference on the overall and component-wise restricted mean times in favor of treatment.

Usage

rmtfit(...)

## Default S3 method:
rmtfit(id, time, status, trt, type = "multistate", ...)

## S3 method for class 'formula'
rmtfit(formula, data, ...)

Arguments

...

Further arguments.

id

A vector of id variable.

time

A vector of follow-up times.

status

For type="multistate", k = entering into state k (K+1 represents death) and 0 = censoring; For type="recurrent", 1 = recurrent event, 2 = death, and 0 = censoring;

trt

A vector of binary variable for treatment group.

type

"multistate" = multistate data; "recurrent" = recurrent event data.

formula

A formula object. For multistate data, use ms(id,time,status)~trt; for recurrent event data, use rec(id,time,status)~trt.

data

A data frame, which contains the variables names in the formula.

Value

An object of class rmtfit. See rmtfit.object for details.

Methods (by class)

default: Default
formula: Formula

Examples

#######################
# Multistate outcome  #
#######################
# load the colon cancer trial data
library(rmt)
head(colon_lev)
# fit the data
obj=rmtfit(ms(id,time,status)~rx,data=colon_lev)
# print the event numbers by group
obj
# summarize the inference results for tau=7.5 years
summary(obj,tau=7.5)

############################
# Recurrent event outcome  #
############################
# load the HF-ACTION trial data
library(rmt)
head(hfaction)
# fit the data
obj=rmtfit(rec(patid,time,status)~trt_ab,data=hfaction)
# print the event numbers by group
obj
# summarize the inference results for tau=3.5 years
summary(obj,tau=3.5,Kmax=4) # aggregating results for recurrent-event
# frequency >=4.

Estimated restricted mean times in favor of treatment

Description

This class of objects is returned by the rmtfit class of functions. Objects of this class have methods for the functions print, summary, plot, and bouquet.

Value

t

A vector of follow-up times \tau.

mu

A matrix with K+2 rows; The kth row (k=1,\ldots, K) is \mu_k(\tau), the restricted mean time in favor of treatment on the kth state (or recurrent event); The (K+1)th row is the net restricted mean survival time; The last row is the overal effect \mu(\tau).

var

A matrix with K+2 rows containing the variance estimates for mu.

mu10, mu01

Matrices with K+1 rows; The kth row (k=1,\ldots, K) is the restricted mean win (mu10) and loss (mu01) times by the treatment on the kth state (or recurrent event); The (K+1)th row is that on the survival time.

...

Summary of the analysis results

Description

Summarize the overall and stage-wise inferential results for the restricted mean times in favor of treatment at a user-specified length of follow-up.

Usage

## S3 method for class 'rmtfit'
summary(object, tau = NULL, Kmax = NULL, ...)

Arguments

object

An object returned by rmtfit.

tau

A positive real number for the follow-up time; Default is the maximum event time in the data.

Kmax

A positive integer; If specified, the stage-wise estimates over Kmax,\ldots,K will be aggregated.

...

Additional arguments affecting the summary produced.

Value

An object of class summary.rmtfit with components

WL

A 2\times(K+2)-dimensional matrix; Each row contains the estimates for the stage-wise and overall restricted mean win times for each group.

tab

A (K+2)\times 4-dimensional matrix summarizing the inferential results for the stage-wise and overall restricted mean times in favor of treatment; Columns include Estimate, Std.Err, Z value, and Pr(>|z|).

...

Examples

#See examples for rmtfit().

Bouquet plot

Description

Usage

Arguments

Value

See Also

Examples

A dataset from a landmark colon cancer trial

Description

Usage

Format

References

A dataset from the HF-ACTION trial

Description

Usage

Format

References

Create a multistate event object

Description

Usage

Arguments

Value

Plot the estimated treatment effect curve

Description

Usage

Arguments

Value

See Also

Examples

Print a short summary of rmtfit objects

Description

Usage

Arguments

Value

Print method for summary.rmtfit objects

Description

Usage

Arguments

Value

Create a recurrent event object

Description

Usage

Arguments

Value

Estimate restricted mean times in favor of treatment

Description

Usage

Arguments

Value

Methods (by class)

See Also

Examples

Estimated restricted mean times in favor of treatment

Description

Value

See Also

Summary of the analysis results

Description

Usage

Arguments

Value

See Also

Examples