---
title: "GSgalgoR Callbacks Mechanism"
output:
BiocStyle::html_document
vignette: >
%\VignetteIndexEntry{GSgalgoR Callbacks Mechanism}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
# Introduction
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.
* At the beginning of the `galgo()` execution process. (i.e. when `galgo()`
is about to start.)
* At the end of the `galgo()` execution process. (i.e. when `galgo()` is about
to finish. )
* At the beginning of the evolution process. (i.e. at the beginning of each
generation/iteration. )
* At the end of the evolution process.
(i.e. at the end of each generation/iteration.)
* In the middle of the evolution process. (i.e. in the middle of the
generation, right after the new mating pool have been created.)
Each one of the five possible hooks can be accessed through parameters
with the *_callback* suffix in the `galgo()` function.
```{r eval=FALSE }
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.
...)
```
# Example 1: A simple custom callback function definition
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
```{r}
library(GSgalgoR)
```
```{r}
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](bioconductor.org/packages/release/data/experiment/html/breastCancerTRANSBIG.html)
dataset is used to setup the expression and clinical information
required for the `galgo()` function.
```{r message=FALSE}
library(breastCancerTRANSBIG)
```
```{r}
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.
```{r message=FALSE}
library(GSgalgoR)
```
```{r}
# 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)
```
# Example 2: Saving partial population pool using 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.
```{r}
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.
```{r}
# 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
)
```
# Callbacks implemented in GSgalgoR
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.
```{r}
# 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
)
```
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:
```{r eval=FALSE}
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)
}
```
# Session info
```{r sess_info, eval=TRUE}
sessionInfo()
```