The GSgalgoR package provides a practical but straightforward callback mechanism for adapting different galgo() execution sections to final user needs. The GSgalgoR callbacks mechanism enables adding custom functions to change the galgo() function behavior by including minor modification to galgo’s workflow. A common application of the callback mechanism is to implement personalized reports, saving partial information during the evolution process or compute the execution time.
There are five possible points where the user can hook its own code inside galgo() execution process.
galgo() execution process. (i.e. when galgo() is about to start.)galgo() execution process. (i.e. when galgo() is about to finish. )Each one of the five possible hooks can be accessed through parameters with the *_callback* suffix in the galgo() function.
galgo(..., start_galgo_callback = callback_default,# `galgo()` is about to start. end_galgo_callback = callback_default, # `galgo()` is about to finish. start_gen_callback = callback_default, # At the beginning of each generation end_gen_callback = callback_default, # At the end of each generation report_callback = callback_default, # In the middle of the generation, # right after the new mating pool # have been created. ...)
A callback function definition can be any R function accepting six parameters.
-userdir: the directory (“character”) where the user can save information into local filesystem. -generation: the number (“integer”) of the current generation/iteration. -pop_pool: the data.frame containing the resulting solutions for current iteration. -pareto: the solutions found by galgo() accross all generations in the solution space -prob_matrix: the expression set (“matrix) where features are rows and samples distributed in columns. -current_time: The current time (an object of class”POSIXct").
The following callback function example prints the generation number and current time every two iterations
library(GSgalgoR) my_callback <- function(userdir = "", generation, pop_pool, pareto, prob_matrix, current_time) { # code starts here if (generation%%2 == 0) message(paste0("generation: ",generation, " current_time: ",current_time)) }
then, the my_callback() function needs to be assigned to some of the available hooks provided by the galgo(). An example of such assignment and the resulting output is provided in the two snippets below.
A reduced version of the TRANSBIG dataset is used to setup the expression and clinical information required for the galgo() function.
library(breastCancerTRANSBIG) data(transbig) train <- transbig rm(transbig) expression <- Biobase::exprs(train) clinical <- Biobase::pData(train) OS <- survival::Surv(time = clinical$t.rfs, event = clinical$e.rfs) # use a reduced dataset for the example expression <- expression[sample(1:nrow(expression), 100), ] # scale the expression matrix expression <- t(scale(t(expression)))
Then, the galgo() function is invoked and the recently defined function my_callback() is assigned to the report_callback hook-point.
# Running galgo GSgalgoR::galgo(generations = 6, population = 15, prob_matrix = expression, OS = OS, start_galgo_callback = GSgalgoR::callback_default, end_galgo_callback = GSgalgoR::callback_default, report_callback = my_callback, # call `my_callback()` in the mile # of each generation/iteration. start_gen_callback = GSgalgoR::callback_default, end_gen_callback = GSgalgoR::callback_default) #> Using CPU for computing pearson distance #> generation: 2 current_time: 2020-08-31 12:20:36 #> generation: 4 current_time: 2020-08-31 12:20:36 #> generation: 6 current_time: 2020-08-31 12:20:37 #> NULL
custom callback function
The following callback function save in a temporary directory the solutions obtained every five generation/iteration. A file the number of the generation and with a rda. extension will be left in a directory defined by the tempdir() function.
my_save_pop_callback <- function(userdir = "", generation, pop_pool, pareto, prob_matrix, current_time) { directory <- paste0(tempdir(), "/") if (!dir.exists(directory)) { dir.create(directory, recursive = TRUE) } filename <- paste0(directory, generation, ".rda") if (generation%%2 == 0){ save(file = filename, pop_pool) } message(paste("solution file saved in",filename)) }
As usual, the galgo() function is invoked and the recently defined function my_save_pop_callback() is assigned to the end_gen_callback hook-point. As a result, every five generation/iteration the complete solution obtained by galgo will be saved in a file.
# Running galgo GSgalgoR::galgo( generations = 6, population = 15, prob_matrix = expression, OS = OS, start_galgo_callback = GSgalgoR::callback_default, end_galgo_callback = GSgalgoR::callback_default, report_callback = my_callback,# call `my_callback()` # in the middle of each generation/iteration. start_gen_callback = GSgalgoR::callback_default, end_gen_callback = my_save_pop_callback # call `my_save_pop_callback()` # at the end of each # generation/iteration ) #> Using CPU for computing pearson distance #> solution file saved in /tmp/RtmpddOpEu/1.rda #> generation: 2 current_time: 2020-08-31 12:20:39 #> solution file saved in /tmp/RtmpddOpEu/2.rda #> solution file saved in /tmp/RtmpddOpEu/3.rda #> generation: 4 current_time: 2020-08-31 12:20:40 #> solution file saved in /tmp/RtmpddOpEu/4.rda #> solution file saved in /tmp/RtmpddOpEu/5.rda #> generation: 6 current_time: 2020-08-31 12:20:41 #> solution file saved in /tmp/RtmpddOpEu/6.rda #> NULL
By default, GSfalgoR implements four callback functions
callback_default() a simple callback that does nothing at all. It is just used for setting the default behavior of some of the hook-points inside galgo() callback_base_report() a report callback for printing basic information about the solution provided by galgo() such as fitness and crowding distance. callback_no_report() a report callback for informing the user galgo is running. Not valuable information is shown. callback_base_return_pop() a callback function for building and returning t he galgo.Obj object.
In the the default definition of the galgo() function the hook-points are defined as follow:
-start_galgo_callback = callback_default -end_galgo_callback = callback_base_return_pop -report_callback = callback_base_report -start_gen_callback = callback_default -end_gen_callback = callback_default
Notice by using the callback mechanism it is possible to modify even the returning value of the galgo() function. The default callback_base_return_pop() returns a galgo.Obj object, however it would simple to change that behavior for something like the my_save_pop_callback() and the function will not returning any value.
# Running galgo GSgalgoR::galgo( generations = 6, population = 15, prob_matrix = expression, OS = OS, start_galgo_callback = GSgalgoR::callback_default, end_galgo_callback = my_save_pop_callback, report_callback = my_callback, # call `my_callback()` # in the middle of each generation/iteration start_gen_callback = GSgalgoR::callback_default, end_gen_callback = GSgalgoR::callback_default ) #> Using CPU for computing pearson distance #> generation: 2 current_time: 2020-08-31 12:20:43 #> generation: 4 current_time: 2020-08-31 12:20:44 #> generation: 6 current_time: 2020-08-31 12:20:45 #> solution file saved in /tmp/RtmpddOpEu/6.rda
For preserving the return behavior of the galgo() function,callback_base_return_pop() should be called inside a custom callback. An example of such situation is shown below:
library(GSgalgoR) another_callback <- function(userdir = "", generation, pop_pool, pareto, prob_matrix, current_time) { # code starts here # code ends here callback_base_return_pop(userdir, generation, pop_pool, prob_matrix, current_time) }
sessionInfo() #> R version 4.0.0 (2020-04-24) #> Platform: x86_64-pc-linux-gnu (64-bit) #> Running under: Ubuntu 18.04.4 LTS #> #> Matrix products: default #> BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.7.1 #> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.7.1 #> #> locale: #> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C #> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8 #> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 #> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C #> [9] LC_ADDRESS=C LC_TELEPHONE=C #> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C #> #> attached base packages: #> [1] stats graphics grDevices utils datasets methods base #> #> other attached packages: #> [1] breastCancerTRANSBIG_1.27.0 GSgalgoR_0.99.0 #> [3] BiocStyle_2.17.0 #> #> loaded via a namespace (and not attached): #> [1] Rcpp_1.0.4.6 compiler_4.0.0 BiocManager_1.30.10 #> [4] nsga2R_1.0 iterators_1.0.12 tools_4.0.0 #> [7] digest_0.6.25 evaluate_0.14 memoise_1.1.0 #> [10] lattice_0.20-41 rlang_0.4.6 Matrix_1.2-18 #> [13] foreach_1.5.0 rstudioapi_0.11 yaml_2.2.1 #> [16] parallel_4.0.0 pkgdown_1.5.1 xfun_0.14 #> [19] stringr_1.4.0 knitr_1.28 desc_1.2.0 #> [22] fs_1.4.1 rprojroot_1.3-2 grid_4.0.0 #> [25] Biobase_2.49.0 R6_2.4.1 survival_3.1-12 #> [28] rmarkdown_2.2 bookdown_0.19 magrittr_1.5 #> [31] backports_1.1.7 codetools_0.2-16 htmltools_0.4.0 #> [34] MASS_7.3-51.6 BiocGenerics_0.35.4 splines_4.0.0 #> [37] assertthat_0.2.1 stringi_1.4.6 doParallel_1.0.15 #> [40] crayon_1.3.4