# GSgalgoR Callbacks Mechanism

# 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.

    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

    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.

    library(GSgalgoR)

    # 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: 2026-04-29 22:16:41.713708
    #> generation: 4 current_time: 2026-04-29 22:16:42.555733
    #> generation: 6 current_time: 2026-04-29 22:16:43.490501
    #> NULL

# 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.

    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/Rtmpr5KfNX/1.rda
    #> generation: 2 current_time: 2026-04-29 22:16:45.394113
    #> solution file saved in /tmp/Rtmpr5KfNX/2.rda
    #> solution file saved in /tmp/Rtmpr5KfNX/3.rda
    #> generation: 4 current_time: 2026-04-29 22:16:46.260445
    #> solution file saved in /tmp/Rtmpr5KfNX/4.rda
    #> solution file saved in /tmp/Rtmpr5KfNX/5.rda
    #> generation: 6 current_time: 2026-04-29 22:16:47.033373
    #> solution file saved in /tmp/Rtmpr5KfNX/6.rda
    #> NULL

# 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.

    # 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: 2026-04-29 22:16:48.889603
    #> generation: 4 current_time: 2026-04-29 22:16:49.774217
    #> generation: 6 current_time: 2026-04-29 22:16:50.552783
    #> solution file saved in /tmp/Rtmpr5KfNX/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:

    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

    sessionInfo()
    #> R version 4.6.0 (2026-04-24)
    #> Platform: x86_64-pc-linux-gnu
    #> Running under: Ubuntu 24.04.4 LTS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> 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
    #>
    #> time zone: Etc/UTC
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] breastCancerTRANSBIG_1.48.0 GSgalgoR_1.22.0
    #> [3] BiocStyle_2.40.0
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] doParallel_1.0.17   cli_3.6.6           knitr_1.51
    #>  [4] rlang_1.2.0         xfun_0.57           generics_0.1.4
    #>  [7] jsonlite_2.0.0      buildtools_1.0.0    htmltools_0.5.9
    #> [10] maketools_1.3.2     mco_1.17            sys_3.4.3
    #> [13] sass_0.4.10         rmarkdown_2.31      Biobase_2.72.0
    #> [16] grid_4.6.0          evaluate_1.0.5      jquerylib_0.1.4
    #> [19] fastmap_1.2.0       foreach_1.5.2       yaml_2.3.12
    #> [22] lifecycle_1.0.5     BiocManager_1.30.27 compiler_4.6.0
    #> [25] codetools_0.2-20    lattice_0.22-9      digest_0.6.39
    #> [28] nsga2R_1.1          R6_2.6.1            parallel_4.6.0
    #> [31] splines_4.6.0       Matrix_1.7-5        bslib_0.10.0
    #> [34] tools_4.6.0         iterators_1.0.14    survival_3.8-6
    #> [37] BiocGenerics_0.58.0 cachem_1.1.0