In acidgenomics/r-syntactic: Syntactically Valid Names

## nolint start
suppressPackageStartupMessages({
    library(syntactic)
})
## nolint end
data(syntactic, package = "AcidTest")
object <- syntactic[["character"]]

Introduction

The syntactic package returns syntactically valid names from user-defined sample and other biological metadata. The package improves upon the make.names function defined in base R, specifically by adding smart handling of mixed case acronyms (e.g. mRNA, RNAi), decimals, and other coventions commonly used in the life sciences.

The package is intended to work in two modes: string mode (default) and file rename mode.

There are five primary naming functions:

camelCase (e.g. "helloWorld").
dottedCase (e.g. "hello.world").
snakeCase (e.g. "hello_world").
kebabCase (e.g. "hello-world").
upperCamelCase (e.g. "HelloWorld").

Recommended naming conventions

Unsure how to name variables and/or functions in R? Here are my current recommendations, for scientists and bioinformaticians:

When in doubt, refer to the Bioconductor coding style guide.
Use snakeCase as your daily driver, inside of scripts and R Markdown files. This convention is always legible and consistent. Don't use this convention inside of packages, however.
For packages, switch to camelCase. Use this consistently for function names, arguments, and internal variable names. Camel case is the preferred convention for Bioconductor, which uses the S4 class system for object-oriented programming. S4 generics on Bioconductor are primarily named in camel case; refer to BiocGenerics for details. Note that snake case is used for function names in RStudio / tidyverse packages, but these build on top of the S3 class system, which isn't used inside of most biological R packages.
upperCamelCase should only ever be used for S4 class definitions, such as SummarizedExperiment. Avoid naming functions with this convention.
Use kebabCase for file names. Dashes (hyphens) serve as consistent word boundaries across platforms, whereas underscores do not. This applies in particular to URLs. This post by Jeff Atwood explains nicely why you should use dashes instead of underscores for file names.
Avoid using dottedCase in R whenever possible. It's the original naming convention defined in R, but it's smart to instead use snakeCase and its convention of underscores instead. The S3 class system uses a naming convention of generic.method, which can get mixed up by variables containing periods (dots) in the name.
Valid names in R can't start with a number. This is often an issue when importing sequencing data (e.g. FASTQ files). The naming functions will add an "x" prefix in this case.

String mode

In general, stick with snakeCase or camelCase when sanitizing character strings in R.

print(object)

Use snake case formatting inside of scripts.

snakeCase(object)

We recommend using camel case inside of packages. The syntactic package offers two variants: relaxed (default) or strict mode. We prefer relaxed mode for function names, which generally returns acronyms (e.g. ID) more legibly.

camelCase(object, strict = FALSE)

If you're more old school and prefer using strict camel conventions, that's also an option.

camelCase(object, strict = TRUE)

Here's the default convention in R, for comparison:

make.names(object)

Additionally, the package exports these string functions:

capitalize(): Capitalize the first letter of all words in a string.
sentenceCase: Convert a string into sentence case.
makeNames(): A modern variant of make.names() that sanitizes using underscores instead of dots.

File rename mode

The package also supports file name sanitization, using the syntacticRename function. This currently includes support for kebabCase (recommended), snakeCase, and camelCase, via the fun argument.

Here's an example of how to quickly rename files on disk into kebab case:

input <- c(
    "mRNA Extraction.pdf",
    "inDrops v3 Library Prep.pdf"
)
invisible(file.create(input))
output <- syntacticRename(input, fun = "kebabCase")
print(output)
invisible(file.remove(output[["to"]]))

File names containing a prefix that is considered illegal in R can be allowed, which is often useful for sequencing data:

input <- paste0(seq(4L), "_sample_", LETTERS[seq(4L)], ".fastq.gz")
print(input)
invisible(file.create(input))
output <- syntacticRename(input, fun = "kebabCase")
print(output)
invisible(file.remove(output[["to"]]))

Recursion inside of directories is supported using the recursive = TRUE argument.

Our koopa shell bootloader uses these functions internally for quick interactive file renaming. In that package, refer to kebab-case, snake-case, and/or camel-case documentation for details.

Additional methods

The syntactic package only contains S4 methods defined for character vectors, to keep the package lightweight with few dependencies. Additional S4 methods for Bioconductor classes, including DataFrame, GenomicRanges, and SummarizedExperiment, are defined in the basejump package.