tune_penCSC {CSCNet} | R Documentation |

## tune_penCSC

### Description

A flexible function for tuning the involved hyper-parameters of a penalized cause-specific-cox model with elastic net penalty using the linking idea.

### Usage

```
tune_penCSC(
time,
status,
vars.list,
data,
horizons,
event,
rhs = ~1,
method = "cv",
k = 10,
times = 25,
p = 0.7,
strat.var = NULL,
metrics = "Brier",
final.metric = NULL,
alpha.grid = NULL,
lambda.grid = NULL,
nlambdas.list = NULL,
grow.by = 0.01,
standardize = TRUE,
keep = NULL,
preProc.fun = function(x) x,
preProc.fun.test = NULL,
parallel = FALSE,
preProc.pkgs = NULL,
preProc.globals = NULL,
core.nums = future::availableCores()/2
)
```

### Arguments

`time` |
A character showing the name of the time variable in the data. |

`status` |
A character showing the name of the status/event variable in the data. |

`vars.list` |
A named list containing the variables to be included in each cause-specific model. Variables can be vectors of variable names or a one sided formula. Names of the list must be the events and exactly the same as values in the status variable. See 'Examples' for details. |

`data` |
A data frame containing the information of the variables. |

`horizons` |
A vector of time horizons which we want the absolute risk predictions to be evaluated at. |

`event` |
The value for event of interest which we want the absolute risk predictions to be evaluated for. This must be one of the values in the status variable of the data. |

`rhs` |
A right hand sided formula indicating the variables to be used in estimating the inverse probability of censoring weighting (IPCW) model. Default is |

`method` |
Resampling method to be used for hyper-parameter tuning. Values can be: |

`k` |
Number of folds. Only applicable for |

`times` |
Repeat number of the resampling process. Only applicable for |

`p` |
The fraction of data to be used as the training set during resampling. Only applicable for |

`strat.var` |
A single character indicating name of the strata variable to be used to create resamples. If numerical, groups will be specified based on percentiles. Default is |

`metrics` |
Evaluation metric (loss function) to be used. Values can be |

`final.metric` |
The evaluation metric to decide the best hyper-parameters set for the final fits on the whole data. When |

`alpha.grid` |
A named list containing a sequence of alpha values to be evaluated for each cause-specific model. Names of the list must be the events and exactly the same as values in the status variable. Default is |

`lambda.grid` |
A named list containing a sequence of lambda values to be evaluated for each cause-specific model. Names of the list must be the events and exactly the same as values in the status variable. Default is |

`nlambdas.list` |
A names list of single integers indicating the length of lambda sequences which are calculated automatically by the function for each cause. Only applicable when |

`grow.by` |
Difference between the values in the growing sequence of lambda values to find the maximum value that makes the null model. Only applicable when |

`standardize` |
Logical indicating whether the variables must be standardized or not during model fitting procedures. Default is |

`keep` |
A character vector of the names of variables that should not be shrunk in all model fitting procedures. Default is |

`preProc.fun` |
A function that accepts a data and returns a modified version of it that has gone through the user's desired pre-processing steps. All modifications from this function will be done during the resampling procedures to avoid data leakage. It will modify all training and test set(s) during the validation unless other argument |

`preProc.fun.test` |
A function the exact same characteristics and description as |

`parallel` |
Logical indicating whether the tuning process should be performed in parallel or not. Default is |

`preProc.pkgs` |
A character vector containing the names of packages that was used in creating user's |

`preProc.globals` |
A character vector containing names of objects included in |

`core.nums` |
Number of CPU cores to be used for parallel computation. Only applicable if |

### Details

`tune_penCSC`

has the ability to automatically determine the candidate sequences of alpha & lambda values. Setting any of `alpha.grid`

& `lambda.grid`

to `NULL`

will order the function to calculate them automatically.
The process of determining the lambda values automatically is by:

Starting from lambda=0, the algorithm fits LASSO models until finding a lambda value that creates a NULL model where all variables were shrunk to be exactly zero.

The obtained lambda value will be used as the maximum value of a sequence starting from 0. The length of this sequence is controlled by values in

`nlambdas.list`

.

This will be done for each cause-specific model to create exclusive sequences of lambdas for each of them.

### Value

A list containing the detailed information of the hyper-parameter tuning and the validation process, best combination of hyper-parameters and the final fits based on the whole data using the best obtained hyper-parameters. Use `$`

to explore all the involved information.

### Author(s)

Shahin Roshani

### References

Friedman J, Hastie T, Tibshirani R (2010). "Regularization Paths for Generalized Linear Models via Coordinate Descent." Journal of Statistical Software, 33(1), 1-22. doi:10.18637/jss.v033.i01, https://www.jstatsoft.org/v33/i01/.

Saadati, M, Beyersmann, J, Kopp-Schneider, A, Benner, A. Prediction accuracy and variable selection for penalized cause-specific hazards models. Biometrical Journal. 2018; 60: 288– 306. doi:10.1002/bimj.201600242.

Gerds TA, Kattan MW (2021). Medical Risk Prediction Models: With Ties to Machine Learning (1st ed.). Chapman and Hall/CRC. doi:10.1201/9781138384484

Pfeiffer, R. M., & Gail, M. M. (2017). Absolute risk: Methods and applications in clinical management and public health.

Kuhn, M. (2008). Building Predictive Models in R Using the caret Package. Journal of Statistical Software, 28(5), 1–26. doi:10.18637/jss.v028.i05.

Bengtsson H (2021). “A Unifying Framework for Parallel and Distributed Processing in R using Futures.” The R Journal, 13(2), 208–227. doi:10.32614/RJ-2021-048.

Vaughan D, Dancho M (2022). furrr: Apply Mapping Functions in Parallel using Futures. https://github.com/DavisVaughan/furrr, https://furrr.futureverse.org/.

Therneau T (2022). A Package for Survival Analysis in R. R package version 3.3-1, https://CRAN.R-project.org/package=survival.

Wickham H, Averick M, Bryan J, Chang W, McGowan L, François R, et al. Welcome to the tidyverse. J Open Source Softw. 2019 Nov 21;4(43):1686.

Bache S, Wickham H (2022). magrittr: A Forward-Pipe Operator for R. https://magrittr.tidyverse.org, https://github.com/tidyverse/magrittr.

### Examples

```
library(riskRegression)
data(Melanoma)
vl <- list('1'=~age+sex+epicel+ici,
'2'=c('age','ulcer','thick','invasion'))
al <- list('1'=0,'2'=c(.5,1))
#External standardization function with data frame as its input and output
library(recipes)
std.fun <- function(data){
cont_vars <- data %>% select(where(~is.numeric(.))) %>% names
cont_vars <- cont_vars[-which(cont_vars %in% c('time','status'))]
#External functions from recipes package are being used
recipe(~.,data=data) %>%
step_center(all_of(cont_vars)) %>%
step_scale(all_of(cont_vars)) %>%
prep(training=data) %>% juice
}
set.seed(233)
test <- tune_penCSC(time='time',status='status',vars.list=vl,data=Melanoma,horizons=1825,
event=1,method='cv',k=5,metrics='AUC',alpha.grid=al,standardize=FALSE,
preProc.fun=std.fun,parallel=TRUE,preProc.pkgs='recipes')
test
```

*CSCNet*version 0.1.2 Index]