Title: Automated Reproducibility Checks for R Markdown Documents
Version: 1.2.0
Description: Provide reproducible R chunks in R Markdown document that automatically check computational results for reproducibility. This is achieved by creating json files storing metadata about computational results. A comprehensive tutorial to the package is available as preprint by Brandmaier & Peikert (2024, <doi:10.31234/osf.io/3zjvf>).
License: MIT + file LICENSE
Encoding: UTF-8
Imports: jsonlite, knitr, digest, rstudioapi, utils, rmarkdown
Suggests: spelling, MASS, psych, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Language: en-US
BugReports: https://github.com/brandmaier/reproducibleRchunks/issues
RoxygenNote: 7.3.2
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-07-23 17:05:24 UTC; andreas.brandmaier
Author: Andreas M. Brandmaier [aut, cre], Aaron Peikert [ctb]
Maintainer: Andreas M. Brandmaier <andreas.brandmaier@medicalschool-berlin.de>
Repository: CRAN
Date/Publication: 2025-07-23 17:30:02 UTC

Escape quotes for shell commands

Description

This helper prepares character vectors for use in shell commands by quoting them with shQuote() and (double) escaping any internal double quotes.

Usage

escapedQuote(x, double = FALSE)

Arguments

x

A character vector that may contain double quotes.

double

Boolean. Should the quotes be escaped twice? Default: FALSE

Value

A character vector with all double quotes double escaped so that it can safely be passed to a command line call.

Examples

## Not run: 
escapedQuote('foo "bar" baz')

## End(Not run)

Gather Package Names

Description

Searches all meta data in the current directory for information on what R packages are necessary to reproduce the Markdown files.

Usage

gather_package_names()

Value

A character vector of R package names.

find all metadata files

Description

find all metadata files

Usage

get_all_metadata_files()

Get the total number of failed reproduction attempts

Description

Get the total number of failed reproduction attempts

Usage

get_num_reproducibility_errors(envir = .cache)

Arguments

envir

Environment to retrieve data from. This defaults to an internal package namespace.

Value

Returns the number of errors encountered when reproducing a Markdown document

Get a summary about all reproduction attempts

Description

This function returns a data frame, in which details about reproduction attempts are collected. The data frame has three columns named "Chunk","Variable", and "Success". Every row in the data frame corresponds to one variable, for which reproducibility was tested. Chunk stores the name of the surrounding chunk, Variable stores the name of the variable, and Success is a boolean variable, which indicates whether the reproduction attempt was successful.

Usage

get_reproducibility_summary(envir = .cache)

Arguments

envir

Environment to retrieve data from. This defaults to an internal package namespace.

Value

Returns a data.frame with three columns.

Test reproducibility of an R Markdown file

Description

Test reproducibility of an R Markdown file

Usage

isReproducible(
  filename,
  resetOptions = TRUE,
  engine = c("knitr", "rmarkdown"),
  quiet = TRUE,
  ...
)

Arguments

filename

Character. An R Markdown file to check for reproducibility

resetOptions

Boolean. Should all package options be reset to defaults? TRUE by default. This avoids problems if multiple checks on multiple documents with varying options are made in a row

engine

Character. Either knitr or rmarkdown, depending on what package should be used to render the document.

quiet

Boolean. Suppress output when knitting the document.

...

Optional arguments passed down to rmarkdown::render()

Loading reproducibility data

Description

This function loads reproducibility meta data from a file and stores the meta information about the variable contents in the specified environment. Reproducibility meta data can be loaded from either a json (preferred) or a binary saved R object. The function returns a named list with meta information restored from file. The named elements include "hashing" indicating whether a hashing algorithm was used, "hashing_algorithm" indicating the name of the hashing algorithm, "hashing_package" indicating the name of the R package, from which the hashing algorithm was used, "hashing_package_version" indicating the package version, "digits" the numeric precision used before hashing numeric values, and "code_fingerprint" the actual hashed string of the chunk code.

Usage

load_repro_data(filename, envir, filetype = c("json", "rda"))

Arguments

filename

Character. File name to load objects from.

envir

Environment to load the objects into. By default, this is the global environment.

filetype

Character. Currently supported is json and rda.

Value

Returns a named list with meta information restored from file. See description for more details.

See Also

save_repro_data()

Knitr Hook

Description

This is the main RMarkdown chunk hook for processing the automated reproducibility tests of code chunks. This function is not intended to be called directly. Rather, it is expected that RStudio calls this function when rendering chunks with the label identical to this function name.

Usage

reproducibleR(options)

Arguments

options

A list of chunk options passed from the knitr engine. Usually this is just the object options passed to the engine function; see knit_engines.

Details

This function first executes the R code from a given chunk. If a variable is declared within the scope of the chunk, meta information about the variable's content are generated. If no metadata exists, this metadata is stored in a separate file. If metadata exists, it is compared against the metadata of the reproduction attempt.

Value

A character string generated from the source code and output.

Author(s)

Andreas M. Brandmaier

Examples


reproducibleR(knitr::opts_chunk$merge(list(engine="reproducibleR",code="1+1")))

Delete reproducibility files

Description

Deletes all meta data in the current directory, that is, deletes all files in the current working directory that start with default_prefix() and end with default_filetype().

Usage

reset(interactive = NULL)

Arguments

interactive

Logical. If TRUE (the default), the user is asked for confirmation before files are removed.

Value

Invisibly returns the vector of deleted files.

Storing reproducibility data

Description

Storing reproducibility data

Usage

save_repro_data(
  x,
  filename,
  filetype = default_filetype(),
  envir = NULL,
  extra = NULL
)

Arguments

x

Object to be stored.

filename

Name (possible including full path) of the save file

filetype

Character. Currently supported is json and rda.

envir

Environment to load the objects into. By default, this is the global environment.

extra

List. Extra payload to store in the meta data

Value

No return value

See Also

load_repro_data()

Add GitHub Action to test reproducibility

Description

Creates a GitHub Actions workflow that runs isReproducible() on all R Markdown files in the repository. The workflow installs pandoc so that the documents can be rendered. Depending on the result, a badge file reproducibleRchunks-badge.svg is generated indicating successful, failing or unknown reproduction status.

Usage

use_github_action(
  files = NULL,
  path = ".github/workflows/reproducibleR.yml",
  packages = NULL
)

Arguments

files

Character. File(s) that should be tested for reproducibility. If NULL, all Rmd files in the directory.

path

Path to the workflow file to create. Defaults to .github/workflows/reproducibleR.yml.

packages

Character. If NULL, necessary R packages are inferred automatically.

Value

Invisibly returns the path to the created workflow file.