Package 'worcs'

Description

Add a specific endpoint to the WORCS project file (a filename, or "testthat" integration tests), see Details.

Usage

add_endpoint(filename = NULL, worcs_directory = ".", verbose = TRUE, ...)

Arguments

Details

Endpoints are either:

1. Files that are expected to be exactly reproducible (e.g., "manuscript.html", "myfigure.png", "results_table.csv", et cetera). For individual files, reproducibility is checked by ensuring that the endpoint's checksum is unchanged, see digest. Be mindful that the checksum also changes if two files are practically, but not literally, identical. This can occur when using random numbers anywhere in your analysis (e.g., Monte Carlo estimation, or even jittering points in a plot), or when numbers are rounded differently in the 15th decimal on different computers.

2. A folder of integration tests, created using the testthat package (see add_testthat). Note that testthat allows you, for example, to test whether numbers are equal within rounding tolerance.

Value

No return value. This function is called for its side effects.

See Also

snapshot_endpoints check_endpoints

Examples

# Create directory to run the example
old_wd <- getwd()
test_dir <- file.path(tempdir(), "add_endpoint")
dir.create(test_dir)
setwd(test_dir)
file.create(".worcs")
writeLines("test", "test.txt")
add_endpoint("test.txt")
# Cleaning example directory
setwd(old_wd)
unlink(test_dir, recursive = TRUE)

Description

This function wraps usethis' licenses functions, which are designed for R-packages. This function makes them applicable to other use cases (e.g., WORCS projects, FAIR theory).

Usage

add_license_file(path = ".", license = "ccby", ...)

Arguments

Value

No return value. This function is called for its side effects.

Examples

if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
add_license_file(path = ".",
                 license = "proprietary",
                 copyright_holder = "test")
})
}

Description

Adds an Rmarkdown manuscript to a 'worcs' project.

Usage

add_manuscript(
  worcs_directory = ".",
  manuscript = "APA6",
  remote_repo = NULL,
  verbose = TRUE,
  ...
)

Arguments

Details

Available choices include the following manuscript templates:

'APA6'

An APA6 style template from the papaja package

'github_document'

A github_document from the rmarkdown package

'acm_article'

acm style template from the rtices package

'acs_article'

acs style template from the rtices package

'aea_article'

aea style template from the rtices package

'agu_article'

agu style template from the rtices package

'ajs_article'

ajs style template from the rtices package

'amq_article'

amq style template from the rtices package

'ams_article'

ams style template from the rtices package

'arxiv_article'

arxiv style template from the rtices package

'asa_article'

asa style template from the rtices package

'bioinformatics_article'

bioinformatics style template from the rtices package

'biometrics_article'

biometrics style template from the rtices package

'copernicus_article'

copernicus style template from the rtices package

'ctex_article'

ctex style template from the rtices package

'elsevier_article'

elsevier style template from the rtices package

'frontiers_article'

frontiers style template from the rtices package

'glossa_article'

glossa style template from the rtices package

'ieee_article'

ieee style template from the rtices package

'ims_article'

ims style template from the rtices package

'informs_article'

informs style template from the rtices package

'iop_article'

iop style template from the rtices package

'isba_article'

isba style template from the rtices package

'jasa_article'

jasa style template from the rtices package

'jedm_article'

jedm style template from the rtices package

'joss_article'

joss style template from the rtices package

'jss_article'

jss style template from the rtices package

'lipics_article'

lipics style template from the rtices package

'mdpi_article'

mdpi style template from the rtices package

'mnras_article'

mnras style template from the rtices package

'oup_article'

oup style template from the rtices package

'peerj_article'

peerj style template from the rtices package

'pihph_article'

pihph style template from the rtices package

'plos_article'

plos style template from the rtices package

'pnas_article'

pnas style template from the rtices package

'rjournal_article'

rjournal style template from the rtices package

'rsos_article'

rsos style template from the rtices package

'rss_article'

rss style template from the rtices package

'sage_article'

sage style template from the rtices package

'sim_article'

sim style template from the rtices package

'springer_article'

springer style template from the rtices package

'tf_article'

tf style template from the rtices package

'trb_article'

trb style template from the rtices package

'wellcomeor_article'

wellcomeor style template from the rtices package

Value

No return value. This function is called for its side effects.

Examples

the_test <- "worcs_manuscript"
old_wd <- getwd()
dir.create(file.path(tempdir(), the_test))
file.create(file.path(tempdir(), the_test, ".worcs"))
add_manuscript(file.path(tempdir(), the_test),
              manuscript = "None")
setwd(old_wd)
unlink(file.path(tempdir(), the_test))

Description

Adds an Rmarkdown preregistration template to a 'worcs' project.

Usage

add_preregistration(
  worcs_directory = ".",
  preregistration = "cos_prereg",
  verbose = TRUE,
  ...
)

Arguments

Details

Available choices include the templates from the prereg package, and several unique templates included with worcs:

'PSS'

Preregistration and Sharing Software (Krypotos, Klugkist, Mertens, & Engelhard, 2019)

'Secondary'

Preregistration for secondary analyses (Mertens & Krypotos, 2019)

'aspredicted_prereg'

aspredicted template from the prereg package

'brandt_prereg'

brandt template from the prereg package

'cos_prereg'

cos template from the prereg package

'fmri_prereg'

fmri template from the prereg package

'prp_quant_prereg'

prp_quant template from the prereg package

'psyquant_prereg'

psyquant template from the prereg package

'rr_prereg'

rr template from the prereg package

'vantveer_prereg'

vantveer template from the prereg package

Value

No return value. This function is called for its side effects.

Examples

the_test <- "worcs_prereg"
old_wd <- getwd()
dir.create(file.path(tempdir(), the_test))
file.create(file.path(tempdir(), the_test, ".worcs"))
add_preregistration(file.path(tempdir(), the_test),
                    preregistration = "cos_prereg")
setwd(old_wd)
unlink(file.path(tempdir(), the_test))

Description

Add a recipe to a WORCS project file to generate its endpoints.

Usage

add_recipe(
  worcs_directory = ".",
  recipe = "rmarkdown::render('manuscript/manuscript.Rmd')",
  terminal = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Value

No return value. This function is called for its side effects.

See Also

add_endpoint snapshot_endpoints check_endpoints

Examples

# Create directory to run the example
if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
file.create(".worcs")
writeLines("test", "test.txt")
add_recipe()
})
}

Description

This function adds a user-specified synthetic data resource for public use to a WORCS project with closed data.

Usage

add_synthetic(
  data,
  synthetic_name = paste0("synthetic_", original_name),
  original_name,
  worcs_directory = ".",
  verbose = TRUE,
  ...
)

Arguments

Value

Returns NULL invisibly. This function is called for its side effects.

See Also

open_data closed_data save_data

Examples

# Create directory to run the example
old_wd <- getwd()
test_dir <- file.path(tempdir(), "add_synthetic")
dir.create(test_dir)
setwd(test_dir)
worcs:::write_worcsfile(".worcs")
# Prepare data
df <- iris[1:3, ]
# Run closed_data without synthetic
closed_data(df, codebook = NULL, synthetic = FALSE)
# Manually add synthetic
add_synthetic(df, original_name = "df.csv")
# Remove original from file and environment
file.remove("df.csv")
rm(df)
# See that load_data() now loads the synthetic file
load_data()
# Cleaning example directory
setwd(old_wd)
unlink(test_dir, recursive = TRUE)

Description

Add a computational pipeline to a worcs project using the targets and tarchetypes packages (which must be installed). See those packages for extensive documentation.

Usage

add_targets(worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

No return value. This function is called for its side effects.

Examples

# Create directory to run the example
old_wd <- getwd()
test_dir <- file.path(tempdir(), "targets")
dir.create(test_dir)
setwd(test_dir)
file.create(".worcs")
add_targets()
# Cleaning example directory
setwd(old_wd)
unlink(test_dir, recursive = TRUE)

Description

Wraps use_testthat to add integration testing to a WORCS Project.

As testthat is primarily geared towards integration tests for 'R' packages, this function conducts testthat test for WORCS projects.

Usage

add_testthat(worcs_directory = ".", ...)

test_worcs(worcs_directory = ".", ...)

Arguments

Value

No return value. This function is called for its side effects.

No return value. This function is called for its side effects.

Examples

if(requireNamespace("withr", quietly = TRUE) &
  requireNamespace("testthat", quietly = TRUE)){
withr::with_tempdir({
  usethis::create_project(path = ".", rstudio = FALSE, open = FALSE)
  add_testthat()
})
}
if(requireNamespace("withr", quietly = TRUE) &
  requireNamespace("testthat", quietly = TRUE)){
  tmpdr <- file.path(tempdir(), "testworcs")
  usethis::create_project(path = tmpdr, rstudio = FALSE, open = FALSE)
  usethis::with_project(tmpdr, {
  writeLines("", ".worcs")
  add_testthat()
  usethis::use_test(name = "testme", open = FALSE)
  test_worcs()
  })

}

Description

Check that the checksums of all endpoints in a WORCS project match their snapshots.

Usage

check_endpoints(worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

Returns a logical value (TRUE/FALSE) invisibly.

See Also

add_endpoint snapshot_endpoints

Examples

# Create directory to run the example
old_wd <- getwd()
test_dir <- file.path(tempdir(), "check_endpoint")
dir.create(test_dir)
setwd(test_dir)
file.create(".worcs")
writeLines("test", "test.txt")
add_endpoint("test.txt")
check_endpoints()
# Cleaning example directory
setwd(old_wd)
unlink(test_dir, recursive = TRUE)

Description

Evaluates whether a project meets the criteria of the WORCS checklist (see worcs_checklist).

Usage

check_worcs(path = ".", verbose = TRUE)

Arguments

Value

A data.frame with a description of the criteria, and a column with evaluations ($pass). For criteria that must be evaluated manually, $pass will be FALSE.

Examples

example_dir <- file.path(tempdir(), "badge")
dir.create(example_dir)
write("a", file.path(example_dir, ".worcs"))
check_worcs(path = example_dir)

Description

This function checks that all worcs dependencies are correctly installed, and suggests how to remedy any missing dependencies.

Usage

check_worcs_installation(what = "all")

check_dependencies(package = "worcs")

check_git()

check_github(pat = TRUE, ssh = FALSE)

check_ssh()

check_tinytex()

check_rmarkdown()

check_renv()

check_renv_synchronized(worcs_directory = ".", ...)

Arguments

Value

Logical, indicating whether all checks passed or not.

Examples

check_worcs_installation("none")

Description

This is a wrapper for render. First, this function parses the citations in the document, converting citations marked with double at sign, e.g.: @@reference2020, into normal citations, e.g.: @reference2020. Then, it renders the file.

Usage

cite_all(...)

Arguments

Value

Returns NULL invisibly. This function is called for its side effect of rendering an 'R Markdown' file.

Examples

# NOTE: Do not use this function interactively, as in the example below.
# Only specify it as custom knit function in an 'R Markdown' file, like so:
# knit: worcs::cite_all

 if (rmarkdown::pandoc_available("2.0")){
   if(requireNamespace("withr", quietly = TRUE)){
     withr::with_tempdir({
       file_name <- file.path("citeall.Rmd")
       loc <- rmarkdown::draft(file_name,
                               template = "github_document",
                               package = "rmarkdown",
                               create_dir = FALSE,
                               edit = FALSE)
       write(c("", "Optional reference: @reference2020"),
             file = file_name, append = TRUE)
       cite_all(file_name)
     }, pattern = "cite_all")
   }
 }

Description

This is a wrapper for render. First, this function parses the citations in the document, removing citations marked with double at sign, e.g.: @@reference2020. Then, it renders the file.

Usage

cite_essential(...)

Arguments

Value

Returns NULL invisibly. This function is called for its side effect of rendering an 'R Markdown' file.

Examples

# NOTE: Do not use this function interactively, as in the example below.
# Only specify it as custom knit function in an R Markdown file, like so:
# knit: worcs::cite_all

if (rmarkdown::pandoc_available("2.0")){
  file_name <- tempfile("citeessential", fileext = ".Rmd")
  rmarkdown::draft(file_name,
                   template = "github_document",
                   package = "rmarkdown",
                   create_dir = FALSE,
                   edit = FALSE)
  write(c("", "Optional reference: @reference2020"),
        file = file_name, append = TRUE)
  cite_essential(file_name)
}

Description

This function saves a data.frame as a .csv file (using write.csv), stores a checksum in '.worcs', appends the .gitignore file to exclude filename, and saves a synthetic copy of data for public use. To generate these synthetic data, the function synthetic is used.

Usage

closed_data(
  data,
  filename = paste0(deparse(substitute(data)), ".csv"),
  codebook = paste0("codebook_", deparse(substitute(data)), ".Rmd"),
  value_labels = paste0("value_labels_", deparse(substitute(data)), ".yml"),
  worcs_directory = ".",
  synthetic = TRUE,
  save_expression = write.csv(x = data, file = filename, row.names = FALSE),
  load_expression = read.csv(file = filename, stringsAsFactors = TRUE),
  ...
)

Arguments

Value

Returns NULL invisibly. This function is called for its side effects.

See Also

open_data closed_data save_data

Examples

if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    file.create(".worcs")
    df <- iris[1:3, ]
    df$Species <- droplevels(df$Species)
    closed_data(df, codebook = NULL)
  })
}

Description

For each column of x, this function checks whether value labels exist in value_labels. If so, integer values are replaced with these value labels.

Usage

data_label(
  x,
  variables = names(x),
  value_labels = read_yaml(paste0("value_labels_", substitute(x), ".yml"))
)

Arguments

Value

A data.frame.

Examples

## Not run: 
if(interactive()){
 labs <- list(x = list(class = "factor", `1` = "a", `2` = "b"))
 df <- data.frame(x = 1:2)
 df <- data_label(df, value_labels = labs)
 }

## End(Not run)

Description

Coerces factor and ordered variables to class integer.

Usage

data_unlabel(x, variables = names(x)[sapply(x, inherits, what = "factor")])

Arguments

Value

A data.frame.

Examples

## Not run: 
if(interactive()){
 df <- data.frame(x = factor(c("a", "b")))
 df <- data_unlabel(df)
 }

## End(Not run)

Description

Provide descriptive statistics for a dataset.

Usage

descriptives(x, ...)

Arguments

Value

A data.frame with descriptive statistics for x.

Examples

descriptives(iris)

Description

Export project to .zip file

Usage

export_project(zipfile = NULL, worcs_directory = ".", open_data = TRUE)

Arguments

Value

Logical, indicating the success of the operation. This function is called for its side effect of creating a .zip file.

Examples

export_project(worcs_directory = tempdir())

Description

Arguments passed through ... are added to the .gitignore file. Elements already present in the file are modified. When ignore = TRUE, the arguments are added to the .gitignore file, which will cause 'Git' to not track them.

When ignore = FALSE, the arguments are prepended with !, This works as a "double negation", and will cause 'Git' to track the files.

Usage

git_ignore(..., ignore = TRUE, repo = ".")

Arguments

Value

No return value. This function is called for its side effects.

Examples

if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
dir.create(".git")
git_ignore("ignorethis.file")
})
}

Description

Given that a 'GitHub' user is configured, with the appropriate permissions, this function pushes the current branch (if safe), then publishes a 'GitHub' Release of the repository indicated by repo to that user's account.

Usage

git_release_publish(repo = ".", tag_name = NULL, release_name = NULL)

Arguments

Value

No return value. This function is called for its side effects.

Examples

## Not run: 
git_release_publish()

## End(Not run)

Description

Given that a 'GitHub' user is configured, with the appropriate permissions, this function connects to an existing repository.

Usage

git_remote_connect(repo, remote_repo)

Arguments

Value

Invisibly returns a list with the following elements:

• repo_url: Character, URL of the connected repository

• repo_exists: Logical

• prior_commits: Logical

See Also

gh_whoami git_fetch, git_remote

Examples

## Not run: 
git_remote_connect()

## End(Not run)

Description

Given that a 'GitHub' user is configured, with the appropriate permissions, this function creates a new repository on your account.

Usage

git_remote_create(name, private = TRUE)

Arguments

Value

Invisibly returns a logical value, indicating whether the function was successful or not.

Examples

## Not run: 
git_remote_create()

## End(Not run)

Description

This function is a wrapper for git_add, git_commit, and git_push. It adds all locally changed files to the staging area of the local 'Git' repository, then commits these changes (with an optional) message, and then pushes them to a remote repository. This is used for making a "cloud backup" of local changes. Do not use this function when working with privacy sensitive data, or any other file that should not be pushed to a remote repository. The git_add argument force is disabled by default, to avoid accidentally committing and pushing a file that is listed in .gitignore.

Usage

git_update(
  message = paste0("update ", Sys.time()),
  files = ".",
  repo = ".",
  author,
  committer,
  remote,
  refspec,
  password,
  ssh_key,
  mirror,
  force,
  verbose = TRUE
)

Arguments

Value

No return value. This function is called for its side effects.

Examples

git_update()

Description

This function is a wrapper for git_config_global_set. It sets two name/value pairs at once: name = "user.name" is set to the value of the name argument, and name = "user.email" is set to the value of the email argument.

Usage

git_user(name, email, overwrite = !has_git_user(), verbose = TRUE)

Arguments

Value

No return value. This function is called for its side effects.

Examples

git_user("name", "email", overwrite = FALSE)

Description

Sets up a GitHub Action to perform continuous integration (CI) for a WORCS project. CI automatically evaluates check_endpoints() or reproduce(check_endpoints = TRUE). at each push or pull request.

Usage

github_action_check_endpoints(worcs_directory = ".")

github_action_reproduce(worcs_directory = ".")

github_action_testthat(worcs_directory = ".")

Arguments

Value

No return value. This function is called for its side effects.

See Also

use_github_action add_endpoint check_endpoints

Description

Check whether the values user.name and user.email exist exist for the current repository. Uses git_signature_default.

Usage

has_git_user(repo = ".")

Arguments

Value

Logical, indicating whether 'Git' global configuration settings could be retrieved, and contained the values user.name and user.email.

Examples

testdir <- file.path(tempdir(), "test_git_user")
dir.create(testdir)
gert::git_init(testdir)
has_git_user(testdir)
unlink(testdir, recursive = TRUE)

Description

List the endpoints in a WORCS project.

Usage

list_endpoints(worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

None, prints to the console.

See Also

add_endpoint snapshot_endpoints

Examples

if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    file.create(".worcs")
    write.csv(iris, "iris.csv")
    add_endpoint("iris.csv")
    list_endpoints()
  })
}

Description

Scans the WORCS project file for data that have been saved using open_data or closed_data, and loads these data into the global (working) environment. The function will load the original data if available on the current system. If only a synthetic dataset is available, this function loads the synthetic data. The name of the object containing the data is derived from the file name by removing the file extension, and, when applicable, the prefix "synthetic_". Thus, both "data.csv" and "synthetic_data.csv" will be loaded into an object called data.

Usage

load_data(
  worcs_directory = ".",
  to_envir = TRUE,
  envir = parent.frame(1),
  verbose = TRUE,
  use_metadata = TRUE
)

Arguments

Value

Returns a list invisibly. If to_envir = TRUE, this list contains the loaded data files. If to_envir = FALSE, the list is empty, and the loaded data files are attached directly to the global environment.

Examples

if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    file.create(".worcs")
    df <- iris[1:5, ]
    df$Species <- droplevels(df$Species)
    closed_data(df, codebook = NULL)
    temp_env <- new.env()
    load_data(envir = temp_env)
    rm("df", envir = temp_env)
    file.remove("df.csv")
    load_data(envir = temp_env)
  })
}

Description

Loads the designated project entry point into the default editor, using file.edit.

Usage

load_entrypoint(worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

No return value. This function is called for its side effects.

Examples

## Not run: 
if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    # Prepare worcs file and dummy entry point
    worcs:::write_worcsfile(".worcs", entry_point = "test.txt")
    writeLines("Hello world", con = file("test.txt", "w"))
    # Demonstrate load_entrypoint()
    load_entrypoint()
  })
}

## End(Not run)

Description

Creates a codebook for a dataset in 'R Markdown' format, and renders it to 'markdown' for 'GitHub'. A codebook contains metadata and documentation for a data file. We urge users to customize the automatically generated 'R Markdown' document and re-knit it, for example, to add a paragraph with details on the data collection procedures. The variable descriptives are stored in a .csv file, which can be edited in 'R' or a spreadsheet program. Columns can be appended, and we encourage users to complete at least the following two columns in this file:

category

Describe the type of variable in this column. For example: "morality".

description

Provide a plain-text description of the variable. For example, the full text of a questionnaire item: "People should be willing to do anything to help a member of their family".

Re-knitting the 'R Markdown' file (using render) will transfer these changes to the 'markdown' file for 'GitHub'.

Usage

make_codebook(
  data,
  filename = "codebook.Rmd",
  render_file = TRUE,
  csv_file = gsub("rmd$", "csv", filename, ignore.case = TRUE),
  verbose = TRUE
)

Arguments

Value

Logical, indicating whether or not the operation was successful. This function is mostly called for its side effect of rendering an 'R Markdown' codebook.

Examples

if(rmarkdown::pandoc_available("2.0")){
  library(rmarkdown)
  library(knitr)
  filename <- tempfile("codebook", fileext = ".Rmd")
  make_codebook(iris, filename = filename, csv_file = NULL)
  unlink(c(
    ".worcs",
    filename,
    gsub("\\.Rmd", "\\.md", filename),
    gsub("\\.Rmd", "\\.html", filename),
    gsub("\\.Rmd", "_files", filename)
  ), recursive = TRUE)
}

Description

This function prints a notification message when some or all of the data used in a project are synthetic (see closed_data and synthetic). See details for important information.

Usage

notify_synthetic(..., msg = NULL, worcs_directory = ".")

Arguments

Details

The preferred way to use this function is to provide specific data objects in the function call, using the ... argument. If no such objects are provided, notify_synthetic will scan the parent environment for objects of class worcs_data.

This function is emphatically designed to be included in an 'R Markdown' file, to dynamically generate a notification message when a third party 'Knits' such a document without having access to all original data.

Value

No return value. This function is called for its side effect of printing a notification message.

See Also

closed_data synthetic add_synthetic

Examples

if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    file.create(".worcs")
    df <- iris
    class(df) <- c("worcs_data", class(df))
    attr(df, "type") <- "synthetic"
    result <- capture.output(notify_synthetic(df, msg = "it is synthetic"))
    if(!grepl("synthetic", result)) stop()
    df <- df[1:10, ]
    closed_data(df, codebook = NULL)
    file.remove("df.csv")
    result <- capture.output(notify_synthetic(msg = "synthetic"))
    if(!grepl("synthetic", result)) stop()
    if(requireNamespace("rmarkdown", quietly = TRUE)){
    add_manuscript(manuscript = "github_document")
    print(readLines("manuscript/manuscript.Rmd"))
    rmarkdown::render("manuscript/manuscript.Rmd")
    if(!any(grepl("reproduced using synthetic",
    readLines("manuscript/manuscript.html")))) stop()
    }
  })
}

Description

This function saves a data.frame as a .csv file (using write.csv), stores a checksum in '.worcs', and amends the .gitignore file to exclude filename.

Usage

open_data(
  data,
  filename = paste0(deparse(substitute(data)), ".csv"),
  codebook = paste0("codebook_", deparse(substitute(data)), ".Rmd"),
  value_labels = paste0("value_labels_", deparse(substitute(data)), ".yml"),
  worcs_directory = ".",
  save_expression = write.csv(x = data, file = filename, row.names = FALSE),
  load_expression = read.csv(file = filename, stringsAsFactors = TRUE),
  ...
)

Arguments

Value

Returns NULL invisibly. This function is called for its side effects.

See Also

open_data closed_data save_data

Examples

if(requireNamespace("withr", quietly = TRUE)){
  withr::with_tempdir({
    file.create(".worcs")
    df <- iris[1:5, ]
    open_data(df, codebook = NULL)
  })
}

Description

Remove an endpoint from a WORCS project.

Usage

remove_endpoint(filename = NULL, worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

None, prints to the console.

See Also

add_endpoint snapshot_endpoints

Examples

if(requireNamespace("withr", quietly = TRUE)){
 withr::with_tempdir({
   file.create(".worcs")
   write.csv(iris, "iris.csv")
   add_endpoint("iris.csv")
   list_endpoints()
   remove_endpoint("iris.csv")
   list_endpoints()
 })
}

Description

Evaluate the recipe contained in a WORCS project to derive its endpoints.

Usage

reproduce(worcs_directory = ".", verbose = TRUE, check_endpoints = TRUE, ...)

Arguments

Value

No return value. This function is called for its side effects.

See Also

add_endpoint snapshot_endpoints check_endpoints

Examples

# Create directory to run the example
if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
file.create(".worcs")
worcs:::add_recipe(recipe = 'writeLines("test", "test.txt")')
})
}

Description

Calculate skew and kurtosis, standard errors for both, and the estimates divided by two times the standard error. If this latter quantity exceeds an absolute value of 1, the skew/kurtosis is significant. With very large sample sizes, significant skew/kurtosis is common.

Usage

skew_kurtosis(x, verbose = FALSE, se = FALSE, ...)

Arguments

Value

A matrix of skew and kurtosis statistics for x.

Examples

skew_kurtosis(datasets::anscombe)

Description

Update the checksums of all endpoints in a WORCS project.

Usage

snapshot_endpoints(worcs_directory = ".", verbose = TRUE, ...)

Arguments

Value

No return value. This function is called for its side effects.

See Also

add_endpoint check_endpoints

Examples

# Create directory to run the example
old_wd <- getwd()
test_dir <- file.path(tempdir(), "update_endpoint")
dir.create(test_dir)
setwd(test_dir)
file.create(".worcs")
writeLines("test", "test.txt")
add_endpoint("test.txt")
writeLines("second test", "test.txt")
snapshot_endpoints()
# Cleaning example directory
setwd(old_wd)
unlink(test_dir, recursive = TRUE)

Description

Generates a synthetic version of a data.frame, with similar characteristics to the original. See Details for the algorithm used.

Usage

synthetic(
  data,
  model_expression = ranger(x = x, y = y),
  predict_expression = predict(model, data = xsynth)$predictions,
  missingness_expression = NULL,
  verbose = TRUE
)

Arguments

Details

Based on the work by Nowok, Raab, and Dibben (2016), this function uses a simple algorithm to generate a synthetic dataset with similar characteristics to the original. The algorithm is as follows:

1. Let x be the original data.frame, with columns 1:j

2. Let xsynth be a synthetic data.frame, with columns 1:j

3. Column 1 of xsynth is a bootstrapped version of column 1 of x

4. Using model_expression, a predictive model is built for column c, for c along 2:j, with c predicted from columns 1:(c-1) of the original data.

5. Using predict_expression, columns 1:(c-1) of the synthetic data are used to predict synthetic values for column c.

Variables are thus imputed in order of occurrence in the data.frame. To impute in a different order, reorder the data.

Note that, for data synthesis to work properly, it is essential that the class of variables is defined correctly. The default algorithm ranger supports numeric, integer, and factor types. Other types of variables should be converted to one of these types, or users can use a custom model_expression and predict_expressio when calling synthetic.

Note that for data synthesis to work properly, it is essential that the class of variables is defined correctly. The default algorithm ranger supports numeric, integer, factor, and logical data. Other types of variables should be converted to one of these types.

Users can provide use a custom model_expression and predict_expression to use a different algorithm when calling synthetic.

As demonstrated in the example, users could call lm as a model_expression to use linear regression, which preserves linear marginal relationships but can give rise to values out of range of the original data. Or users could call sample as a predict_expression to bootstrap each variable, a very quick solution that maintains univariate distributions but loses all marginal relationships. These examples are not exhaustive, and users can even create custom functions.

Value

A data.frame with synthetic data, based on data.

References

Nowok, B., Raab, G.M and Dibben, C. (2016). synthpop: Bespoke creation of synthetic data in R. Journal of Statistical Software, 74(11), 1-26. doi:10.18637/jss.v074.i11.

Examples

## Not run: 
# Example using the iris dataset and default ranger algorithm
iris_syn <- synthetic(iris)

# Example using lm as prediction algorithm (only works for numeric variables)
# note that, within the model_expression, a new data.frame is created because
# lm() requires a separate data argument:
dat <- iris[, 1:4]
result <- synthetic(dat,
          model_expression = lm(.outcome ~ .,
                                data = data.frame(.outcome = y,
                                xsynth)),
          predict_expression = predict(model, newdata = xsynth), verbose = FALSE)

## End(Not run)
# Example using bootstrapping:
result <- synthetic(iris,
          model_expression = NULL,
          predict_expression = sample(y, size = length(y), replace = TRUE), verbose = FALSE)
## Not run: 
# Example with missing data, no imputation
iris_missings <- iris
for(i in 1:10){
  iris_missings[sample.int(nrow(iris_missings), 1, replace = TRUE),
                sample.int(ncol(iris_missings), 1, replace = TRUE)] <- NA
}
iris_miss_syn <- synthetic(iris_missings)

# Example with missing data, imputation by median/mode substitution
# First, define a simple function for median/mode substitution:
imp_fun <- function(x){
  if(is.data.frame(x)){
    return(data.frame(sapply(x, imp_fun)))
  } else {
    out <- x
    if(inherits(x, "numeric")){
      out[is.na(out)] <- median(x[!is.na(out)])
    } else {
      out[is.na(out)] <- names(sort(table(out), decreasing = TRUE))[1]
    }
    out
  }
}

# Then, call synthetic() with this function as missingness_expression:
iris_miss_syn <- synthetic(iris_missings,
                           missingness_expression = imp_fun(data))

## End(Not run)

Description

Evaluates whether a project meets the criteria of the WORCS checklist (see worcs_checklist), and adds a badge to the project's README.md.

Usage

worcs_badge(
  path = ".",
  update_readme = "README.md",
  update_csv = "checklist.csv"
)

Arguments

Value

No return value. This function is called for its side effects.

Examples

example_dir <- file.path(tempdir(), "badge")
dir.create(example_dir)
write("a", file.path(example_dir, ".worcs"))
worcs_badge(path = example_dir,
update_readme = NULL)

Description

This checklist can be used to see whether a project adheres to the principles of open reproducible code in science, as set out in the WORCS paper.

Usage

data(worcs_checklist)

Format

A data frame with 15 rows and 5 variables.

Details

References

Van Lissa, C. J., Brandmaier, A. M., Brinkman, L., Lamprecht, A., Peikert, A., , Struiksma, M. E., & Vreede, B. (2021) doi:10.3233/DS-210031.

Description

Construct the path to a file inside a worcs project directory in a platform-independent way, see file.path.

Usage

worcs_path(..., worcs_directory = ".", fsep = .Platform$file.sep)

Arguments

Value

Normalized path to file.

Examples

if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
writeLines("", ".worcs")
writeLines("hello world", "myfile.txt")
file.exists(worcs_path("myfile.txt"))
})
}

Description

Creates a new 'worcs' project. This function is invoked by the 'RStudio' project template manager, but can also be called directly to create a WORCS project through syntax or the console.

Usage

worcs_project(
  path = "worcs_project",
  manuscript = "APA6",
  preregistration = "cos_prereg",
  add_license = "ccby",
  use_renv = TRUE,
  use_targets = FALSE,
  remote_repo = "https",
  verbose = TRUE,
  ...
)

Arguments

Value

No return value. This function is called for its side effects.

Examples

the_test <- "worcs_template"
old_wd <- getwd()
dir.create(file.path(tempdir(), the_test))
do.call(git_user, worcs:::get_user())
worcs_project(file.path(tempdir(), the_test, "worcs_project"),
              manuscript = "github_document",
              preregistration = "None",
              add_license = "None",
              use_renv = FALSE,
              remote_repo = "https")
setwd(old_wd)
unlink(file.path(tempdir(), the_test))

Description

The search starts at path, and recursively proceeds up the directory hierarchy until a worcs project directory is found.

Usage

worcs_root(path = ".")

Arguments

Value

Normalized path of the worcs project root directory.

See Also

find_root

Examples

if(requireNamespace("withr", quietly = TRUE)){
withr::with_tempdir({
writeLines("", ".worcs")
worcs_root()
})
}