rco
is an open source package, and the contributions to
the development of the library are more than welcome. In this guide is
detailed what is the procedure commonly followed to develop a new
optimizer.
Developing a new optimizer will require four steps that are explained below: writing the code, the test cases, the vignette, and some additional files.
All the code developed for the new optimizer will go in a file named
R/opt-**optimizer-name**.R
.
An optimizer will be a single function (one exported), which should
be called opt_**optimizer_name**
. This function will take
as input a texts
parameter that contains a string list
(character vector) with the code to optimize. An example of this, with
just one code to optimize, would be:
All other parameters that the function
opt_**optimizer_name**
takes as input must have an
associated default parameter, for example,
opt_**optimizer_name** <- function(texts, param1 = FALSE) { ... }
.
As output, the developed function must return a list with a field
codes
that must have the same format as the
texts
input but with the code optimized.
To document code we use the roxygen2
package. You should give a brief description of the new optimizer, of
the input parameters, and an example of use.
As skeleton to use to develop the new optimizer we propose to follow:
#' Optimizer: **New Optimizer Name**
#'
#' **New optimizer description**
#' Carefully examine the results after running this function!
#'
#' @param texts A list of character vectors with the code to optimize.
#' **Other parameters description**
#'
#' @examples
#' **New optimizer example of use**
#'
#' @export
#'
opt_**optimizer_name** <- function(texts) {
# todo: **list of possible improvements for the optimizer**
res <- list()
**new optimizer code**
res$codes <- **...**
return(res)
}
For the parsing and tokenization of the code we suggest to use the
functions developed in R/parse.R
.
For testing, we use the testthat
package. All the code for testing the new optimizer will go in a file
named tests/testthat/test-opt_**optimizer_name**.R
.
Please create a test suite that covers a large percentage of possible use and border cases.
As skeleton to use to develop the new optimizer’s test suite we propose to follow:
When developing a new optimizer, we create a vignette to explain it.
This documentation will not only be a vignette of the package but will
also be part of the rco
website.
For writing vignettes, we use the knitr
and rmarkdown
packages. The new vignette will go in a file named
vignettes/opt-**optimizer-name**.Rmd
, and must follow the
skeleton:
---
output: rmarkdown::html_vignette
title: **New Optimizer Name**
vignette: >
%\VignetteIndexEntry{**New Optimizer Name**}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
# **New Optimizer Name**
## Background
## Example
## Implementation
## **Additional headings** (optional)
## To-Do (optional)
The Background
section must introduce the reader to why
this optimization provides improvements, and what it does. The
Example
section must give a real example to be optimized,
and show the improvements it gave in terms of execution speed, memory
usage, or others. The Implementation
section must show the
idea beneath the optimizer coding, this section intends to ease the
understanding of the developed code if it is needed to be edited or
improved. Then, as many sections as necessary can be included, where
questions and challenges related to the optimizer are explained or
commented. Finally, if a list of possible improvements for the optimizer
were detailed, each of them should be discussed in the
To-Do
section.
DESCRIPTION
Package Version must be bumped, if the current version is
x.y.z
then it should be updated to
x.y.(z+1)
.
NEWS.md
A entry to the NEWS.md
file should be added:
R/optimizers.R
The new optimizer function must be added to the
all_optimizers
list with its name. Also add it in its
documentation, as the other optimizers are itemized.
_pkgdown.yml
Add the new optimizer’s vignette in the website, for this, follow as it is done with the rest of the optimizers.