ten: *t*ime, *e*vent(s) and *n*umber at risk.

Description Usage Arguments Value Note See Also Examples

Description

time, event(s) and number at risk.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
ten(x, ...)

## S3 method for class 'numeric'
ten(x, ...)

## S3 method for class 'Surv'
ten(x, ..., call = NULL)

## S3 method for class 'coxph'
ten(x, ..., abbNames = TRUE, contrasts.arg = NULL)

## S3 method for class 'survfit'
ten(x, ..., abbNames = TRUE, contrasts.arg = NULL)

## S3 method for class 'formula'
ten(x, ..., abbNames = TRUE, contrasts.arg = NULL)

## S3 method for class 'data.frame'
ten(x, ..., abbNames = TRUE, contrasts.arg = NULL,
  call = NULL)

## S3 method for class 'data.table'
ten(x, ..., abbNames = TRUE, mm = NULL, call = NULL)

## S3 method for class 'ten'
ten(x, ..., abbNames = NULL, call = NULL)

Arguments

x

For the default method, a numeric vector indicating an event (or status).
Each element indicates whether an event occurred (1) or not (0) for an observation.
These are assumed to be ordered by discrete times.
This is similar to the event argument for Surv objects.

Methods are available for objects of class Surv, survfit, coxph and formula.

abbNames

Abbreviate names?
If abbNames="TRUE" (the default), the covariate groups are referred to by number.
As the names for each covariate group are made by concatenating the predictor names, the full names can become unwieldly.
If abbNames="FALSE", the full names are given.
In either case, the longNames are given as an attribute of the returned ten object.

contrasts.arg

Methods for handling factors.
A list. The names are the names of columns of the model.frame containing factors.
The values are used as replacement values for the stats::contrasts replacement function. These should be functions (given as character strings) or numeric matrices.
This can be passed from survfit, coxph and formula objects to:
?stats::model.matrix

call

Used to pass the call from a formula to the final ten.data.table method.

mm

Used to pass the model.matrix from a formula to the final ten.data.table method.

...

Additional arguments (not implemented).

Value

A data.table with the additional class ten.
By default, the shape returned is 'long' i.e. there is one row for each unique timepoint per covariate group.
The basic form, for a numeric or Surv object, has columns:

t

time.

e

number of events.

n

number at risk.

A survfit, coxph or formula object will have additional columns:

cg

covariate group. This is formed by combining the variables; these are separated by a comma ','.

ncg

number at risk, by covariate group

Special terms.

The following are considered 'special' terms in a survival model:

strata

For a stratified model, ten returns a list with one element per strata, which is a ten object.
This has the class stratTen. The name of the list elements are those of the strata in the model.

cluster

These terms are dropped.

tt

The variable is unchanged. That is, time-transform terms are handled as if the the function tt(x) was identity(x).

Attribures.
The returned object will also have the following attributes:

shape

The default is "long" but is changed to "wide" when asWide is called on the object.

abbNames

Abbreviate names?

longNames

A data.table with two columns, showing the abbrevbiated and full names.

ncg

Number of covariate groups

call

The call used to generate the object

mm

The model.matrix used to generate to generate the object, if applicable.

Additional attributes will be added by the following functions:
sf ci

Note

The methods for data.frame (for a model frame) and data.table are not typically intended for interactive use.

Currently only binary status and right-censoring are supported.

In stratified models, only one level of stratification is supported (i.e. strata cannot be 'nested' currently).

Partial matching is available for the following arguments, based on the characters in bold:

See Also

asWide

print

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
require("survival")
## binary vector
ten(c(1, 0, 1, 0, 1))
## Surv object
df0 <- data.frame(t=c(1, 1, 2, 3, 5, 8, 13, 21),
                  e=rep(c(0, 1), 4))
s1 <- with(df0, Surv(t, e, type="right"))
ten(s1)
## some awkward values
suppressWarnings(
    s1 <- Surv(time=c(Inf, -1, NaN, NA, 10, 12),
               event=c(c(NA, 1, 1, NaN, Inf, 0.75))))
ten(s1)
## coxph object
## K&M. Section 1.2. Table 1.1, page 2.
data("hodg", package="KMsurv")
hodg <- data.table::data.table(hodg)
data.table::setnames(hodg,
                     c(names(hodg)[!names(hodg) %in%
                                   c("score", "wtime")],
                       "Z1", "Z2"))
c1 <- coxph(Surv(time=time, event=delta) ~ Z1 + Z2,
            data=hodg[gtype==1 && dtype==1, ])
ten(c1)
data("bmt", package="KMsurv")
ten(c1 <- coxph(Surv(t2, d3) ~ z3*z10, data=bmt))
## T&G. Section 3.2, pg 47.
## stratified model
data("pbc", package="survival")
c1 <- coxph(Surv(time, status==2) ~ log(bili) + age + strata(edema), data=pbc)
ten(c1)
## K&M. Example 7.2, pg 210.
data("kidney", package="KMsurv")
with(kidney[kidney$type==2, ], ten(Surv(time=time, event=delta)))
s1 <- survfit(Surv(time=time, event=delta) ~ type, data=kidney)
ten(s1)[e > 0, ]
## A null model is passed to ten.Surv
(t1 <- with(kidney, ten(Surv(time=time, event=delta) ~ 0)))
## but the original call is preserved
attr(t1, "call")
## survival::survfit doesn't accept interaction terms...
## Not run: 
    s1 <- survfit(Surv(t2, d3) ~ z3*z10, data=bmt)
## End(Not run)
## but ten.formula does:
ten(Surv(time=t2, event=d3) ~ z3*z10, data=bmt)
## the same is true for the '.' (dot operator) in formulas
(t1 <- ten(Surv(time=t2, event=d3) ~ ., data=bmt))
## impractical long names stored as an attribute
attr(t1, "longNames")
## not typically intended to be called directly
mf1 <- model.frame(Surv(time, status==2) ~ age + strata(edema) + strata(spiders), pbc,
                   drop.unused.levels = TRUE)
ten(mf1)

dardisco/survMisc documentation built on May 14, 2019, 6:08 p.m.