| Title: | Utilities for Nf-Core Modules |
|---|---|
| Description: | Provides utility functions to facilitate the use of R within nf-core modules. The package helps parse Nextflow inputs and perform validation checks to ensure correct parameter handling and reproducible execution. |
| Authors: | nf-core Community [aut], Louis Le Nezet [aut, cre, cph] (ORCID: <https://orcid.org/0009-0000-0202-2703>) |
| Maintainer: | Louis Le Nezet <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.0.2 |
| Built: | 2026-06-23 09:29:09 UTC |
| Source: | https://github.com/nf-core/r-nf-core-utils |
This package aims to ease the link between Nextflow inputs and outputs to the R variable needed in the script.
Below are listed some of the main functions available:
process_inputs(): Given a list of expected options with their
default this function will parse the arguments given and validate
their value based on the expected rules.
process_end(): Create a versions.yml and 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.
Maintainer: Louis Le Nezet [email protected] (ORCID) [copyright holder]
Authors:
nf-core Community
Useful links:
Report bugs at https://github.com/nf-core/r-nf-core-utils/issues
library(nfcore.utils) td <- withr::local_tempdir() test_file_path <- file.path(td, "test_file.txt") file.create(test_file_path) options <- list( input_file = test_file_path, output_file = "prefix", threshold = 0.5 ) args <- c("--threshold 0.7") processed_options <- process_inputs( options, args, keys_to_nullify = c("input_file", "output_file"), expected_files = c("input_file"), expected_double = c("threshold"), required_opts = c("input_file", "threshold") ) ## Not run: process_end( packages = list( "r-stats" = "stats" ), task_name = 'MY_PROCESS' ) ## End(Not run)library(nfcore.utils) td <- withr::local_tempdir() test_file_path <- file.path(td, "test_file.txt") file.create(test_file_path) options <- list( input_file = test_file_path, output_file = "prefix", threshold = 0.5 ) args <- c("--threshold 0.7") processed_options <- process_inputs( options, args, keys_to_nullify = c("input_file", "output_file"), expected_files = c("input_file"), expected_double = c("threshold"), required_opts = c("input_file", "threshold") ) ## Not run: process_end( packages = list( "r-stats" = "stats" ), task_name = 'MY_PROCESS' ) ## End(Not run)
This function logs the R session info to a file named R_sessionInfo.log
in the specified output directory.
create_log_session_info(out_dir = ".")create_log_session_info(out_dir = ".")
out_dir |
Output directory where the R session info log will be written to. Default is the current directory. |
R session info log
td <- withr::local_tempdir() create_log_session_info(td)td <- withr::local_tempdir() create_log_session_info(td)
This function allows to automatically create the
versions.yml file used to store the packages used.
r-base as well as r-nfcore.utils versions will
automatically be added.
create_versions_yml(packages, task_name, out_dir = ".")create_versions_yml(packages, task_name, out_dir = ".")
packages |
Named list of packages to add to the versions.yml. The items names should be the conda package name, while the items value should be the package name used in R. |
task_name |
Name of the nextflow process.
Typically |
out_dir |
Output directory where the versions.yml will be written to. Default is the current directory. |
versions.yml file
td <- withr::local_tempdir() create_versions_yml(list("r-stats" = "stats"), "MY_PROCESS", td)td <- withr::local_tempdir() create_versions_yml(list("r-stats" = "stats"), "MY_PROCESS", td)
NULL or invalidCheck if is NULL or invalid
is_null_or_invalid(x, variable_name = NULL)is_null_or_invalid(x, variable_name = NULL)
x |
String to check |
variable_name |
Name of the variable to print if error occurs |
TRUE if is null, ERROR if invalid and FALSE otherwise
is_null_or_invalid(NULL) # TRUE try(is_null_or_invalid(" ")) # ERROR is_null_or_invalid("Hello World !") # FALSEis_null_or_invalid(NULL) # TRUE try(is_null_or_invalid(" ")) # ERROR is_null_or_invalid("Hello World !") # FALSE
This function checks if the input is non-NULL and contains more than just whitespace. It returns TRUE if the input is a non-empty, non-whitespace string, and FALSE otherwise.
is_valid_string(input)is_valid_string(input)
input |
A variable to check. |
A logical value: TRUE if the input is a valid, non-empty, non-whitespace string; FALSE otherwise.
is_valid_string("Hello World") # Returns TRUE is_valid_string(" Hello World ") # Returns TRUE is_valid_string(" ") # Returns FALSE is_valid_string(NULL) # Returns FALSEis_valid_string("Hello World") # Returns TRUE is_valid_string(" Hello World ") # Returns TRUE is_valid_string(" ") # Returns FALSE is_valid_string(NULL) # Returns FALSE
Turn “null” or empty strings into actual NULL
nullify(x)nullify(x)
x |
Input option |
NULL or x
nullify("null") # Returns NULL nullify("NULL") # Returns NULL nullify(" ") # Returns NULL nullify("") # Returns NULL nullify(NULL) # Returns NULL nullify(NA) # Returns NULL nullify("Hello") # Returns "Hello"nullify("null") # Returns NULL nullify("NULL") # Returns NULL nullify(" ") # Returns NULL nullify("") # Returns NULL nullify(NULL) # Returns NULL nullify(NA) # Returns NULL nullify("Hello") # Returns "Hello"
If only the key is given, the value will be set to TRUE
parse_arguments(x)parse_arguments(x)
x |
Long-form argument list like –opt1 val1 –opt2 val2 |
named list of options and values similar to optparse
parse_arguments("--opt1 val1 --opt2 val2") parse_arguments(' --opt1-extra "value with space" --opt2 val2 ')parse_arguments("--opt1 val1 --opt2 val2") parse_arguments(' --opt1-extra "value with space" --opt2 val2 ')
Create the versions.yml file and log session info at the end of the process.
process_end(packages, task_name, out_dir = ".")process_end(packages, task_name, out_dir = ".")
packages |
Named list of packages to add to the versions.yml. The items names should be the conda package name, while the items value should be the package name used in R. |
task_name |
Name of the nextflow process.
Typically |
out_dir |
Output directory where the versions.yml will be written to. Default is the current directory. |
versions.yml file and R session info log
td <- withr::local_tempdir() process_end(list("r-stats" = "stats"), "MY_PROCESS", td)td <- withr::local_tempdir() process_end(list("r-stats" = "stats"), "MY_PROCESS", td)
This function processes input parameters and files, applying parameter overrides, validating expected keys and files, and ensuring that the provided file paths are valid.
process_inputs( opt, args = NULL, keys_to_nullify = NULL, expected_files = NULL, expected_folders = NULL, expected_double = NULL, expected_integer = NULL, expected_boolean = NULL, required_opts = NULL )process_inputs( opt, args = NULL, keys_to_nullify = NULL, expected_files = NULL, expected_folders = NULL, expected_double = NULL, expected_integer = NULL, expected_boolean = NULL, required_opts = NULL )
opt |
A list of default options. |
args |
A character vector of command-line arguments to override defaults. |
keys_to_nullify |
A character vector of keys that should be nullified. |
expected_files |
A character vector of keys in |
expected_folders |
A character vector of keys in |
expected_double |
A character vector of keys in |
expected_integer |
A character vector of keys in |
expected_boolean |
A character vector of keys in |
required_opts |
A character vector of keys in |
A list of processed options with overrides applied and validated.
td <- withr::local_tempdir() test_file_path <- file.path(td, "test_file.txt") file.create(test_file_path) options <- list( input_file = test_file_path, output_file = "prefix", threshold = 0.5, "is-a-test" = NULL ) args <- c("--threshold 0.7 --is-a-test") processed_options <- process_inputs( options, args, keys_to_nullify = c("input_file", "output_file"), expected_files = c("input_file"), expected_double = c("threshold"), expected_boolean = c("is-a-test"), required_opts = c("input_file", "threshold") )td <- withr::local_tempdir() test_file_path <- file.path(td, "test_file.txt") file.create(test_file_path) options <- list( input_file = test_file_path, output_file = "prefix", threshold = 0.5, "is-a-test" = NULL ) args <- c("--threshold 0.7 --is-a-test") processed_options <- process_inputs( options, args, keys_to_nullify = c("input_file", "output_file"), expected_files = c("input_file"), expected_double = c("threshold"), expected_boolean = c("is-a-test"), required_opts = c("input_file", "threshold") )
The following rules are applied:
extension == txt or tsv, then separator is set to tabulation
extension == csv, then separator is set to comma
read_delim_flexible(file, ...)read_delim_flexible(file, ...)
file |
Input file |
... |
Arguments passed on to
|
output Data frame
This function checks if the input is non-NULL and contains more than just whitespace.
valid_string(input)valid_string(input)
input |
A variable to check. |
input with whitespace trimmed or throw error if not a valid string
valid_string("Hello World") # Returns "Hello World" valid_string(" Hello World ") # Returns "Hello World" try(valid_string(" ")) # Error try(valid_string(NULL)) # Errorvalid_string("Hello World") # Returns "Hello World" valid_string(" Hello World ") # Returns "Hello World" try(valid_string(" ")) # Error try(valid_string(NULL)) # Error
Convert to TRUE or FALSE with accepted lowered values as:
TRUE: 1, yes, true
FALSE: 0, no, false
validate_boolean(x, variable_name = NULL)validate_boolean(x, variable_name = NULL)
x |
String to check and convert |
variable_name |
Name of the variable to print if error occurs |
x as TRUE/FALSE, or NULL if is null and ERROR if x isn't convertable to a boolean
validate_boolean(NULL) # NULL try(validate_boolean(" ")) # ERROR try(validate_boolean("Hello World !")) # ERROR try(validate_boolean(12.4)) # ERROR validate_boolean("1") # TRUE validate_boolean(0) # FALSEvalidate_boolean(NULL) # NULL try(validate_boolean(" ")) # ERROR try(validate_boolean("Hello World !")) # ERROR try(validate_boolean(12.4)) # ERROR validate_boolean("1") # TRUE validate_boolean(0) # FALSE
Check if value is a double number
validate_double(x, variable_name = NULL)validate_double(x, variable_name = NULL)
x |
String to check and convert |
variable_name |
Name of the variable to print if error occurs |
x as double, or NULL if is null and ERROR if x isn't convertable to a double
validate_double(NULL) # NULL try(validate_double(" ")) # ERROR try(validate_double("Hello World !")) # ERROR validate_double("12.4") # 12.4 validate_double("12") # 12.0validate_double(NULL) # NULL try(validate_double(" ")) # ERROR try(validate_double("Hello World !")) # ERROR validate_double("12.4") # 12.4 validate_double("12") # 12.0
Check if value is an existing file
validate_file(x, variable_name = NULL)validate_file(x, variable_name = NULL)
x |
String to check |
variable_name |
Name of the variable to print if error occurs |
x, or NULL if is null and ERROR if x isn't an existing file
try(validate_file("test")) # ERRORtry(validate_file("test")) # ERROR
Check if value is an existing folder
validate_folder(x, variable_name = NULL)validate_folder(x, variable_name = NULL)
x |
String to check |
variable_name |
Name of the variable to print if error occurs |
x, or NULL if is null and ERROR if x isn't an existing folder
try(validate_folder("test")) # ERRORtry(validate_folder("test")) # ERROR
Check if value is an integer
validate_integer(x, variable_name = NULL)validate_integer(x, variable_name = NULL)
x |
String to check and convert |
variable_name |
Name of the variable to print if error occurs |
x as integer, or NULL if is null and ERROR if x isn't convertable to an integer
validate_integer(NULL) # NULL try(validate_integer(" ")) # ERROR try(validate_integer("Hello World !")) # ERROR try(validate_integer("12.4")) # ERROR validate_integer("12") # 12validate_integer(NULL) # NULL try(validate_integer(" ")) # ERROR try(validate_integer("Hello World !")) # ERROR try(validate_integer("12.4")) # ERROR validate_integer("12") # 12