ezcox: Easily Process a Batch of Cox Models

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(ezcox)
#> Welcome to 'ezcox' package!
#> =======================================================================
#> You are using ezcox version 0.4.0
#> 
#> Github page  : https://github.com/ShixiangWang/ezcox
#> Documentation: https://shixiangwang.github.io/ezcox/articles/ezcox.html
#> 
#> Run citation("ezcox") to see how to cite 'ezcox'.
#> =======================================================================
#> 
data("lung", package = "survival")

# 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 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref    beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <int> <int>   <dbl> <dbl>
#> 1 age      FALSE      age            age              228   228  0.0187 1.02 
#> 2 sex      FALSE      sex            sex              228   228 -0.531  0.588
#> 3 ph.ecog  FALSE      ph.ecog        ph.ecog          227   227  0.476  1.61 
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

# 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 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref    beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <int> <int>   <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.513  0.599
#> 2 sex      TRUE       age            age              228   228  0.017  1.02 
#> 3 ph.ecog  FALSE      ph.ecog        ph.ecog          227   227  0.443  1.56 
#> 4 ph.ecog  TRUE       age            age              228   228  0.0113 1.01 
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

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
#> Warning: [ONE-TIME WARNING] Forked processing ('multicore') is disabled
#> in future (>= 1.13.0) when running R from RStudio, because it is
#> considered unstable. Because of this, plan("multicore") will fall
#> back to plan("sequential"), and plan("multiprocess") will fall back to
#> plan("multisession") - not plan("multicore") as in the past. For more details,
#> how to control forked processing or not, and how to silence this warning in
#> future R sessions, see ?future::supportsMulticore
#> # A tibble: 4 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref    beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <int> <int>   <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.513  0.599
#> 2 sex      TRUE       age            age              228   228  0.017  1.02 
#> 3 ph.ecog  FALSE      ph.ecog        ph.ecog          227   227  0.443  1.56 
#> 4 ph.ecog  TRUE       age            age              228   228  0.0113 1.01 
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

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 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref   beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <dbl> <dbl>  <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.545 0.580
#> 2 sex      TRUE       1              0                113    63  0.418 1.52 
#> 3 sex      TRUE       2              0                 50    63  0.947 2.58 
#> 4 sex      TRUE       3              0                  1    63  2.05  7.76 
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

# At default, it will drop all control variables
filter_ezcox(zz)
#> # A tibble: 1 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref   beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <dbl> <dbl>  <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.545 0.580
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

# You can specify levels to filter out
filter_ezcox(zz, c("0", "2"))
#> Filtering control levels in 'both' mode:
#>  0, 2
#> # A tibble: 1 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref   beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <dbl> <dbl>  <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.545 0.580
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>
filter_ezcox(zz, c("0", "2"), type = "contrast")
#> Filtering control levels in 'contrast' mode:
#>  0, 2
#> # A tibble: 3 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref   beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <dbl> <dbl>  <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.545 0.580
#> 2 sex      TRUE       1              0                113    63  0.418 1.52 
#> 3 sex      TRUE       3              0                  1    63  2.05  7.76 
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>
filter_ezcox(zz, c("0", "2"), type = "ref")
#> Filtering control levels in 'ref' mode:
#>  0, 2
#> # A tibble: 1 x 12
#>   Variable is_control contrast_level ref_level n_contrast n_ref   beta    HR
#>   <chr>    <lgl>      <chr>          <chr>          <dbl> <dbl>  <dbl> <dbl>
#> 1 sex      FALSE      sex            sex              228   228 -0.545 0.580
#> # … with 4 more variables: lower_95 <dbl>, upper_95 <dbl>, p.value <dbl>,
#> #   global.pval <dbl>

# 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

• Wang, Shixiang, et al. “The predictive power of tumor mutational burden in lung cancer immunotherapy response is influenced by patients’ sex.” International journal of cancer (2019).