---
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()
```

