{fusen} v0.4 – 14 developers tips and tricks

If you think {fusen} is not for you because you’ve been building R packages your entire life without it, it’s time to give it a try! Refer to the new tips and tricks in the dedicated vignette in case you feel you need additional functionalities: chances are I already implemented them…

Go back to the previous blog post to know how to start with {fusen}: https://rtask.thinkr.fr/fusen-v0-3-better-project-templates-grouped-functions-and-numerous-other-enhancements/

Below News, you will see the content of the vignette ‘Tips & Tricks’ in {fusen} 0.4, to go further in your package building using {fusen}.

NEWS in {fusen} v.0.4

New features

• inflate() the current opened flat file if flat_file is empty (#138)
• Add rmarkdown template for additional flat file for RStudio
• Add wrappers around add_flat_template() for lazy devs: add_additional(), add_full(), add_minimal()
• Show “flat_template” origin of files generated by {fusen} (@ALanguillaume)
• Allow inflate(vignette_name = c("Super title" = "01-Super Slug")) for nice Title different from vignette Entry (#87)

Bug fixes

• Read DESCRIPTION file for package name when available (#144 @VincentGuyader)
• Read nyc_squirrels with encoding to avoid encoding problems with use_data()
• Allow flat files with tests only
• Simplify “flat_teaching” with a unique simple function
• Fix asciify_name() to account for diacritics (@ALanguillaume)
• Improve template ‘full’ for internal data use
• Fix tests when git does not exists

Developers’ tips and tricks

1. Can I be lazy in chunk names used?

• Chunk short names are possible:
  • function can be named fun- or fun_ or fun-my_function_name
  • example can be named ex- or ex_ or ex-my_function_name
  • tests can be named test- or test-my_function_name
  • development can be named dev- or dev_ or dev-my_function_name
• There are wrappers around add_flat_template() for lazy developpers: add_additional(), add_full(), add_minimal()

2. Can I knit the content of the flat template ?

Yes. Although this is not the real goal, the flat template can be filled and run like any other Rmarkdown file.
However, you need to keep in mind that this will be transformed as a R package, which requires some specific attention.

• Use a development chunk at the beginning of your flat template to declare all packages that you will need to explore your code

```{r dev}
library(glue)
library(stringi)
```

Note that this will not be used anywhere in the package. A development chunk is only there for your code exploration, during development.

• Remember that in the package structure, examples and tests code will be run independently. Thus, examples and tests chunk need to have all code required to run independently.
• The development chunk that contains the inflate() call need to have eval=FALSE parameter to avoid side effects if you knit the flat file.

3. How to declare packages with library() for the future vignette ?

If you use a classical chunk, without any specific name, it will be copied as is in the vignette.

```{r}
library(glue)
library(stringi)
```

4. How to include examples that cannot be run ?

I created a chunk example but I do not want the example to be run in the function example and I do not want it to be run in the vignette.

• Use eval=FALSE in the chunk options, so that it wont be run in the vignette
• Use #' \dontrun{} syntax, with #' before so that examples in the function example will not be run

```{r function-myfunction}
myfunction <- function(x) {x}
```

```{r example-myfunction, eval=FALSE}
# Will be run in example but not in vignette
myfunction(10)

# Will not be run in example
#' \dontrun{
myfunction(12)
#' }
#' \dontrun{
#' myfunction(12)
#' }
```

5. Document your internal datasets in a function chunk as usual

To document datasets, pkgdoc, special R files, you can write them as is in the function chunk.
If {fusen} does not detect the keyword function() or R6Class() in the function chunk code, then the chunk is copied as is in a “R/” file.

```{r function-cars}
#' cars
#'
#' data in 'datasets'.
#'
#' @format A data frame with 50 rows and 2 variables:
#' \describe{
#'   \item{ speed }{  numeric }
#'   \item{ dist }{  numeric }
#' }
#' @source Ezekiel, M. (1930) Methods of Correlation Analysis. Wiley.
"cars"
```

6. How to ignore some chunks ?

All chunks named dev or development will not be used in the package.
Use them for your exploration that you do not want to keep at the end of the process.
This won’t affect your package.

```{r dev}
# Some code exploration
```

7. How to create a vignette with different title and Index Entry?

You can use inflate(vignette_name = c("Super title" = "01-Super Slug")) for vignette title different from vignette Entry

inflate(vignette_name = c("Super title" = "01-Super Vignette Index Entry"))

8. How not to create a vignette?

• If I only build internal functions, I may not want to inflate the flat file as a vignette.
• The flat file is the developer’s documentation and that may be enough

inflate(vignette_name = NA)

9. How to get a pre-filled template for a specific function name ?

If it is the first function of the flat template:

• you can create the template with add_flat_template("minimal", flat_name = "my_function_name"). In this case, the template will be pre-filled with your function name: chunk names, function calls.
• You can also use the RStudio Addin “Add {fusen} flat template” to create a new template in your “dev/” directory. You will be prompt for the template type and the function name

If this is the second function inside an existing template:

• Position your prompt where you want to add the new function and use the RStudio Addin: “Add {fusen} chunks”. You will be asked for the function name.
• The Addin uses add_fusen_chunks("my_function_name")

10. How to pre-fill multiple functions in one template

This can be added in the “dev_history.Rmd”, and will replace a place holder in your flat rmd (HERE in this case) with proper fusen chunks for all your future functions to be.

• Add a line with HERE in your flat file

# Path of the flat file
path_flat_rmd <- here::here("dev/flat_minimal.Rmd")

# Name of future functions to add - example
fun_nms <- c(
  "get_contract_by_country_of",
  "get_contract_subsidies_of",
  "get_contract_effort_of",
  "get_contract_fees_of",
  "get_contract_target_countries_of",
  "get_contract_all_info_of"
)

# Create content
l_chunks <- purrr::map_chr(fun_nms, fusen:::build_fusen_chunks)
chunks <- paste(l_chunks, collapse = "")

# Add in the flat file
flat_rmd <- readLines(path_flat_rmd)
flat_rmd <- sub("^HERE$", chunks, flat_rmd)
writeLines(flat_rmd, path_flat_rmd)

11. How to Inflate multiple flat files ?

• Add an entry in your main “dev_history.Rmd” file

fusen::inflate("dev/flat_file1.Rmd")
fusen::inflate("dev/flat_file2.Rmd")
fusen::inflate("dev/flat_file3.Rmd")

If the main “dev_history.Rmd” file does not exists, you can create it with add_flat_template("dev_history")

12. How to store multiple functions in a unique R file ?

There are multiple ways of doing it. Choose one of: use the section title structure, use roxygen tags or use chunk parameter.

All functions under one title section

Use the 3-set of chunks (fun, example, test) twice, under the same title section of the Rmd

# One title for both groups of chunk

The code and tests for the first function
```{r function-fun1}
```
```{r example-fun1}
```
```{r test-fun1}
```

The code and tests for the second function
```{r function-fun2}
```
```{r example-fun2}
```
```{r test-fun2}
```

Use same @rdname in function roxygen

# Title 1 for function 1

```{r function-fun_rdname1}
#' My fun_rdname1
#'
#' @param x Vector of Numeric values
#' @inheritParams stats::median
#'
#' @rdname same_rdname
#' @return
#' Median of vector x
#' @export
#'
#' @examples
#' my_fun_rdname1(2:20)
my_fun_rdname1 <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {stop("x should be numeric")}
  stats::median(x, na.rm = na.rm)
}
```

# Title  2 for function 2

```{r function-fun_rdname2}
#' My fun_rdname2
#'
#' @param x Vector of Numeric values
#' @inheritParams stats::median
#'
#' @rdname same_rdname
#' @return
#' Median of vector x
#' @export
#'
#' @examples
#' my_fun_rdname2(2:20)
my_fun_rdname2 <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {stop("x should be numeric")}
  stats::median(x, na.rm = na.rm)
}
```

Use same @filename in function roxygen

@filename is recognized only by {fusen} as a proper roxygen tag to merge multiple functions in the same “R/” and “tests/” files.
This code line is removed in the resulting “R/” files to avoid any interference with Roxygenize.

# Title 1 for function 1

```{r function-fun_filename1}
#' My fun_filename1
#'
#' @param x Vector of Numeric values
#' @inheritParams stats::median
#'
#' @filename same_filename
#' @return
#' Median of vector x
#' @export
#'
#' @examples
#' my_fun_filename1(2:20)
my_fun_filename1 <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {stop("x should be numeric")}
  stats::median(x, na.rm = na.rm)
}
```

# Title  2 for function 2

```{r function-fun_filename2}
#' My fun_filename2
#'
#' @param x Vector of Numeric values
#' @inheritParams stats::median
#'
#' @filename same_filename
#' @return
#' Median of vector x
#' @export
#'
#' @examples
#' my_fun_filename2(2:20)
my_fun_filename2 <- function(x, na.rm = TRUE) {
  if (!is.numeric(x)) {stop("x should be numeric")}
  stats::median(x, na.rm = na.rm)
}
```

Use chunk param filename = "the_common_filename"

Add it in the function chunk only

# Title 1 for function 1

```{r function-fun_chunk1, filename = "fun_chunk1"}
#' The code of your function 1
```
```{r example-fun_chunk1}
```
```{r test-fun_chunk1}
```

# Title 2 for function 2

```{r function-fun_chunk2, filename = "fun_chunk1"}
#' The code of your function 2
```
```{r example-fun_chunk2}
```
```{r test-fun_chunk2}
```

13. How to read dataset that I usually put in “tests/testthat/” for my unit tests?

You will need to write two ways of reading the data:

• One to use on-demand in the flat file, which needs to be commented
• One to be use in the future test file

# The code that you will run manually in the flat file if needed during development

# > This needs to be commented
# my_file <- read.csv("tests/testthat/my_file.csv")

# The code that will be used in the inflated test file
# This needs to be uncommented
my_file <- read.csv("my_file.csv")

14. Your tips and tricks?

What are your tips and tricks with {fusen} ?
Share with us on Twitter with @thinkR_fr