Author: Shixiang Wang SYSUCC
Date: 2023-05-08

# ezcox: Easily Process a Batch of Cox Models

#### Shixiang Wang SYSUCC

#### 2023-05-08

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 with:

    install.packages("ezcox")

And the development version from GitHub with:

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

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

    remotes::install_github("ShixiangWang/forestmodel")

## Example

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

    library(survival)
    library(ezcox)
    #> Welcome to 'ezcox' package!
    #> =======================================================================
    #> You are using ezcox version 1.0.4
    #>
    #> Project home : https://github.com/ShixiangWang/ezcox
    #> Documentation: https://shixiangwang.github.io/ezcox
    #> Cite as      : arXiv:2110.14232
    #> =======================================================================
    #>
    data(lung)
    #> Warning in data(lung): data set 'lung' not found
    head(lung)
    #>   inst time status age sex ph.ecog ph.karno pat.karno meal.cal wt.loss
    #> 1    3  306      2  74   1       1       90       100     1175      NA
    #> 2    3  455      2  68   1       0       90        90     1225      15
    #> 3    3 1010      1  56   1       0       90        90       NA      15
    #> 4    5  210      2  57   1       1       90        60     1150      11
    #> 5    1  883      2  60   1       0      100        90       NA       0
    #> 6   12 1022      1  74   1       1       50        80      513       0

    # Build unvariable models
    ezcox(lung, covariates = c("age", "sex", "ph.ecog"))
    #> => Processing variable age
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> => Processing variable sex
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> => Processing variable ph.ecog
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> # A tibble: 3 × 12
    #>   Variable is_cont…¹ contr…² ref_l…³ n_con…⁴ n_ref    beta    HR lower…⁵ upper…⁶
    #>   <chr>    <lgl>     <chr>   <chr>     <int> <int>   <dbl> <dbl>   <dbl>   <dbl>
    #> 1 age      FALSE     age     age         228   228  0.0187 1.02    1       1.04
    #> 2 sex      FALSE     sex     sex         228   228 -0.531  0.588   0.424   0.816
    #> 3 ph.ecog  FALSE     ph.ecog ph.ecog     227   227  0.476  1.61    1.29    2.01
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​is_control, ²​contrast_level, ³​ref_level, ⁴​n_contrast,
    #> #   ⁵​lower_95, ⁶​upper_95

    # Build multi-variable models
    # Control variable 'age'
    ezcox(lung, covariates = c("sex", "ph.ecog"), controls = "age")
    #> => Processing variable sex
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> => Processing variable ph.ecog
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> # A tibble: 4 × 12
    #>   Variable is_cont…¹ contr…² ref_l…³ n_con…⁴ n_ref    beta    HR lower…⁵ upper…⁶
    #>   <chr>    <lgl>     <chr>   <chr>     <int> <int>   <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE     sex     sex         228   228 -0.513  0.599   0.431   0.831
    #> 2 sex      TRUE      age     age         228   228  0.017  1.02    0.999   1.04
    #> 3 ph.ecog  FALSE     ph.ecog ph.ecog     227   227  0.443  1.56    1.24    1.96
    #> 4 ph.ecog  TRUE      age     age         228   228  0.0113 1.01    0.993   1.03
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​is_control, ²​contrast_level, ³​ref_level, ⁴​n_contrast,
    #> #   ⁵​lower_95, ⁶​upper_95

## 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.

    ezcox_parallel(lung, covariates = c("sex", "ph.ecog"), controls = "age")
    #> Loading required namespace: furrr
    #> # A tibble: 4 × 12
    #>   Variable is_cont…¹ contr…² ref_l…³ n_con…⁴ n_ref    beta    HR lower…⁵ upper…⁶
    #>   <chr>    <lgl>     <chr>   <chr>     <int> <int>   <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE     sex     sex         228   228 -0.513  0.599   0.431   0.831
    #> 2 sex      TRUE      age     age         228   228  0.017  1.02    0.999   1.04
    #> 3 ph.ecog  FALSE     ph.ecog ph.ecog     227   227  0.443  1.56    1.24    1.96
    #> 4 ph.ecog  TRUE      age     age         228   228  0.0113 1.01    0.993   1.03
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​is_control, ²​contrast_level, ³​ref_level, ⁴​n_contrast,
    #> #   ⁵​lower_95, ⁶​upper_95

## Filter

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

    lung$ph.ecog = factor(lung$ph.ecog)
    zz = ezcox(lung, covariates = "sex", controls = "ph.ecog")
    #> => Processing variable sex
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.

    zz
    #> # A tibble: 4 × 12
    #>   Variable is_control contr…¹ ref_l…² n_con…³ n_ref   beta    HR lower…⁴ upper…⁵
    #>   <chr>    <lgl>      <chr>   <chr>     <dbl> <dbl>  <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE      sex     sex         228   228 -0.545  0.58   0.417   0.806
    #> 2 sex      TRUE       1       0           113    63  0.418  1.52   1.03    2.25
    #> 3 sex      TRUE       2       0            50    63  0.947  2.58   1.66    4.01
    #> 4 sex      TRUE       3       0             1    63  2.05   7.76   1.04   58
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​contrast_level, ²​ref_level, ³​n_contrast, ⁴​lower_95,
    #> #   ⁵​upper_95

    # At default, it will drop all control variables
    filter_ezcox(zz)
    #> # A tibble: 1 × 12
    #>   Variable is_control contr…¹ ref_l…² n_con…³ n_ref   beta    HR lower…⁴ upper…⁵
    #>   <chr>    <lgl>      <chr>   <chr>     <dbl> <dbl>  <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE      sex     sex         228   228 -0.545  0.58   0.417   0.806
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​contrast_level, ²​ref_level, ³​n_contrast, ⁴​lower_95,
    #> #   ⁵​upper_95

    # You can specify levels to filter out
    filter_ezcox(zz, c("0", "2"))
    #> Filtering control levels in 'both' mode:
    #>  0, 2
    #> # A tibble: 1 × 12
    #>   Variable is_control contr…¹ ref_l…² n_con…³ n_ref   beta    HR lower…⁴ upper…⁵
    #>   <chr>    <lgl>      <chr>   <chr>     <dbl> <dbl>  <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE      sex     sex         228   228 -0.545  0.58   0.417   0.806
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​contrast_level, ²​ref_level, ³​n_contrast, ⁴​lower_95,
    #> #   ⁵​upper_95
    filter_ezcox(zz, c("0", "2"), type = "contrast")
    #> Filtering control levels in 'contrast' mode:
    #>  0, 2
    #> # A tibble: 3 × 12
    #>   Variable is_control contr…¹ ref_l…² n_con…³ n_ref   beta    HR lower…⁴ upper…⁵
    #>   <chr>    <lgl>      <chr>   <chr>     <dbl> <dbl>  <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE      sex     sex         228   228 -0.545  0.58   0.417   0.806
    #> 2 sex      TRUE       1       0           113    63  0.418  1.52   1.03    2.25
    #> 3 sex      TRUE       3       0             1    63  2.05   7.76   1.04   58
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​contrast_level, ²​ref_level, ³​n_contrast, ⁴​lower_95,
    #> #   ⁵​upper_95
    filter_ezcox(zz, c("0", "2"), type = "ref")
    #> Filtering control levels in 'ref' mode:
    #>  0, 2
    #> # A tibble: 1 × 12
    #>   Variable is_control contr…¹ ref_l…² n_con…³ n_ref   beta    HR lower…⁴ upper…⁵
    #>   <chr>    <lgl>      <chr>   <chr>     <dbl> <dbl>  <dbl> <dbl>   <dbl>   <dbl>
    #> 1 sex      FALSE      sex     sex         228   228 -0.545  0.58   0.417   0.806
    #> # … with 2 more variables: p.value <dbl>, global.pval <dbl>, and abbreviated
    #> #   variable names ¹​contrast_level, ²​ref_level, ³​n_contrast, ⁴​lower_95,
    #> #   ⁵​upper_95

    # More see ?filter_ezcox

## Get models

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

    zz = ezcox(lung, covariates = c("sex", "ph.ecog"), controls = "age", return_models=TRUE)
    #> => Processing variable sex
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    #> => Processing variable ph.ecog
    #> ==> Building Surv object...
    #> ==> Building Cox model...
    #> ==> Done.
    mds = get_models(zz)
    str(mds, max.level = 1)
    #> List of 2
    #>  $ Surv ~ sex + age    :List of 19
    #>   ..- attr(*, "class")= chr "coxph"
    #>   ..- attr(*, "Variable")= chr "sex"
    #>  $ Surv ~ ph.ecog + age:List of 22
    #>   ..- attr(*, "class")= chr "coxph"
    #>   ..- attr(*, "Variable")= chr "ph.ecog"
    #>  - attr(*, "class")= chr [1:2] "ezcox_models" "list"
    #>  - attr(*, "has_control")= logi TRUE

## Show models

    show_models(mds)
    #> Warning in recalculate_width_panels(panel_positions, mapped_text =
    #> mapped_text, : Unable to resize forest panel to be smaller than its heading;
    #> consider a smaller text size

    # Set model names
    show_models(mds, model_names = paste0("Model ", 1:2))
    #> Warning in recalculate_width_panels(panel_positions, mapped_text =
    #> mapped_text, : Unable to resize forest panel to be smaller than its heading;
    #> consider a smaller text size

    # Merge all models and drop control variables
    show_models(mds, merge_models = TRUE, drop_controls = TRUE)
    #> covariates=NULL but drop_controls=TRUE, detecting controls...
    #> Yes. Setting variables to keep...
    #> Done.
    #> Warning in recalculate_width_panels(panel_positions, mapped_text =
    #> mapped_text, : Unable to resize forest panel to be smaller than its heading;
    #> consider a smaller text size

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