Skip to contents

salim includes a diverse mix of functions which have not found their home in a more suitable place yet. The package kinda serves as an incubator for not yet fully matured code and thus will most probably never be made available through CRAN.

This is arguably a low-cohesion package.

Installation

To install the latest development version of salim, run the following in R:

if (!("remotes" %in% rownames(installed.packages()))) {
  install.packages(pkgs = "remotes",
                   repos = "https://cloud.r-project.org/")
}

remotes::install_gitlab(repo = "salim_b/r/pkgs/salim")

Usage

The (function) reference is found here.

Package configuration

Some of salim’s functionality is controlled via package-specific global configuration which can either be set via R options or environment variables (the former take precedence). This configuration includes:

Description R option Environment variable Default value
Locale identifier consisting of a ISO 639-1 or ISO 639-3 language code plus an optional country identifier separated by a hyphen (-). For example "fr" or "de-CH". salim.locale R_SALIM_LOCALE "en-US"
Body font family for plot theming functions. salim.font_family_body R_SALIM_FONT_FAMILY_BODY "Alegreya Sans"
Body color for plot theming functions. salim.plot_color_body R_SALIM_PLOT_COLOR_BODY "#343a40"
Background color for plot theming functions. salim.plot_color_bg R_SALIM_PLOT_COLOR_BG "#f2f2f2"
Grid color for plot theming functions. salim.plot_color_grid R_SALIM_PLOT_COLOR_GRID "#d9d9d9"

Development

R Markdown format

This package’s source code is written in the R Markdown file format to facilitate practices commonly referred to as literate programming. It allows the actual code to be freely mixed with explanatory and supplementary information in expressive Markdown format instead of having to rely on # comments only.

All the .gen.R suffixed R source code found under R/ is generated from the respective R Markdown counterparts under Rmd/ using pkgpurl::purl_rmd()1. Always make changes only to the .Rmd files – never the .R files – and then run pkgpurl::purl_rmd() to regenerate the R source files.

Coding style

This package borrows a lot of the Tidyverse design philosophies. The R code adheres to the principles specified in the Tidyverse Design Guide wherever possible and is formatted according to the Tidyverse Style Guide (TSG) with the following exceptions:

  • Line width is limited to 160 characters, double the limit proposed by the TSG (80 characters is ridiculously little given today’s high-resolution wide screen monitors).

    Furthermore, the preferred style for breaking long lines differs. Instead of wrapping directly after an expression’s opening bracket as suggested by the TSG, we prefer two fewer line breaks and indent subsequent lines within the expression by its opening bracket:

    # TSG proposes this
    do_something_very_complicated(
      something = "that",
      requires = many,
      arguments = "some of which may be long"
    )
    
    # we prefer this
    do_something_very_complicated(something = "that",
                                  requires = many,
                                  arguments = "some of which may be long")

    This results in less vertical and more horizontal spread of the code and better readability in pipes.

  • Usage of magrittr’s compound assignment pipe-operator %<>% is desirable2.

  • Usage of R’s right-hand assignment operator -> is not allowed3.

  • R source code is not split over several files as suggested by the TSG but instead is (as far as possible) kept in the single file Rmd/salim.Rmd which is well-structured thanks to its Markdown support.

As far as possible, these deviations from the TSG plus some additional restrictions are formally specified in pkgpurl::default_linters, which is (by default) used in pkgpurl::lint_rmd(), which in turn is the recommended way to lint this package.

See also

  • The pal package for a collection of additional, more mature convenience/utility functions by the same author.