README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# iwillsurvive `r packageVersion("iwillsurvive")` <img src="https://raw.githubusercontent.com/ndphillips/iwillsurvive/master/inst/figures/iwillsurvive_hex.png" align="right" height="139"/>

<!-- badges: start -->
[![R build status](https://github.com/ndphillips/iwillsurvive/workflows/R-CMD-check/badge.svg)](https://github.com/ndphillips/iwillsurvive/actions)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental)
[![Codecov test coverage](https://codecov.io/gh/ndphillips/iwillsurvive/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ndphillips/iwillsurvive?branch=master)
[![Codename: shuffled](https://img.shields.io/badge/version-0.1_'Gloria'-yellow.svg)](https://en.wikipedia.org/wiki/Gloria_Gaynor)
  <!-- badges: end -->


The goal of `iwillsurvive` is to make it easy to estimate and visualize simple 
survival models. It does this by providing an intuitive functional interface and
user-friendly in-line messages, notes, and warnings, while leveraging the 
gold-standard `survival` package for all statistical methods.

## Installation

`iwillsurvive` is hosted at https://github.com/ndphillips/iwillsurvive. Here is 
how to install it:

```{r, echo = TRUE, eval = FALSE}
devtools::install_github(
  repo = "https://github.com/ndphillips/iwillsurvive",
  build_vignettes = TRUE
)
```

## Example

```{r example, message = FALSE, results = "hide"}
library(iwillsurvive)
library(dplyr)
```

I'll now give a very brief overview of the basic survival model that `iwillsurvive` works with. For a more thorough and informative discussion, check out [Emily C. Zabor's Survival Analysis in R](https://www.emilyzabor.com/tutorials/survival_analysis_in_r_tutorial.html). It's awesome.

### Raw data

We'll start with the `cohort_raw` dataset which represents the results of a (fictional) clinical trial testing the effectiveness of a drug in extending survival from a patient's first line of therapy start date.

Here are the first 8 patients:

```{r, echo = FALSE}
cohort_raw %>%
  slice(1:8) %>%
  knitr::kable()
```

Here's what the key columns mean:

|Column|Definition|
|:-----|:---------|
|`patientid`|A character referring to an individual patient in the form "FXXXXX"|
|`condition`|A character indicating which condition the patient was in, unique values are: `r paste(unique(cohort_raw$condition), collapse = ", ")`|
|`lotstartdate`|A date indicating when a patient started their first line of therapy after diagnosis (will be used as the *index date*)|
|`lastvisitdate`|A date indicating the last known date that a patient was alive (will be used as the *censor date*)|
|`dateofdeath`|A date indicating the date of death of patients who died during the study period (will be used as the *event date*)|

### Research Question

Below is our main research question:

> What is the difference in median survival from lot1start to
 death (or censor) for patients in the placebo versus drug condition?

### Survival data

Before we can estimate the survival model, we need to define some key columns:

|Variable|Definition|
|:----|:-----|
|`followup_date`|The date at which the event occurs (if known), otherwise the last date the patient was known to be alive|
|`followup_days`|The number of days from indexdate to `followupdate`|
|`eventstatus`|A logical column indicating whether or not the patient died. TRUE = Yes, FALSE = No.

To calculate these variables, we can use `iwillsurvive`'s *derive* functions:
Use the `derive_*()` functions to calculate key derived columns:

* `followup_date`: `dateofdeath`, if known, and `censordate`, otherwise
* `followup_days`: Days from `index_date` (in our case, `lotstartdate`) to 
`followup_date`
* `event_status`: A logical column indicating whether or not the event 
(`dateofdeath`) is known.

```{r}
cohort <- cohort_raw %>%
  derive_followup_date(
    event_date = "dateofdeath",
    censor_date = "lastvisitdate"
  ) %>%
  derive_followup_time(index_date = "lotstartdate") %>%
  derive_event_status(event_date = "dateofdeath")
```

Here's how the new columns look for the first 8 patients:

```{r, echo = FALSE}
cohort %>%
  select(patientid, followup_date:event_status) %>%
  slice(1:8) %>%
  knitr::kable()
```


### Fitting survival models

Use `iwillsurvive()` to fit the survival model. We'll set the follow up time to
be `followup_days` and specify "condition" as a term (i.e.; covariate) to be 
used in the model.

<!-- * Note: If we were using `survival::survfit()` we'd need to specify this nasty  -->
<!-- looking formula `survival::survfit(survival::Surv(followup_days, event_status,  -->
<!-- type = 'right') ~ group, data = cohort)` ddirectly, With `iwillsurvive()`, we can  -->
<!-- simply specify the column names of interest and let the function take care of  -->
<!-- the formula -->

```{r}
cohort_iws <- iwillsurvive(cohort,
  followup_time = "followup_days",
  terms = "condition",
  event_title = "Death",
  index_title = "LOT1 Start"
)
```

#### print method

Print the object to see summary information:

```{r, eval = FALSE}
cohort_iws
```

```{r, echo = FALSE, out.width="60%"}
knitr::include_graphics("https://raw.githubusercontent.com/ndphillips/iwillsurvive/master/inst/figures/print_iwillsurvive.png")
```

#### Plotting followup times


Use `plot_followup()` to visualize the observed follow-up times for each patient 
ordered by the length of their follow-up and colored by their event status (not
 by condition)

```{r, fig.width = 7, fig.height = 5.5, out.width = "100%"}
plot_followup(cohort_iws)
```

#### Plotting Kaplan-Meier curves (the plot method)

Use `plot()` to plot the Kaplan-Meier survival curve. If you don't include any 
arguments, you'll get the 'default' curve options.

```{r, fig.width = 7, fig.height = 5.5, out.width = "100%", warning = FALSE}
plot(cohort_iws)
```

You can fully customize the look of your Kaplan-Meier curve (see 
`?plot.iwillsurvive`) to see all the optional arguments:

```{r}
plot(cohort_iws,
  add_confidence = FALSE,
  add_median_delta = FALSE,
  censor_pch = 3,
  censor_size = 5,
  legend_position_x = c(600, 400),
  legend_nudge_y = c(.25, .3),
  median_flag_nudge_y = .15,
  anchor_arrow = TRUE,
  palette = "Dark2",
  title = "My Title",
  subtitle = "My Subttitle",
  risk_table_title = "My Risk Table Title"
)
```

### Understanding iwillsurvive objects

The `iwillsurvive()` function returns an object of class `iwillsurvive`. 
Internally, it is a list containing many objects from the original data, to a 
`survival` object:

```{r}
names(cohort_iws)
```

The `.$data` object contains the original data

```{r}
cohort_iws$data
```

The `.$fit` object contains the `survival` object (created using the 
`survival::survfit()` function)

```{r}
cohort_iws$fit
```

The `.$fit_summary` object contains summary information:

```{r}
cohort_iws$fit_summary
```

### iwillsurvive and the survival package

`iwillsurvive` uses the `survival` package under the hood for all model estimation. 
For that reason, you should always be able to get the 'same result' using the
 `survival` package as you would using the `iwillsurvive` package.
 
For example, here's how to directly replicate the same result we got using 
 `survival`:

```{r}
library(survival)

# Fit the model
fit_survival <- survival::survfit(
  survival::Surv(followup_days, event_status,
    type = "right"
  ) ~ condition,
  data = cohort
)

# Print method
fit_survival
```