cmprsk2.Rmd

<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{cmprsk2 intro}
-->

## Subdistribution Analysis of Competing Risks
 
* [intro](#intro)  
* [design](#design)  
* [examples](#examples)  
* [install](#install)  

```{r, message=FALSE}
library('cmprsk2')
library('htmlTable')
```

## intro

Extensions to the **`cmprsk`** package:

1. estimation, testing, and regression modeling of subdistribution functions in competing risks, as described in Gray (1988);

1. A class of K-sample tests for comparing the cumulative incidence of a competing risk, Ann. Stat. 16:1141-1154, and Fine JP and Gray RJ (1999); and

1. A proportional hazards model for the subdistribution of a competing risk, JASA, 94:496-509.
 
## design

The two main package functions, `cuminc2` and `crr2`, provide a convenient formula-interface to `cmprsk::cuminc` and `cmprsk::crr` to users who are familiar with using survival objects in the **`survival`** package.

The syntax for creating survival objects is

$$Surv(time, status) \sim rhs$$
Similarly, the syntax for creating **`cmprsk`** objects is

$$Surv(time, status(censor) == event) \sim rhs$$
where `status` is a categorical variable with censoring indicators, usually "0", "Censor", "Censored", etc., and two or more unique event indicators for each competing risk. `event` in the formula will be one of the event indicators found in `status` and will be considered the primary event of interest.

## examples

### cumulative incidence

Note in the formula that it is not necessary to specify the event of interest for `cuminc2`.

```{r}
ci <- cuminc2(Surv(futime, event(censored)) ~ sex, transplant)
summary(ci)

cmprsk::timepoints(ci$cuminc, times = 0:4 * 500)
cmprsk2::timepoints2(ci)
cmprsk2::timepoints2(
  ci, sd = TRUE, html = TRUE,
  htmlArgs = list(caption = 'Table 1: Timepoints.')
)

plot(ci)

ci <- cuminc2(Surv(futime, event(censored)) ~ abo, transplant)
cuminc_pairs(ci)$p.value

plot(ci, split = 'event')
```

### competing risks regression

While it is necessary to specify the event of interest in the `crr2` formula, this will be the _primary_ event of interest. That is, by default models are fit for all competing events, but the primary event model will be listed first.

Using `crr2(..., which = event)` will only fit model(s) for `event`.

```{r}
cr <- crr2(Surv(futime, event(censored) == death) ~ sex, transplant)
summary(cr)


cr <- crr2(Surv(futime, event(censored) == death) ~ sex + abo, transplant)
summary(cr, n = TRUE, ref = TRUE)


cr <- crr2(Surv(futime, event(censored) == ltx) ~ sex + abo, transplant,
           cox = Surv(futime, event == 'death') ~ sex + abo)
summary(
  cr, html = TRUE, n = TRUE, ref = TRUE,
  htmlArgs = list(
    caption = 'Table 1: Competing risks.',
    rnames = with(transplant, c(levels(sex), levels(abo)))
  )
)


cr <- crr2(Surv(futime, event(censored) == ltx) ~ sex + abo, transplant,
           which = 'ltx')
summary(
  cr, html = TRUE, n = TRUE,
  htmlArgs = list(
    caption = 'Table 1: Competing risks.',
    tfoot = '<font size=1>Reference groups: Sex, male; blood type, A.</font>',
    rgroup = c('Sex', 'Blood type'),
    rnames = c('Female', paste('Type:', c('B', 'AB', 'O')))
  )
)
```

## install

```{r, eval=FALSE}
# install.packages('devtools')
devtools::install_github('raredd/cmprsk2', build_vignettes = TRUE)
```

## session

```{r, eval=TRUE}
utils::sessionInfo()
```