---
title: "ezcox: Easily Process a Batch of Cox Models"
author: "Shixiang Wang \\
        SYSUCC"
date: "`r Sys.Date()`"
output:
  prettydoc::html_pretty:
    toc: true
    theme: cayman
    highlight: github
  pdf_document:
    toc: true
vignette: >
  %\VignetteIndexEntry{ezcox: Easily Process a Batch of Cox Models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The goal of ezcox is to operate a batch of univariate or multivariate Cox models and return tidy result.

## Installation

You can install the released version of ezcox from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("ezcox")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("ShixiangWang/ezcox")
```

Visualization feature of **ezcox** needs the recent version of **forestmodel**, please run the following commands:

```r
remotes::install_github("ShixiangWang/forestmodel")
```

## Example

This is a basic example which shows you how to get result from a batch of cox models.

```{r example}
library(survival)
library(ezcox)
data(lung)
head(lung)

# Build unvariable models
ezcox(lung, covariates = c("age", "sex", "ph.ecog"))

# Build multi-variable models
# Control variable 'age'
ezcox(lung, covariates = c("sex", "ph.ecog"), controls = "age")
```

## Run parallelly

For parallel computation, users can use `ezcox_parallel()`. This function has same arguments as `ezcox()`.
For variables < 200, this function is not recommended.

```{r}
ezcox_parallel(lung, covariates = c("sex", "ph.ecog"), controls = "age")
```


## Filter

Sometimes, we may need to filter result from multi-variable models.

```{r}
lung$ph.ecog = factor(lung$ph.ecog)
zz = ezcox(lung, covariates = "sex", controls = "ph.ecog")

zz

# At default, it will drop all control variables
filter_ezcox(zz)

# You can specify levels to filter out
filter_ezcox(zz, c("0", "2"))
filter_ezcox(zz, c("0", "2"), type = "contrast")
filter_ezcox(zz, c("0", "2"), type = "ref")

# More see ?filter_ezcox
```

## Get models

Get raw models may help users understand the detail and do further visualization.

```{r}
zz = ezcox(lung, covariates = c("sex", "ph.ecog"), controls = "age", return_models=TRUE)
mds = get_models(zz)
str(mds, max.level = 1)
```

## Show models

```{r, fig.height=5, fig.width=6}
show_models(mds)
# Set model names
show_models(mds, model_names = paste0("Model ", 1:2))
# Merge all models and drop control variables
show_models(mds, merge_models = TRUE, drop_controls = TRUE)
```

More see `?show_models`.

## Citation

- Shixiang Wang (2021). ezcox: Easily Process a Batch of Cox Models. R package version 1.0.0.
  https://github.com/ShixiangWang/ezcox