Author: Louis Le Nezet

# R nf-core utils tutorial

Louis Le Nezet

#### 30/03/2026

# Contents

# 1 Introduction

This package is meant to be use inside Nextflow `template()` script. Its aim is to provide useful function to take care of the connection between Nextflow variable and R logic.

## 1.1 Main function

There is two important function in this package.

### 1.1.1 Function `process_inputs()`

This function takes as inputs a list of expected options with their default values, the argument string and different validation rules.

#### 1.1.1.1 Parameter `opt`

This parameter should list all the different variable that you might use in the main script. You can set them to a default value or event directly initialize them with Nextflow variable such as:

    opt <- list(
      prefix = "${task.ext.prefix}",
      seed = 1
    )

#### 1.1.1.2 Parameter `args`

The argument string correspond to `${task.ext.args}` in Nextflow and will be parsed with `parse_arguments()`. This function expect all arguments to be in the form `--key value`. Key only argument will be interpreted as `TRUE` such as `--is-test` will give back `list("is-test" = "TRUE")`. Beware that is is for the moment a string value.

If you need spaces for one value, use bracket around it, such as `--key "value with space"`. All the key / value pairs will then overwrite their counter part in the options list passe to `process_inputs()`.

#### 1.1.1.3 Validation rules

The `process_inputs()` function will enforce the following rules to the keys listed:

- `keys_to_nullify`: will be set to R `NULL` value if is “null” or empty
- `expected_files`: these paths should be existing files
- `expected_folders`: these path should be existing folder
- `expected_double`: these values will be converted with `as.double()` or should be `NULL`
- `expected_integer`: these values will be converted with `as.integer()` or should be `NULL`
- `expected_boolean`: these values will be converted to TRUE/FALSE or should be `NULL` accepted values are:
  - TRUE: 1, yes, true
  - FALSE: 0, no, false
- `required_opts`: these keys should be non-null values

### 1.1.2 Function `process_end()`

This function will emit a `versions.yml` and a `R_sessionInfo.log` file in the directory provided. The version file will be populated with the R version, the version of nfcore.utils and the version of the additional packages given.

#### 1.1.2.1 Parameter `packages`

This parameter should be a named list where the name correspond to the conda package name and the value the R package name.

Such as:

    process_end(
      packages = list(
        "r-stats" = "stats"
      ),
      task_name = "${task.process}"
    )

## 1.2 Usage example

If we take for example the `custom/geneticmapconvert` process in nf-core modules.

The nextflow process is the following:

    process CUSTOM_GENETICMAPCONVERT {
      tag "$meta.id"
      label 'process_single'

      input:
      tuple val(meta), path(map_file)

      output:
      tuple val(meta), path("${prefix}.glimpse.map"), emit: glimpse_map
      path "versions.yml", emit: versions_geneticmapconvert, topic: versions

      when:
      task.ext.when == null || task.ext.when

      script:
      prefix = task.ext.prefix ?: "${meta.id}"
      args = task.ext.args ?: ''

      """
      echo ${args} // In the form --tolerance 0.15
      """

      template 'geneticmapconvert.R'
    }

Then in the `templates/geneticmapconvert.R` we use the following

    library(nfcore.utils)
    library(data.table)
    library(stringr)

    ### INPUTS PARSING ###
    opt <- list(
      map_file = "${map_file}",
      chr = "${meta.chr}",
      prefix = "${prefix}",
      tolerance = NULL
    )

    process_input(
      opt = opt,
      args = "${args}",
      keys_to_nullify = c("prefix", "tolerance"),
      expected_files = c("map_file"),
      expected_double = c("tolerance"),
      required_opts = c("map_file", "prefix")
    )

    ### MAIN SCRIPT ###

    ...

    ### END of PROCESS ###
    process_end(
      packages = list(
        "r-data.table" = "data.table",
        "r-stringr" = "stringr"
      ),
      task_name = "${task.process}",
      versions_path = "versions.yml",
      log_path = "R_sessionInfo.log"
    )

# 2 Session information

    options(old_opt)
    sessionInfo()

    ## R version 4.5.3 (2026-03-11)
    ## Platform: x86_64-conda-linux-gnu
    ## Running under: Ubuntu 22.04.3 LTS
    ##
    ## Matrix products: default
    ## BLAS/LAPACK: /home/llenezet/miniconda3/envs/env_r_nfcore_utils/lib/libopenblasp-r0.3.32.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ## [1] C
    ##
    ## time zone: Europe/Paris
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] BiocStyle_2.38.0
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] digest_0.6.39       R6_2.6.1            bookdown_0.46
    ##  [4] fastmap_1.2.0       xfun_0.57           cachem_1.1.0
    ##  [7] knitr_1.51          htmltools_0.5.9     rmarkdown_2.31
    ## [10] lifecycle_1.0.5     cli_3.6.5           sass_0.4.10
    ## [13] jquerylib_0.1.4     compiler_4.5.3      tools_4.5.3
    ## [16] evaluate_1.0.5      bslib_0.10.0        yaml_2.3.12
    ## [19] otel_0.2.0          BiocManager_1.30.27 jsonlite_2.0.0
    ## [22] rlang_1.1.7