Package 'metacheck'

Description

Signal detection values for modules that classify papers as having a feature or not

Usage

accuracy(expected, observed)

Arguments

Value

a list of accuracy parameters

Description

Match table from bib table

Usage

add_bib_match(paper, min_score = 50)

Arguments

Value

the paper or paperlist with bib_match table added

Examples

## Not run: 
paper <- demopaper()
paper$bib_match <- NULL # remove existing
paper2 <- add_bib_match(paper)
paper2$bib_match

## End(Not run)

Description

Retrieve info from AsPredicted by URL

Usage

aspredicted_info(ap_url, id_col = 1, wait = 1)

Arguments

Value

a data frame of information

Description

Find AsPredicted Links in Papers

Usage

aspredicted_links(paper)

Arguments

Value

a table with the AsPredicted url in the first (href) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
aspredicted_links(psychsci)

## End(Not run)

Description

Sends one or more input sentences to a public Gradio app hosted on Hugging Face (the lakens-causal-sentences Space), created based on code by Rasoul Norouzi, retrieves the result via Server-Sent Events (SSE), and returns a tidy data frame with one row per detected cause–effect relation.

Usage

causal_relations(
  sentence,
  rel_mode = "auto",
  rel_threshold = 0.5,
  cause_decision = "cls+span",
  timeout = 10,
  verbose = FALSE
)

Arguments

Details

The function uses Gradio’s two-step queue API: (1) a POST request enqueues the job and returns an event_id; (2) a GET request streams text/event-stream frames until event: complete. Many Gradio apps emit a double-encoded completion payload of the form ⁠["<final JSON string>"]⁠. This function unwraps that to obtain the final JSON structure (an array of items containing causal and relations) before parsing.

If a sentence has no relations, the output includes one row with cause = NA, effect = NA, and the sentence’s causal flag (as returned by the model). For sentences with multiple relations, the function returns one row per relation.

Value

A base data.frame with columns:

• sentence (character): the original input sentence,

• causal (logical): whether the sentence is causal per the model,

• cause (character): extracted cause span (or NA),

• effect (character): extracted effect span (or NA).

References

Norouzi, R., Kleinberg, B., Vermunt, J. K., & van Lissa, C. J. (2025). Capturing causal claims: A fine-tuned text mining model for extracting causal sentences from social science papers. Research Synthesis Methods, 16(1), 139–156. https://doi.org/10.1017/rsm.2024.13

Hugging Face Model Card: rasoultilburg/SocioCausaNet https://huggingface.co/rasoultilburg/SocioCausaNet

Examples

## Not run: 
# Single sentence
df1 <- causal_relations("Smoking causes cancer")
print(df1)

# Multiple sentences (batch)
df2 <- causal_relations(c("Insomnia causes depression.", "Rain leads to flooding."))
print(df2)

# Custom parameters and verbose diagnostics
df3 <- causal_relations(
  sentence = "Stress increases blood pressure.",
  rel_mode = "auto",
  rel_threshold = 0.4,
  cause_decision = "cls+span",
  timeout = 10,
  verbose = TRUE
)
print(df3)

## End(Not run)

Description

Check code for the presence of absolute paths

Usage

code_abs_path(code_text)

Arguments

Value

a vector of absolute paths

Examples

code_text <- c(
  "file <- 'C:/User/lakens/file.R'",
  "tmp <- '/User/lakens/file.html'",
  "convert(file, tmp)"
)
code_abs_path(code_text)

Description

A .ipynb is a JSON document, not a text script: its source lives in the source array of each "code" cell. This concatenates those cells in document order so the result can be checked by the same text-based helpers every other language goes through (code_remove_comments(), code_library_names(), code_file_refs(), ...) — the notebook analogue of code_extract_r() purling an .Rmd/.qmd.

Usage

code_extract_py(file_path = NULL, save_path = NULL, text = NULL)

Arguments

Details

Jupyter is kernel-agnostic, so a notebook's cells may be Python or R (or another language); this extracts the source whatever the kernel, and code_lang() is what reports which language it is. The function is named for the file type it reads, not for a language it assumes.

Markdown and raw cells are dropped (they are prose, not code). Cell boundaries are preserved as blank lines so line counts stay meaningful, and IPython magics (⁠%matplotlib inline⁠) and shell escapes (⁠!pip install x⁠) are dropped: they are not statements in any kernel language and would only ever be noise to the checks downstream.

The OUTPUTS a notebook stores alongside its code are not touched here — see read_stat_tables(), which reads those as result tables the same way it reads a .jasp/.omv archive.

Value

a character vector of source lines (empty when the file has no code cells or is not parseable JSON)

Description

A .qmd whose declared/inferred engine is Python (see code_lang()'s .qmd_lang()) cannot go through code_extract_r(): knitr::purl() only recovers ⁠```{r}⁠ chunks, so a Python-engine document would purl to nothing. This is the .qmd analogue of code_extract_r() for that case — concatenating the body of every ⁠```{python}⁠ fence in document order, the same "recover a checkable code file" idea code_extract_py() applies to a .ipynb's code cells (chunk boundaries are preserved as a blank line so line counts stay meaningful).

Usage

code_extract_qmd_py(file_path = NULL, save_path = NULL, text = NULL)

Arguments

Details

Unlike code_extract_r(), this is a plain text/regex scan, not a real Pandoc/Quarto parse: a fence marker appearing inside a string literal or a displayed (non-executable) code block written with four backticks around a literal ⁠```{python}⁠ would be misread as a real chunk. This mirrors the fence-based approach already used elsewhere in the module (e.g. code_parse_r()'s own ⁠^---\\s*$⁠ front-matter check) rather than introducing a new parsing dependency for a single edge case.

Value

a character vector of Python source lines (empty when the document has no Python chunks)

Description

Convert Rmd/qmd files to R code only

Usage

code_extract_r(
  file_path = NULL,
  save_path = NULL,
  documentation = 0,
  text = NULL
)

Arguments

Value

a character vector

Examples

file_path <- demofile("qmd")
code_text <- code_extract_r(file_path)

Description

Get files referenced in code

Usage

code_file_refs(
  code_text,
  lang = c("R", "Python", "SPSS", "SAS", "Stata", "Mplus", "MATLAB"),
  include_writes = FALSE
)

Arguments

Value

a vector of files that are referenced in the code

Examples

code_text <- c(
  'source("functions.R")',
  'a <- "bread"',
  'b <- read.csv("file.csv")'
)
code_file_refs(code_text, "R")

Description

An install.packages() call in analysis code installs software on whoever runs the script, without asking – a portability and security concern raised in issue #398: at minimum it is disruptive (unexpected installs, network access, a package version the author didn't test against), and at worst a security risk if it points at a private/ untrusted repository. Best practice is to document required packages (a README, a renv.lock/DESCRIPTION) rather than install them from inside the analysis code itself. This scans the (comment-free) code for install.packages(...) calls and returns one row per call, with the argument as written. Only a LIVE call is ever seen here: a commented-out ⁠#install.packages(...)⁠ is invisible to this function by construction, the same way code_setwd() never sees a commented-out setwd() – both are only ever called on code_remove_comments()'s output. R-only (the construct is R's; other languages have their own package managers, which this does not scan).

Usage

code_install_packages(code_text)

Arguments

Value

a data frame with columns install_packages_call (the install.packages(...) text as written) and line (its line number). Empty frame when none are found.

Examples

code_text <- c(
  "install.packages('ggplot2')",
  "library(ggplot2)"
)
code_install_packages(code_text)

Description

Detects code language used in files, only for languages metacheck currently processes (R, SAS, SPSS, Stata, Mplus).

Usage

code_lang(file_name)

Arguments

Value

a vector of languages

Examples

file_name <- "file.R"
code_lang(file_name)

file_name <- c("file.Rmd", "file.SAS", "file.r", "file.qmd", "file.txt")
code_lang(file_name)

Description

Returns the lines on which library/require calls exist. This is a helper function for the code_check module.

Usage

code_library_lines(
  code_text,
  lang = c("R", "Python", "SPSS", "SAS", "Stata", "Mplus", "MATLAB")
)

Arguments

Value

a data frame with columns code and line (the line numbers on which library calls exist, after removing blank lines and comments)

Examples

code_text <- c(
  "library(dplyr)",
  "",
  "# this line won't count",
  "library(tidyr)",
  "renv::install('metacheck')"
)
code_library_lines(code_text, "R")

Description

Extracts the names of the packages/libraries a code file loads. Where code_library_lines() only reports the lines on which imports occur (to check they are grouped), this returns the actual package identifiers so they can be catalogued and searched, or written to a requirements.txt.

Usage

code_library_names(
  code_text,
  lang = c("R", "Python", "SPSS", "SAS", "Stata", "Mplus", "MATLAB")
)

Arguments

Details

For R this captures library() / require() / requireNamespace() (bare or quoted argument), pacman's p_load() (which may list several packages at once), namespace-qualified calls (pkg::fun / pkg:::fun), and install.packages() / renv::install(). For Python it captures ⁠import a⁠, ⁠import a as b⁠, ⁠import a, b⁠, and ⁠from a.b import c⁠ (recording the top-level package a). SAS / SPSS / Stata have no package concept, so an empty frame is returned.

The extraction is regex-based (like the rest of the module) so it degrades gracefully on files that will not parse. It can therefore miss dynamically constructed package names, and does not know which version was used — only the names appear in the source.

Where a call takes a variable rather than a package name — install.packages(pkgs), requireNamespace(pkg), library(pkg, character.only = TRUE), lapply(pkgs, library, ...) — the variable is resolved to the names it holds when the file assigns it a literal vector (pkgs <- c("a", "b"), including a ⁠for (pkg in pkgs)⁠ loop variable), and dropped otherwise. The variable's own name is never reported as a package.

Value

a data frame with columns package, source (how the package was referenced: library, require, requireNamespace, p_load, namespace, install, or import), and line (the line number). Rows are unique on package + source + line. An empty frame (same columns) when none found.

Examples

code_text <- c(
  "library(dplyr)",
  "require('tidyr')",
  "pacman::p_load(ggplot2, readr)",
  "x <- stringr::str_trim(' a ')"
)
code_library_names(code_text, "R")

Description

Get Code Composition Stats

Usage

code_line_stats(
  code_text,
  lang = c("R", "Python", "SPSS", "SAS", "Stata", "Mplus", "MATLAB")
)

Arguments

Value

list with items total_lines, comment_lines, code_lines, percent_comment, and (Python only) has_docstring

Examples

code_text <- c(
  "library(dplyr)",
  "",
  "# this line is a comment",
  "a <- 1"
)
code_line_stats(code_text, "R")

Description

The code_check module stores the packages each code file loads as a comma-joined string in its table$packages column. This returns the sorted, de-duplicated union across a set of those rows — the paper-level dependency list used for the module summary, the manifest code section, and the requirements.txt written into a Psych-DS archive by convert_psychds().

Usage

code_packages(packages)

Arguments

Value

a sorted character vector of distinct package names (possibly empty)

Examples

code_packages(c("dplyr, ggplot2", "", "dplyr, tidyr"))

Description

Parse code to check for errors

Usage

code_parse_r(file_path = "", text = NULL)

Arguments

Value

a data frame with columns file_path and line

Examples

file_path <- demofile("qmd")
code_parse_r(file_path)

Description

Read code from files

Usage

code_read(file_path)

Arguments

Value

a character vector of the file contents

Examples

file_path <- demofile("json")
text <- code_read(file_path)

Description

Remove comments from code text

Usage

code_remove_comments(
  code_text,
  lang = c("R", "Python", "SPSS", "SAS", "Stata", "Mplus", "MATLAB")
)

Arguments

Value

the code_text minus comment lines

Examples

code_text <- c(
  "# this is a comment",
  "",
  "x <- 'And this is code'"
)
code_text_nc <- code_remove_comments(code_text, "R")

Description

A setwd() call in analysis code is a portability problem: it hardcodes an assumption about the working directory the code runs in (frequently an absolute path on the author's own machine), mutates global state, and makes a script depend on being run from a particular place. Best practice is to keep the working directory as the caller sets it and use relative paths. This scans the (comment-free) code for setwd(...) calls and returns one row per call, with the argument as written. R-only (the construct is R's; other languages have their own, e.g. Stata cd, which this does not scan).

Usage

code_setwd(code_text)

Arguments

Value

a data frame with columns setwd_call (the setwd(...) text as written) and line (its line number). Empty frame when none are found.

Examples

code_text <- c(
  "setwd('D:/Dropbox/project')",
  "x <- read.csv('data.csv')"
)
code_setwd(code_text)

Description

A helper function for making module reports.

Usage

collapse_section(
  text,
  title = "Learn More",
  callout = c("tip", "note", "warning", "important", "caution"),
  collapse = TRUE
)

Arguments

Details

When report_type() is "simple" or "simple_brief", this renders as a plain fenced div with the title as a real bold line of text, not a Quarto callout: Quarto's title/collapse fenced-div attributes are Quarto-specific – plain Pandoc (what report()'s simple-mode render uses, see its own docs) passes an unrecognised attribute straight through as a literal (invisible) HTML attribute rather than rendering it as content, and expanding/collapsing needs Bootstrap's collapse JavaScript, which a simple report never includes. The content is always shown inline, uncollapsed. In a "checklist" report it is a ⁠<details>⁠ box instead, which folds without JavaScript.

Value

text

Examples

text <- c("Paragraph 1...", "Paragraph 2...")
collapse_section(text) |> cat()

Description

Uses grobid or bibr to convert a file to paper format.

Usage

convert(
  file_path,
  save_path = ".",
  method = c("auto", "bibr", "grobid", "xml"),
  crossref_lookup = FALSE,
  keep_xml = TRUE,
  ...
)

Arguments

Details

Both bibr and grobid can handle PDF files. Only bibr can convert doc or docx files. Already-converted grobid XML files can be converted to bibr format (set crossref_lookup=TRUE to add a bib_match table). If the file_path is a directory, the method will be xml if any XML files are present, and bibr if only doc or docx files are present.

With method "auto" or "bibr", PDF files are converted with bibr on metacheck's API on SURF Research Cloud (see convert_bibr) when it is available, unless api_url, api_key or backend is given, or there are doc or docx files. Otherwise the method "auto" uses a local grobid (http://localhost:8070), then a local bibr (http://localhost:8000), then the first available server in the online list at https://www.scienceverse.org/metacheck/convert.json.

Value

the path to the JSON file

Description

Converts document files (PDF, DOC, DOCX) to structured JSON using the bibr extraction service. Supports three backends: metacheck's API on SURF Research Cloud ("surf"), which converts PDF files and needs no API key; the Scienceverse platform ("scivrs") which uses a job queue with load balancing; and a self-hosted bibr instance ("selfhosted") for direct API access.

Usage

convert_bibr(
  file_path,
  save_path = ".",
  backend = c("auto", "surf", "scivrs", "selfhosted"),
  api_key = NULL,
  api_url = NULL,
  include_figures = FALSE,
  start_page = 1,
  end_page = Inf,
  poll_interval = 2,
  timeout = 600
)

Arguments

Details

When backend = "auto" (the default), the "scivrs" backend is used if api_key is provided or the SCIVRS_API_KEY environment variable is set, and "selfhosted" if api_url is provided or the BIBR_API_URL environment variable is set. Otherwise, "surf" is used.

The "surf" backend sends the PDF to the /convert endpoint of metacheck's API on SURF Research Cloud, whose address can be set with the SURF_API_URL environment variable. It converts only PDF files (at most 50 MB), always whole and without figures, so include_figures, start_page and end_page do not apply. The server deletes the upload once it is converted, and the result an hour later.

A self-hosted bibr server that requires authentication (bibr serve with AUTH_API_KEY set, as on a SURF Research Cloud workspace) gets its bearer token from api_key or the BIBR_API_KEY environment variable; its address can be set with BIBR_API_URL.

Value

Path(s) to the saved JSON file(s)

Examples

## Not run: 
# Auto-detect backend from environment variables
pdf <- demofile("pdf")
convert_bibr(pdf)

# Explicitly use metacheck's API on SURF Research Cloud
convert_bibr(pdf, backend = "surf")

# Explicitly use Scienceverse platform
convert_bibr(pdf, backend = "scivrs")

# Use self-hosted bibr instance
convert_bibr(pdf, backend = "selfhosted")

# Extract specific pages
convert_bibr(pdf, start_page = 1, end_page = 10)

# Directory of papers
dir <- system.file("demo", package = "metacheck")
convert_bibr(dir, save_path = "results/")

## End(Not run)

Description

This function uses a GDPR-compliant public grobid server maintained by Eindhoven Technical University. You can set up your own local grobid server following instructions from https://grobid.readthedocs.io/ and set the argument api_url to its path (probably http://localhost:8070). See https://github.com/grobidOrg/grobid#demo for other publicly available servers (we cannot guarantee their privay).

Usage

convert_grobid(
  file_path,
  save_path = ".",
  api_url = "https://grobid.hti.ieis.tue.nl",
  start_page = -1,
  end_page = -1,
  consolidate_citations = 0,
  consolidate_header = 0,
  consolidate_funders = 0
)

Arguments

Details

Consolidation of citations, headers, and funders looks up these items in CrossRef or another database to fix or enhance information (see https://grobid.readthedocs.io/en/latest/Consolidation/). This can slow down conversion. Consolidating headers is only useful for published papers, and can be set to 0 for work in prep. We recommend you leave these defaults at 0 and use crossref_loookup = TRUE when converting from grobid XML to bibr JSON format with the convert() function.

Value

XML object

Description

Valid selects for crossref API are:

Usage

crossref_doi(
  doi,
  select = c("DOI", "type", "title", "author", "container-title", "volume", "issue",
    "page", "URL", "abstract", "year", "error")
)

Arguments

Details

abstract, URL, resource, member, posted, score, created, degree, update-policy, short-title, license, ISSN, container-title, issued, update-to, issue, prefix, approved, indexed, article-number, clinical-trial-number, accepted, author, group-title, DOI, is-referenced-by-count, updated-by, event, chair, standards-body, original-title, funder, translator, published, archive, published-print, alternative-id, subject, subtitle, published-online, publisher-location, content-domain, reference, title, link, type, publisher, volume, references-count, ISBN, issn-type, assertion, deposited, page, content-created, short-container-title, relation, editor

Value

data frame with DOIs and info

Examples

doi <- "10.7717/peerj.4375"
## Not run: 
# cr_info <- crossref_doi(doi)

## End(Not run)

Description

Look up Reference in CrossRef

Usage

crossref_query(
  ref,
  min_score = 50,
  rows = 1,
  select = c("DOI", "score", "type", "title", "author", "editor", "publisher",
    "container-title", "year", "volume", "issue", "page", "URL")
)

Arguments

Details

The argument ref can take many formats. Crossref queries only look for authors, title, and container-title (e.g., journal or book), but extra information doesn't seem to hurt.

• a text reference or fragment

• a bibentry object (authors, title and container will be extracted)

• a vector of text or bibentry objects

• a paper object (the bib table will be extracted)

Valid selects for this route are: abstract, URL, resource, member, posted, score, created, degree, update-policy, short-title, license, ISSN, container-title, issued, update-to, issue, prefix, approved, indexed, article-number, clinical-trial-number, accepted, author, group-title, DOI, is-referenced-by-count, updated-by, event, chair, standards-body, original-title, funder, translator, published, archive, published-print, alternative-id, subject, subtitle, published-online, publisher-location, content-domain, reference, title, link, type, publisher, volume, references-count, ISBN, issn-type, assertion, deposited, page, content-created, short-container-title, relation, editor

Value

doi

Examples

ref <- paste(
  "Lakens, D., Mesquida, C., Rasti, S., & Ditroilo, M. (2024).",
  "The benefits of preregistration and Registered Reports.",
  "Evidence-Based Toxicology, 2(1)."
)
## Not run: 
cr <- crossref_query(ref)

## End(Not run)

Description

Doi.org Info from DataCite

Usage

datacite_doi(doi)

Arguments

Value

bib_match data frame

Examples

doi <- "10.5281/zenodo.2669586"
## Not run: 
doi_info <- datacite_doi(doi)

## End(Not run)

Description

Retrieve info from DataONE by URL

Usage

dataone_info(dataone_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information

Examples

## Not run: 
  dataone_info("https://doi.org/10.18739/A2GT5FG86")

## End(Not run)

Description

Get all DataONE links: real hyperlinks from the paper's own url table, plus a body-text fallback for a BARE DOI mention (routinely cited without any URL scheme at all) using the DOI prefixes of known hosts (see .dataone_hosts()) – the url table only ever contains links the source document itself made clickable. Same two-tier approach zenodo_links() uses.

Usage

dataone_links(paper)

Arguments

Details

Unlike the single-host archive modules, a DataONE citation only resolves to a specific member node's own API (see the file-level note in archive-dataone.R) – a host neither listed by domain nor identifiable by its DOI prefix is not one this package can currently query, even if it is a real DataONE member node.

Value

a table with the DataONE url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
dataone_links(psychsci)

## End(Not run)

Description

Creates a directory for the dataset and downloads all of its files. Returns (invisibly) a data frame with file info.

Usage

dataverse_file_download(
  host,
  doi,
  download_to = ".",
  max_file_size = 10,
  max_download_size = 100,
  unzip_types = NULL,
  pb = NULL
)

Arguments

Details

You can limit downloads to only files under a specific size (defaults to 10MB) and only a maximum download size (largest files will be omitted until total size is under the limit). Omitted files will be listed as messages in verbose mode, and included in the returned data frame with the downloaded column value set to FALSE.

A .zip in the dataset is normally fetched whole and left as a zip. Set unzip_types to pull only the files you want out of it instead: Dataverse's file-download endpoint honours byte-range requests (verified 2026-08-14 against demo.dataverse.org: HEAD/Range both return Accept-Ranges: bytes and a ⁠206 Partial Content⁠ response) and each member of a zip is compressed separately, so the wanted members can be read out of the archive while the rest is never transferred – the same mechanism zenodo_file_download() uses. When the archive cannot be read that way, it is downloaded whole as before, so this never loses a file – it only avoids transferring one.

Value

data frame of file info. When members are extracted from a zip, its row reports the zip with extracted giving the number of members written; size_on_disk and checksum_ok are then NA, because what is on disk is the members rather than the archive Dataverse published a size and MD5 for.

Examples

## Not run: 
  dataverse_file_download("dataverse.harvard.edu", "10.7910/DVN/GGDUND")

  # take only the data files out of any zip in the dataset
  dataverse_file_download("dataverse.harvard.edu", "10.7910/DVN/GGDUND",
                          unzip_types = "data")

## End(Not run)

Description

Retrieve info from Dataverse by URL

Usage

dataverse_info(dataverse_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information

Examples

## Not run: 
  dataverse_info("https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/GGDUND")

## End(Not run)

Description

Get all Dataverse links: real hyperlinks from the paper's own url table, matched against a list of known Dataverse installations (see dataverse_links()'s source for the list; Dataverse is open-source software run by many independent hosts, unlike Zenodo, so there is no single hostname or DOI prefix to match against everything). Same two-tier hyperlink + bare-mention approach zenodo_links() uses, applied per known host.

Usage

dataverse_links(paper)

Arguments

Value

a table with the Dataverse url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
dataverse_links(psychsci)

## End(Not run)

Description

Dataverse installations each issue their own API token (unlike Zenodo/OSF, which are single services) – a token from dataverse.harvard.edu is meaningless to dataverse.nl. Tokens are therefore stored per host.

Usage

dataverse_pat(host, pat = NULL)

Arguments

Details

Create a token by signing in to the installation, opening your account page, and selecting "API Token".

Store it as an environment variable named ⁠DATAVERSE_PAT_<HOST>⁠, with the host uppercased and every . replaced by ⁠_⁠ (e.g. DATAVERSE_PAT_DATAVERSE_HARVARD_EDU), so it is read every time R starts.

Value

the current token (character; "" when none is set)

Examples

dataverse_pat("dataverse.harvard.edu") # returns "" unless a token is set

Description

Return the file path for various versions of the demo paper. Use demopaper() to directly read it as a paper object from the json file.

Usage

demofile(ext = c("json", "pdf", "docx", "doc", "xml", "qmd"))

Arguments

Value

file path

Examples

json <- demofile()
pdf <- demofile("pdf")

Description

Get demo paper

Usage

demopaper()

Value

paper object

Examples

paper <- demopaper()

Description

Clean DOIs

Usage

doi_clean(doi)

Arguments

Value

a character vector of cleaned DOIs (no https://doi.org or DOI:)

Examples

doi_clean("https://doi.org/10.1038/nphys1170")
doi_clean("doi:10.1038/nphys1170")
doi_clean("DOI: 10.1038/nphys1170")

Description

Doi.org Info from DOI

Usage

doi_lookup(doi)

Arguments

Value

data frame with DOIs and info

Examples

doi <- "10.7717/peerj.4375"
## Not run: 
doi_info <- doi_lookup(doi)

## End(Not run)

Description

Checks the doi.org API to see if a DOI is registered and has an associated URL (using ⁠https://doi.org/api/handles⁠). Returns TRUE if it does, FALSE if the DOI does not exist or does not have an associated URL, and NA if the test failed. Clearly invalid DOIs (i.e. not starting with "10.") will return FALSE without server requests.

Usage

doi_resolves(doi, timeout = 10)

Arguments

Value

Logical vector. For each input DOI, returns TRUE if the DOI resolves, FALSE if it does not resolve (or does not start with 10.), and NA if the check failed.

Examples

## Not run: 
doi_resolves("10.1038/nphys1170") # Expected: TRUE
doi_resolves("10.1234/invalid.doi") # Expected: FALSE

## End(Not run)

Description

Validate DOI format

Usage

doi_valid_format(doi)

Arguments

Value

a logical vector

Examples

doi_valid_format("10.1038/nphys1170")
doi_valid_format("no.no.10.1038")

Description

Dryad also issues a client id/secret pair (from the same account settings page as the plain token in dryad_pat()), meant for the OAuth2 client-credentials grant. Unlike a plain token, which expires after 10 hours and must be regenerated by hand, a client id/secret is exchanged for a short-lived access token automatically – and refreshed automatically, for as long as the credentials themselves stay valid – every time a request needs one, via httr2::req_oauth_client_credentials(). This is the right choice for a long-running corpus build; dryad_pat() remains available for a single quick session where generating a client id/secret is not worth the extra step.

Usage

dryad_auth(
  client_id = NULL,
  client_secret = NULL,
  token_url = "https://datadryad.org/oauth/token"
)

Arguments

Details

Store client_id/client_secret as the DRYAD_CLIENT_ID/ DRYAD_CLIENT_SECRET environment variables so they are read every time R starts, the same way dryad_pat() reads DRYAD_PAT.

Value

invisibly, the httr2::oauth_client() built from the current credentials, or NULL when none are set

Examples

## Not run: 
dryad_auth("my-client-id", "my-client-secret")

## End(Not run)

Description

Creates a directory for the dataset and downloads all of its files. Returns (invisibly) a data frame with file info.

Usage

dryad_file_download(
  dryad_doi,
  download_to = ".",
  max_file_size = 10,
  max_download_size = 100,
  unzip_types = NULL,
  pb = NULL
)

Arguments

Details

A Dryad API token (see dryad_pat()) is REQUIRED to download file bytes, even from a fully public dataset – unlike figshare_file_download(), dataverse_file_download(), or zenodo_file_download(). Without one set, every file in the returned table has downloaded = FALSE: the dataset can still be listed (see dryad_info()), but nothing can be fetched.

You can limit downloads to only files under a specific size (defaults to 10MB) and only a maximum download size (largest files will be omitted until total size is under the limit). Omitted files will be listed as messages in verbose mode, and included in the returned data frame with the downloaded column value set to FALSE.

A .zip in the dataset is normally fetched whole and left as a zip. Set unzip_types to pull only the files you want out of it instead, the same as dataverse_file_download() and zenodo_file_download() do.

Value

data frame of file info. When members are extracted from a zip, its row reports the zip with extracted giving the number of members written; size_on_disk and checksum_ok are then NA, because what is on disk is the members rather than the archive Dryad published a size and digest for.

Examples

## Not run: 
  dryad_file_download("10.5061/dryad.j1fd7")

  # take only the data files out of any zip in the dataset
  dryad_file_download("10.5061/dryad.j1fd7", unzip_types = "data")

## End(Not run)

Description

Retrieve info from Dryad by URL

Usage

dryad_info(dryad_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information, one row per link, with the dataset's metadata, its file records in the list column files, and storage_size (the dataset's total size in bytes as Dryad reports it), files_total (the number of files Dryad reports), and files_incomplete (TRUE when fewer files could be listed than Dryad reports; a warning is given too). A sharing link (datadryad.org/stash/share/...) is followed to the dataset it leads to; one that leads nowhere has its reason in error, as a dataset that could not be found does.

Examples

## Not run: 
  dryad_info("https://doi.org/10.5061/dryad.j1fd7")

## End(Not run)

Description

Get all Dryad links: real hyperlinks from the paper's own url table, plus a body-text fallback for a BARE mention (a DOI like "10.5061/dryad.j1fd7" is routinely cited without any URL scheme at all) that the source PDF/HTML never encoded as an actual hyperlink – the url table only ever contains links the source document itself made clickable. Same two-tier approach zenodo_links() uses.

Usage

dryad_links(paper)

Arguments

Value

a table with the Dryad url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
dryad_links(psychsci)

## End(Not run)

Description

Dryad issues OAuth2 bearer tokens from account settings. Unlike Figshare, Dataverse, Zenodo, and OSF, a token is REQUIRED to download file bytes even from a fully public dataset (verified live 2026-08-16: both the per-file and whole-dataset download endpoints answer 401 with no token, though dataset metadata and file listings are readable without one). Without a token, dryad_file_download() can list what a dataset contains but cannot fetch any of it.

Usage

dryad_pat(pat = NULL)

Arguments

Details

This token expires after 10 hours and must be regenerated by hand from Dryad's account settings – for a long corpus run, dryad_auth() avoids this by exchanging a client id/secret for a token automatically, with no manual re-entry. When client credentials are set via dryad_auth(), they take priority over this token.

Store it as the DRYAD_PAT environment variable so it is read every time R starts.

Value

the current token (character; "" when none is set)

Examples

dryad_pat() # returns "" unless a token is set

Description

Get all links to any of the legacy-DSpace-REST installations in .dspace_legacy_hosts() (PsychArchives plus the others verified 2026-09-11 – see the note at the top of this file): real hyperlinks from the paper's own url table, plus a body-text fallback. The fallback recognises a bare mention (no hostname attached) only for PsychArchives' own handle prefix (20.500.12034) – see .dspace_legacy_parse() for why the other installations' bare mentions cannot be resolved the same way. This is the general (all-hosts) counterpart to psycharchives_links(), which stays PsychArchives-only for anyone calling it directly.

Usage

dspace_links(paper)

Arguments

Value

a table with the DSpace url in the first (href) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
dspace_links(psychsci)

## End(Not run)

Description

Lists the publicly retrievable files (the item's ORIGINAL bundle) of one or more DSpace 7 items via the REST API, without downloading them. Each row carries an absolute file_url so the actual bytes are fetched later by download_repo_files, the same deferred path used for Zenodo, OSF, and legacy DSpace (psycharchives_file_download()).

Usage

dspace7_file_download(dspace7_url, pb = NULL)

Arguments

Value

a data frame of file information (one row per public file)

Description

Get all links to any of the DSpace 7 (or later) installations in .dspace7_hosts() – see the note at the top of this file for how they were found and why they need a separate implementation from dspace_links() (legacy DSpace, archive-psycharchives.R). Real hyperlinks from the paper's own url table, plus a body-text fallback for a bare mention that still carries one of these hosts (a bare handle prefix with no host at all cannot be attributed to a specific installation – see .dspace7_parse()).

Usage

dspace7_links(paper)

Arguments

Details

A DOI mentioned in the text is also looked up, and kept when it leads to one of these installations. The paper's own DOI, and DOIs under a prefix that another detector handles and no DSpace 7 installation uses (see .dspace7_skip_doi_prefixes()), are not looked up. The lookup reads the URL registered for the DOI from doi.org's handle API rather than visiting the landing page, and each DOI is looked up once per R session.

Value

a table with the DSpace 7 url in the first (href) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
dspace7_links(psychsci)

## End(Not run)

Description

Get or set the contact email metacheck sends with requests to external APIs (e.g. Crossref's polite pool), so a host that needs to reach you about your usage can do so. Call with no argument to read the current value; call with a valid email address to set it for the rest of the session. Defaults to "[email protected]" when never set.

Usage

email(email = NULL)

Arguments

Value

the current option value (character)

Examples

email()

Description

Useful emojis

Usage

emojis

Format

An object of class list of length 32.

Details

• General: "check", "star", warning", "stop", "x", "no", "thumbs_up", "thumbs_down", "info", "question"

• Traffic Lights: "tl_green", "tl_yellow", "tl_red", "tl_info", "tl_na", "tl_fail"

• Hearts: "red", "orange", "yellow", "green", "blue", "purple", "brown", "black", "white", "pink"

Description

A .jasp archive already bundles a fully rendered index.html – JASP's own output view, complete with result tables and any plots – alongside the data (see the file header). This extracts that index.html as-is and inlines every plot it references (an ⁠<img src="resources/.../*.png">⁠) as a base64 ⁠data:⁠ URI, so the result is a single, portable, self-contained file that looks exactly like JASP's own output window, with no external image files to keep alongside it.

Usage

export_jasp_html(path, out = NULL)

Arguments

Value

the path written to, invisibly

Description

Builds an HTML page from what import_mplus_output() already decodes: one heading per section (⁠SUMMARY OF ANALYSIS⁠, ⁠MODEL FIT INFORMATION⁠, ⁠MODEL RESULTS⁠, ...) and one ⁠<table>⁠ per detected result. Like export_stata_smcl_html(), this has no figures to embed: Mplus never writes chart data into the .out text file itself (see the file header).

Usage

export_mplus_html(path, out = NULL)

Arguments

Value

the path written to, invisibly

Description

A .omv archive already bundles a fully rendered index.html – jamovi's own output view, complete with result tables and any plots – alongside the data (see the file header). This extracts that index.html as-is and inlines every plot it references (an ⁠<img src="....png">⁠ under one of the per-analysis ⁠resources/⁠ folders) as a base64 ⁠data:⁠ URI, so the result is a single, portable, self-contained file that looks exactly like jamovi's own output window, with no external image files to keep alongside it.

Usage

export_omv_html(path, out = NULL)

Arguments

Value

the path written to, invisibly

Description

Unlike .jasp/.omv, a .spv archive carries no rendered view of its own (see the file header) – so, unlike export_jasp_html() and export_omv_html(), this does not re-export an existing document. It builds a new HTML page from what import_spv() already decodes: one heading per analysis (its recovered SPSS syntax shown underneath, when recoverable), one ⁠<table>⁠ per result table, and – for a chart entry (import_spv()'s is_chart = TRUE) – a scatter plot rendered from its own decoded ⁠(x, y)⁠ points with any fitted trend lines SPSS itself computed drawn over it (see .spv_decode_chart()), embedded as a base64 PNG the same way export_jasp_html() inlines its own plots.

Usage

export_spv_html(path, out = NULL)

Arguments

Value

the path written to, invisibly

Description

Builds an HTML page from what import_stata_smcl() already decodes: one heading per Stata command (its exact syntax, since a .smcl command echo IS the syntax) and one ⁠<table>⁠ per detected result. Unlike export_jasp_html()/export_omv_html() (which re-export an already-rendered view) or export_spv_html() (which renders decoded charts as images), this has no figures to embed at all: a .smcl file never contains chart image data (see the file header) – a ⁠graph export⁠ command is shown as recovered command text only.

Usage

export_stata_smcl_html(path, out = NULL)

Arguments

Value

the path written to, invisibly

Description

List all equations in the text, returning the matched text (e.g., 't(28) = 2.4', 'p = 0.04') and document location in a table. This is the canonical extractor for reported statistics and effect sizes; modules that need statistics should read from this table rather than re-scanning the text.

Usage

extract_eq(paper)

Arguments

Details

This will catch most comparators like =<>~and most versions of scientific notation like 5.0 x 10^-2 or 5.0e-2. If you find any formats that are not correctly handled by this function, please contact the author.

Value

a data frame with one row per equation and the columns lhs (the statistic name, e.g. "t", "F", "p"), df (parenthetical degrees of freedom such as "(28)" or "(2, 57)", otherwise NA), comp (the comparator, e.g. "="), rhs (the reported value as text), grp_id (groups equations in the same sentence), text_id, and paper_id.

Examples

paper <- demopaper()
equations <- extract_eq(paper)

Description

List all p-values in the text, returning the matched text (e.g., 'p = 0.04') and document location in a table.

Usage

extract_p_values(paper)

Arguments

Details

Note that this will not catch p-values reported like "the p-value is 0.03" because that results in a ton of false positives when papers discuss p-value thresholds. If you need to detect text like that, use the text_search() function and a custom pattern.

This will catch most comparators like =<>~ and most versions of scientific notation like 5.0 x 10^-2 or 5.0e-2. If you find any formats that are not correctly handled by this function, please contact the author.

Value

a table

Examples

paper <- demopaper()
p_values <- extract_p_values(paper)

Description

Builds the paper-side counterpart to the analysis output that reproducibility_check extracts: one row per reported TEST, with its components kept together and the sentence it was reported in retained, so a matched result can be traced back to the claim it supports.

Usage

extract_tests(paper)

Arguments

Details

This is a purpose-built alternative to extract_eq() for matching. It reuses extract_eq()'s parsing of ⁠name <op> value⁠ fragments, then does three things that parsing does not:

• isolates separate tests within one sentence. extract_eq()'s grp_id is the sentence number, so a sentence reporting two t-tests yields a single ten-component "test" that no analysis can produce; here a repeated anchor (a second t, F, r, ...) starts a new test;

• keeps the sentence, its text_id, paragraph_id and section_id, so a match links a result_id to the sentence making the claim;

• filters non-statistics, so a figure's height = 4 or a sample's range = 18-29 is not offered as evidence. A run of components with no recognised test statistic in it is dropped entirely.

Value

a data.frame, one row per reported test, with paper_id, test_no (sequential within the paper), text_id, paragraph_id, section_id, sentence (the reporting sentence), anchor (the test statistic the report is built around, e.g. "t"), n_components, components (a list-column of name/comp/value/df), and reported (the test rendered back as text, e.g. "t(23) = 3.77, p = .001, d = 0.77").

Description

Get a table of URLs from a paper or paperlist. Matches urls that start with http or doi:

Usage

extract_urls(paper)

Arguments

Value

a table

Examples

paper <- demopaper()
urls <- extract_urls(paper)

Description

View a figure image

Usage

fig_image_view(paper, figure_id = 1)

Arguments

Value

plots the figure

Examples

paper <- demopaper()
fig_image_view(paper, 1)
fig_image_view(paper, 2)

Description

Creates a directory for the article and downloads all of its files. Returns (invisibly) a data frame with file info.

Usage

figshare_file_download(
  figshare_id,
  download_to = ".",
  max_file_size = 10,
  max_download_size = 100,
  unzip_types = NULL,
  host = "api.figshare.com",
  pb = NULL
)

Arguments

Details

Files are downloaded one by one, each from its own download_url. Figshare does document a whole-article zip (GET /v2/articles/{id}/download, which redirects to ⁠ndownloader.figshare.com/articles/<id>/versions/<v>⁠ and serves application/zip with a Content-Length, verified 2026-10-13), but it is not used here: it always contains every file, so it cannot honour the size limits below, and how it lays out files kept in folders was not verified. Files in folders (Figshare's folder_structure) are saved under those folders. A .zip already present in the article is handled the same way dataverse_file_download() handles one: fetched whole and left as a zip unless unzip_types asks for only specific members out of it.

You can limit downloads to only files under a specific size (defaults to 10MB) and only a maximum download size (largest files will be omitted until total size is under the limit). Omitted files will be listed as messages in verbose mode, and included in the returned data frame with the downloaded column value set to FALSE.

Value

data frame of file info. When members are extracted from a zip, its row reports the zip with extracted giving the number of members written; size_on_disk and checksum_ok are then NA, because what is on disk is the members rather than the archive Figshare published a size and MD5 for.

Examples

## Not run: 
  figshare_file_download("18093368")

  # take only the data files out of any zip in the article
  figshare_file_download("18093368", unzip_types = "data")

## End(Not run)

Description

Retrieve info from Figshare by URL

Usage

figshare_info(
  figshare_url,
  id_col = 1,
  host = "api.figshare.com",
  pb = NULL,
  cache = FALSE
)

Arguments

Value

a data frame of information

Examples

## Not run: 
  figshare_info("https://doi.org/10.6084/m9.figshare.18093368.v1")

## End(Not run)

Description

Get all Figshare links: real hyperlinks from the paper's own url table, plus a body-text fallback for a BARE mention (a DOI like "10.6084/m9.figshare.1234567" is routinely cited without any URL scheme at all) that the source PDF/HTML never encoded as an actual hyperlink – the url table only ever contains links the source document itself made clickable. Same two-tier approach zenodo_links() uses.

Usage

figshare_links(paper)

Arguments

Value

a table with the Figshare url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
figshare_links(psychsci)

## End(Not run)

Description

Figshare issues personal access tokens from account settings (https://figshare.com/account/applications). A token is optional for reading public articles and is used here only to read private ones (it does not raise any request limit: Figshare documents no automatic rate limiting and asks for at most 1 request per second either way), unlike Dataverse where a token is per-installation.

Usage

figshare_pat(pat = NULL)

Arguments

Details

Store it as the FIGSHARE_PAT environment variable so it is read every time R starts.

Value

the current token (character; "" when none is set)

Examples

figshare_pat() # returns "" unless a token is set

Description

Categorise files

Usage

file_category(contents)

Arguments

Value

the table with new column file_category

Examples

contents <- c("script.R", "data.csv", "README", "codebook.csv")
file_category(contents)

Description

Get file Type from Extension

Usage

filetype(filename)

Arguments

Value

a named vector of file types

Examples

filetype("script.R")

Description

FLoRA database containing DOIs of original studies and replications. Use FLoRA_date() to find the date it was downloaded, and FLoRA_update() to update it.

Usage

FLoRA()

Format

A data frame with 8 columns:

doi_o

DOI of original study

apa_ref_o

APA reference of original study

doi_r

DOI of replication study (may be NA if url_r is provided)

apa_ref_r

APA reference of replication study

url_r

URL of replication study (used when DOI is not available)

outcome

replication outcome

outcome_quote

quote describing replication outcome

type

replication or reproduction

Value

a data frame

Source

https://osf.io/9r62x/files/t4j8f

Examples

FLoRA()

Description

Get date FLoRA was updated

Usage

FLoRA_date()

Value

the date

Examples

FLoRA_date()

Description

metacheck comes with a built-in data frame called FLoRA. We update it regularly, but you can use this function to download the newest version. The download is >5MB, but this function will summarise the information into a smaller version and delete the original file.

Usage

FLoRA_update()

Value

the path to the data frame (invisibly)

Description

Formats a structured author list (data frame with given/family columns) as a display string.

Usage

format_bib_authors(authors)

Arguments

Value

a character string (or vector) of formatted author names

Examples

authors <- data.frame(given = c("Alice H.", "Wendy"),
                      family = c("Eagly", "Wood"))
format_bib_authors(authors)

Description

Format a reference for display in a report.

Usage

format_ref(bib)

Arguments

Details

The argument bib should be a bibentry object (e.g., like those made by citation(), but it can also handle a bibtex object or a bibtex formatted character vector. If these do not read in as valid bibtex, the original text of bib will be returned unformatted.

Value

formatted text

Examples

mc <- citation("metacheck")
format_ref(mc)

# handles bibtext
bib_mc <- utils::toBibtex(mc)
format_ref(bib_mc)

paper <- demopaper()
format_ref(paper$bib$ref[1:2])

Description

Lists a Finnish Social Science Data Archive study's title, DOI, access restriction, and data-file inventory (name, format, case/variable counts) via its open DDI-C 2.5 XML metadata record. There is no file-level download here – the DDI record carries no download URI, and actual data access requires Haka/Aila login or a per-dataset access application (see the file header comment) – so files is for REPORTING what a study contains, not for download_repo_files() to fetch.

Usage

fsd_info(fsd_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information

Examples

## Not run: 
fsd_info("https://services.fsd.tuni.fi/catalogue/FSD2653")

## End(Not run)

Description

Get all Finnish Social Science Data Archive (FSD / Aila Data Service) links: real hyperlinks from the paper's own url table (the catalogue page, a 10.60686 DOI, or a urn.fi URN), plus a body-text fallback for a bare "FSD####" mention that the source PDF/HTML never encoded as an actual hyperlink. Same two-tier approach github_links() uses for GitHub.

Usage

fsd_links(paper)

Arguments

Value

a table with the FSD url in the first (href) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
fsd_links(psychsci)

## End(Not run)

Description

A helper for creating modules. Checks for previous module outputs in a chain and returns the named list item if it exists in any parent environment.

Usage

get_prev_outputs(module, item, parent_n = 2)

Arguments

Value

the extracted list item, or NULL if not found

Examples

# .__mc__prev_outputs is usually created by `module_run()`
.__mc__prev_outputs <- list(mod_1 = list(a = 1, b = 2))
f <- function(item) {
  get_prev_outputs("mod_1", item)
}
f("a")
f("d")

Description

Get File List from GitHub

Usage

github_files(repo, dir = "", recursive = FALSE)

Arguments

Value

a data frame of files

Examples

## Not run: 
github_files("scienceverse/metacheck")

## End(Not run)

Description

Get GitHub Repo Info

Usage

github_info(repo, recursive = FALSE)

Arguments

Value

a list of information about the repo

Examples

## Not run: 
github_info("scienceverse/metacheck")

## End(Not run)

Description

Get Languages from GitHub Repo

Usage

github_languages(repo)

Arguments

Value

vector of languages

Examples

## Not run: 
github_languages("scienceverse/metacheck")

## End(Not run)

Description

GitHub links can be in PDFs in several ways.

Usage

github_links(paper)

Arguments

Value

a table with the GitHub url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
github_links(psychsci)

## End(Not run)

Description

Get README from GitHub

Usage

github_readme(repo)

Arguments

Value

a character string of the README contents

Examples

## Not run: 
github_readme("scienceverse/metacheck")

## End(Not run)

Description

Get Short GitHub Repo Name

Usage

github_repo(repo)

Arguments

Value

character string of short repo name

Examples

github_repo("scienceverse/metacheck")
github_repo("https://github.com/scienceverse/metacheck/")
github_repo("https://github.com/scienceverse/metacheck.git")

Description

GitLab.com links can appear in papers the same two ways GitHub links do: a real hyperlink, or a bare "owner/repo" mention near the word "gitlab". Only gitlab.com is matched; a self-hosted GitLab instance's own domain is indistinguishable from an arbitrary institutional website (see the file header comment).

Usage

gitlab_links(paper)

Arguments

Value

a table with the GitLab url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
gitlab_links(psychsci)

## End(Not run)

Description

A personal access token from gitlab.com account settings. Optional for listing/downloading PUBLIC projects (used here only to raise GitLab's unauthenticated rate limit); required for private projects.

Usage

gitlab_pat(pat = NULL)

Arguments

Details

Store it as the GITLAB_PAT environment variable so it is read every time R starts.

Value

the current token (character; "" when none is set)

Examples

gitlab_pat() # returns "" unless a token is set

Description

Get Short GitLab Project Path

Usage

gitlab_repo(repo)

Arguments

Value

character string of the "namespace/project" path, or NULL if the project does not exist / is not reachable

Examples

gitlab_repo("gitlab-org/gitlab")
gitlab_repo("https://gitlab.com/gitlab-org/gitlab/")
gitlab_repo("https://gitlab.com/gitlab-org/gitlab.git")

Description

Convert Grobid TEI XML file to bibr format

Usage

grobid_to_bibr(
  xml_path,
  save_path = ".",
  crossref_lookup = FALSE,
  schema_version = NULL
)

Arguments

Value

a paper object

Description

Extracts the dataset, its variable metadata (measurement level, value labels) and the list of analyses stored in a .jasp archive. Handles both the legacy binary format and the modern embedded-SQLite format.

Usage

import_jasp(path)

Arguments

Value

a list with data (a data.frame; labelled columns carry haven-style label/labels attributes), columns (a data.frame of name and type), analyses (the parsed analyses.json, or NULL), format ("binary" or "sqlite"), and data_file_path (the original source path recorded in the archive, or NA).

Description

Splits the file into its ALL-CAPS-headed sections (Mplus's own structural marker – see the file header) and extracts each section's fixed-width result tables and label/value statistics. The ⁠INPUT INSTRUCTIONS⁠ section (Mplus's own verbatim analysis syntax) is skipped here – see .mplus_export_syntax() for recovering it separately as a sibling .inp file, the same way .spv_export_syntax() recovers .sps from .spv.

Usage

import_mplus_output(path)

Arguments

Value

a list of result tables, each list(analysis, title, data, syntax, table_index) – the same shape read_stat_tables() returns for .jasp/.omv/.spv, so all formats can be processed identically downstream. analysis is the section title (e.g. "MODEL RESULTS"); syntax is the file's own recovered ⁠INPUT INSTRUCTIONS⁠ block (the same text on every table, since one .out file is one Mplus run). Empty list if the file has no recoverable section.

Description

Extracts the dataset, its variable metadata (measurement level, value labels) and a summary of the analyses stored in a .omv archive. The jamovi counterpart of import_jasp(), returning the same structure so downstream code (codebook extraction, data checks) treats an .omv like a .jasp or .sav.

Usage

import_omv(path)

Arguments

Value

a list with data (a data.frame; labelled columns carry haven-style label/labels attributes), columns (a data.frame of name and type), analyses (a character vector, one entry per analysis: its name and, when recoverable, the reproducible R syntax), format ("jamovi"), and data_file_path (NA; jamovi does not record the original import path).

Description

Ties the structure reader (.spv_read_structure(), which table exists, what analysis produced it, which format its data is in) and the two decoders (.spv_decode_light_table() for modern tables, .spv_decode_legacy_data() + .spv_decode_legacy_table() for pre-21 tables) into the SAME shape read_stat_tables() already returns from JASP's analyses.json and jamovi's protobuf blobs.

Usage

import_spv(path)

Arguments

Details

A table that fails to decode (an unsupported construct in either format, or real malformation) is skipped rather than aborting the whole file, so one bad table does not lose every other result in the same archive.

Value

a list of result tables, each list(analysis, title, data, syntax, table_index) — the same shape read_stat_tables() returns for .jasp/.omv (syntax is .spv-specific: the exact SPSS syntax that produced the table, when recoverable). Empty list if the archive has no structure XML or no tables decode.

Description

Renders the file's markup to plain text (see .smcl_render()), splits it into one chunk per Stata command (the ⁠{com}. <command>⁠ echo, mirroring read_r_output()'s R-console-echo splitting), and extracts each chunk's result tables and one-line statistics. ⁠graph export "....png"⁠ commands are recovered as ordinary command text; the PNG itself is never embedded in a .smcl file (Stata writes it to disk separately), so no chart data exists in this format to extract (see the file header).

Usage

import_stata_smcl(path)

Arguments

Value

a list of result tables, each list(analysis, title, data, syntax, table_index) – the same shape read_stat_tables() returns for .jasp/.omv/.spv, so all four formats can be processed identically downstream. analysis is the Stata command that produced the table (e.g. "summarize communication_index barrier_index"); syntax duplicates analysis (Stata's own echoed command IS its syntax, unlike .spv where syntax is recovered separately from a different structure). Empty list if the file has no recoverable command output.

Description

It is useful to ask an LLM to return data in JSON structured format, but can be frustrating to extract the data, especially where the LLM makes syntax mistakes. This function tries to expand a column with a JSON-formatted response into columns and deals with it gracefully (sets an 'error' column to "parsing error") if there are errors. It also fixes column data types, if possible.

Usage

json_expand(table, col = "answer", suffix = c("", ".json"))

Arguments

Value

the table plus the expanded columns

Examples

table <- data.frame(
  paper_id = 1:5,
  answer = c(
    '{"number": "1", "letter": "A", "bool": true}',
    '{"number": "2", "letter": "B", "bool": "FALSE"}',
    '{"number": "3", "letter": "", "bool": null}',
    "oh no, the LLM misunderstood",
    '{"number": "5", "letter": ["E", "F"], "bool": false}'
  )
)

expanded <- json_expand(table, "answer")
expanded

Description

Reads entries back from the on-disk log written by logger() (newest first, so i = 1 is the most recent entry). Returns a single entry as a list, or several entries row-bound into a data frame.

Usage

lastlog(i = 1, logpath = NULL)

Arguments

Value

a list of the last log item, or a data frame of multiple items

Examples

# set up 2 log items
logger("test", list(msg = "hi"))
logger("test", list(msg = "hi again"))

lastlog()
lastlog(2)
lastlog(1:2)

Description

Lists the files of each LDbase link: for a project, every dataset, code and document in its hierarchy (child projects included); for a single dataset, code or document, its own file. A DOI is first resolved to the page it leads to. LDbase has no API, so this reads the public pages (one request per project or item). Items stored elsewhere (LDbase's "external link" option) have no file here and are not listed.

Usage

ldbase_info(ldbase_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame with one row per link: ldbase_url, ldbase_page (the resolved page), ldbase_type, title, doi, license (the licence of the item, or every distinct licence of a project's items joined by "; "), a list-column files (a data frame per link with file_name, file_path, file_url, item_type, item_url) and error (NA, or why the link could not be listed)

Description

Finds links to LDbase (https://ldbase.org) projects, datasets, code and documents, as hyperlinks or in the text, and LDbase DOIs (prefix 10.33009, e.g. 10.33009/ldbase.1627053448.d151). LDbase's own DOI (10.33009/ldbase, cited for the repository itself) and links to its home or search pages are not included: they name no deposit.

Usage

ldbase_links(paper)

Arguments

Value

a data frame with a row for each link (href, plus text_id / paper_id), with ldbase_url (the link) and ldbase_type (projects, datasets, code, documents, or doi for a DOI not yet resolved)

Examples

paper <- test_paper(url = "https://ldbase.org/projects/09609d82-c45f-4442-8c0c-d136191bdc50")
ldbase_links(paper)

Description

Make an html link

Usage

link(url, text = url, new_window = TRUE, type = "")

Arguments

Value

string

Examples

link("https://scienceverse.org")

Description

Ask a large language model (LLM) any question you want about a vector of text or the text from a text_search(). When type is provided, uses ellmer's structured output API to guarantee output conforming to the type spec; otherwise returns free-text responses in an answer column.

Usage

llm(
  text,
  system_prompt,
  type = NULL,
  text_col = "text",
  model = llm_model(),
  params = list(),
  phase = NULL,
  capture_reasoning = FALSE
)

Arguments

Details

You will need to get your own API key from https://console.groq.com/keys. To avoid having to type it out, add it to the .Renviron file in the following format (you can use usethis::edit_r_environ() to access the .Renviron file)

GROQ_API_KEY="key_value_asdf"

See https://console.groq.com/docs for more information

Value

a data frame of results

Examples

## Not run: 
# Free-text query
text <- c("hello", "number", "ten", 12)
system_prompt <- "Is this a number? Answer only 'TRUE' or 'FALSE'"
is_number <- llm(text, system_prompt)

# Structured extraction
type_spec <- ellmer::type_object(
  is_number = ellmer::type_boolean("Whether the input is a number")
)
result <- llm(c("hello", "42"), "Classify the input.", type = type_spec)

## End(Not run)

Description

When enabled (the default), llm() stores each structured or free-text response on disk and replays it on identical later calls, so re-running a report on the same paper does not re-issue (or re-bill) the LLM requests. Because llm() runs at temperature 0 the replayed answer matches a fresh call. Cached entries are keyed by model, system prompt, input text, type spec, and params; changing any of these produces a fresh call.

Usage

llm_cache(enabled = NULL)

Arguments

Value

the current setting (logical), invisibly when setting

Examples

llm_cache()          # is the cache on?
## Not run: 
llm_cache(FALSE)     # force fresh calls

## End(Not run)

Description

Deletes all cached LLM responses (see llm_cache()).

Usage

llm_cache_clear()

Value

the number of cache entries removed, invisibly

Description

Set the maximum number of calls to the LLM

Usage

llm_max_calls(n = NULL)

Arguments

Description

llm() needs SOME max_tokens value on every call (a provider truncates a response with no clear error otherwise – a codebook/data-check pass over many columns at once is the case most likely to need more than the built-in default). Rather than requiring every module call to repeat params = list(max_tokens = ...) individually, set it once per session here; llm() falls back to this whenever a caller's own params does not already specify max_tokens (an explicit params$max_tokens on a single call still wins, same precedence as every other params entry).

Usage

llm_max_tokens(n = NULL)

Arguments

Value

the current default max_tokens value (invisibly when setting)

Examples

## Not run: 
llm_max_tokens(8192)

## End(Not run)

Description

Use llm_model_list() to get a list of available models

Usage

llm_model(model = NULL)

Arguments

Description

List available LLM models for the specified platform.

Usage

llm_model_list(platform = NULL)

Arguments

Details

For platforms other than groq, returns the value from the corresponding ellmer::models_platform function.

Value

a data frame of models and info

Examples

## Not run: 
llm_model_list()

## End(Not run)

Description

Every LLM call this package makes is a bounded, structured-extraction task over text already given in the prompt (classify a file, extract a variable's label, list the scales named in ~30 sentences, group files by study) – pattern-matching over given material, not multi-step reasoning (no arithmetic, no multi-hop inference, no planning). A "thinking"/ "reasoning" model spending extra tokens re-deriving what the prompt already states is close to pure overhead here: it inflates cost/latency and eats into the same max_tokens budget as the visible answer, which is a confirmed real cause of truncated structured responses on gpt-oss models via Groq. Minimal reasoning effort is the right DEFAULT for what this package does, not a tradeoff against quality.

Usage

llm_reasoning(effort = NULL)

Arguments

Details

There is no single universal "reasoning" switch across providers – this is genuinely per model family, each verified rather than assumed:

• ⁠openai/gpt-oss-*⁠ (Groq or any OpenAI-compatible host): the reasoning_effort chat-completion parameter, accepting "low", "medium", or "high" – "low" is the minimum; there is no full-off option for this family (verified against Groq's own docs).

• ⁠qwen3*⁠-family models: also reasoning_effort, but accepting "none" or "default" – "none" fully disables reasoning tokens, unlike gpt-oss.

• Mistral's reasoning-capable models (mistral-small-latest, mistral-medium-3-5): also reasoning_effort, but with only TWO values, "high" (full thinking chunk) or "none" (thinking chunk omitted) – verified against Mistral's own docs, a third distinct shape from both gpt-oss and qwen3.

• Ollama-hosted reasoning models (DeepSeek-R1, Qwen3, ...): the native API's boolean think (llm() already sends this as a ⁠/nothink⁠ system-prompt prefix over Ollama's native ⁠/api/chat⁠ endpoint when think = FALSE, since Ollama's OpenAI-compatible ⁠/v1/⁠ endpoint ignores it) – a genuinely different mechanism (a flag on the request, not a graded effort level), so llm_reasoning()'s "low"/ "none" both map to think = FALSE for this family; there is no Ollama equivalent of "medium"/"high" to request.

A model family with none of the above (a plain non-reasoning model, or one not yet covered here) is left untouched: llm_reasoning() never forces an unsupported parameter onto a call, since providers vary in whether an unrecognised parameter is silently ignored or rejected outright.

Value

the current default reasoning effort (invisibly when setting)

Examples

## Not run: 
llm_reasoning("low")

## End(Not run)

Description

Every single request llm() makes (one item, or one batch, depending on the caller) is bounded by this wall-clock limit. Without it, a stuck local model (most often Ollama under load, or a batch too large for the model to finish) blocks silently – no log output, no progress, nothing – for as long as the underlying HTTP client is willing to wait, which can be hours. A timeout turns that invisible stall into a fast, visible, per-row failure (recorded the same way a provider error already is – see llm()'s own error handling), so a large batch run fails fast and retries instead of hanging.

Usage

llm_timeout(seconds = NULL)

Arguments

Value

the current timeout in seconds (invisibly when setting)

Examples

## Not run: 
llm_timeout(120)

## End(Not run)

Description

Mainly for use in optional LLM workflows in modules

Usage

llm_use(llm_use = NULL)

Arguments

Value

the current option value (logical)

Examples

if (llm_use()) {
  print("We can use LLMs")
} else {
  print("We will not use LLMs")
}

Description

Lists all files in a local directory recursively and returns a data frame compatible with the repo_check output table, for use with code_check.

Usage

local_files(path, recursive = FALSE)

Arguments

Value

a data frame with columns repo_url, file_name, file_url, file_location, file_size, file_type

Examples

## Not run: 
  local_files("my_project")

## End(Not run)

Description

Adds a logging message to the log. Keeps the log as a maximum of 1000 rows.

Usage

logger(label = "", contents = list(), logpath = NULL)

Arguments

Value

called for side effects of writing to log, returns logpath

Examples

logpath <- tempfile(fileext = ".log")
logger("test", list(x = 1), logpath)
lastlog()

Description

The per-paper ⁠*.manifest.json⁠ is written by more than one module: data_check records the files/provenance, and code_check records the packages the code loads (a code section). Because each module rebuilds only its own part of the document, a plain overwrite would let whichever module ran last erase the other's section. This helper reads any existing manifest, overlays patch at the top level (each key in patch replaces that key wholesale; keys not in patch are kept untouched), and writes it back.

Usage

manifest_merge(path, patch)

Arguments

Details

The rule that makes this safe against run order: each writer's patch must contain only the keys it owns. data_check patches everything except code; code_check patches only code. Overlapping keys would still clobber.

Value

(invisibly) the manifest path

Description

Recomposes the statistics a paper REPORTS (from paper$eq, grouped by the grp_id that ties one reported test's numbers together) into whole tests, then checks whether each test's component values co-occur in a single analysis of the paper's extracted OUTPUT (reproducibility_check's statistical output). A test is matched on its whole signature, not lone numbers, so a match means the reported result actually appears in the reproducible output rather than a value coinciding by chance. The result carries, per matched test, which output file and analysis produced it (provenance).

Usage

match_reported_output(
  paper,
  output,
  include_tables = FALSE,
  min_components = 1L
)

Arguments

Value

a data.frame, one row per recomposed reported test, with: text_id, grp_id, reported (the recomposed test as text, e.g. "W=183.5 p=.791 rb=-0.16"), n_components, n_matched (components found in the best-matching output analysis), found (logical), match_values (the matched components as "name=value" pairs), not_matched (the UNMATCHED components of that same test, same "name=value" form – always populated alongside match_values for a partial match, so exactly which claim failed to reproduce is visible, not just a count), source_file / analysis (provenance of the match), confidence ("full" all components matched / "partial" / "none"), and plausible_split – NA unless this test's grouping came from .regroup_by_evidence() re-deriving test boundaries from OUTPUT co-occurrence rather than trusting extract_tests()'s text-only guess (see that function's own header comment): TRUE when a component split away from its original reported neighbours landed at a site sharing a row_label token with theirs (the same underlying variable, reached via a different analysis – plausible), FALSE when no such link was found (the split is NOT hidden or downgraded, only flagged, so a reader can judge the match's plausibility from the source_file/analysis of every piece involved). Attribute "summary" holds the roll-up.

Description

Retrieve info from Mendeley Data by URL

Usage

mendeley_info(mendeley_url, id_col = 1, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information

Examples

## Not run: 
  mendeley_info("https://doi.org/10.17632/vjtxybrc28.1")

## End(Not run)

Description

Get all Mendeley Data links: real hyperlinks from the paper's own url table, plus a body-text fallback for a BARE mention (a DOI like "10.17632/vjtxybrc28.1" is routinely cited without any URL scheme at all) that the source PDF/HTML never encoded as an actual hyperlink – the url table only ever contains links the source document itself made clickable. Same two-tier approach zenodo_links() uses.

Usage

mendeley_links(paper)

Arguments

Value

a table with the Mendeley Data url in the first (text) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
mendeley_links(psychsci)

## End(Not run)

Description

Prints the location and size of all three on-disk caches — the downloaded repository-FILE cache, the repository-LISTING cache (dataset/record metadata, off by default – see repo_info_cache_clear()), and the LLM-response cache — so they are never hidden. By default each sits in a folder in the current working directory (.metacheck_repo_cache, .metacheck_repo_info_cache, and .metacheck_llm_cache); relocate all three with options(metacheck.cache.dir = "/some/path").

Usage

metacheck_cache_info()

Value

a data.frame (cache, path, size_mb), invisibly.

See Also

repo_cache_dir(), repo_cache_clear(), repo_info_cache_clear(), llm_cache_clear()

Examples

## Not run: 
metacheck_cache_info()

## End(Not run)

Description

See the help files for a module by name (get a list of names from module_list())

Usage

module_help(module = NULL)

Arguments

Value

the help text

Examples

module_help("marginal")

Description

Get module information

Usage

module_info(module)

Arguments

Value

a list of module info

Examples

module_info("all_p_values")

Description

Downloads a public GitHub repository that holds one or more metacheck modules and saves it in the metacheck user data directory, so its modules can be used by name in module_run(), report(), module_list() and module_help(), like the built-in modules.

Usage

module_install(repo, ref = NULL, overwrite = FALSE)

Arguments

Details

A module is an .R file with a roxygen header, as made by module_template(). Every such file in the top folder of the repository, or in a folder called ⁠modules/⁠, is installed as a module. Other files (helper code, data, tests) are saved with the repository, but are not listed as modules.

A module can run other modules with module_run() and include their results in its own report with module_report(), so running one module (e.g. report(paper, modules = "my_check")) gives one report for all of its checks.

A module can state the lowest metacheck version it needs with a line ⁠#' @metacheck 0.3.4⁠ in its header; it then refuses to install or run with an older metacheck. External modules should only use exported metacheck functions: internal functions can change without notice.

Nothing is saved when a module in the repository has the same name as a built-in module, a module from another installed repository, or another module in the same repository.

Modules are saved in the metacheck user data folder, which belongs to the user who installs them. To share installed modules between users (for example with the user a Shiny Server runs apps as), set the environment variable METACHECK_MODULES_DIR to a folder all of them can read, both when installing and when using the modules.

Installing a module means running its code whenever you use it: only install modules from repositories you trust.

Value

a data frame of the installed repository (see module_installed()), invisibly

See Also

module_update(), module_remove(), module_installed()

Examples

## Not run: 
module_install("owner/repo")
module_run(demopaper(), "module_name")

## End(Not run)

Description

Lists the GitHub repositories installed with module_install(). Use module_list() to see their modules together with the built-in ones.

Usage

module_installed()

Value

a data frame with one row per repository: repo, the ref (branch, tag or commit) it was installed from, the sha of the installed commit, when it was installed, its modules, and the local path

Examples

module_installed()

Description

List modules

Usage

module_list(
  module_dir = system.file("modules", package = "metacheck"),
  external = TRUE
)

Arguments

Value

a data frame of modules; source is the GitHub repository of an installed module, or NA

Examples

mods <- module_list()

Description

Deletes a repository of modules installed with module_install().

Usage

module_remove(repo)

Arguments

Value

TRUE invisibly if removed, FALSE if not installed

Examples

## Not run: 
module_remove("owner/repo")

## End(Not run)

Description

Report from module output

Usage

module_report(module_output, header = 3)

Arguments

Value

text

Examples

paper <- demopaper()
op <- module_run(paper, "stat_p_exact")
module_report(op) |> cat()

Description

Run a module

Usage

module_run(paper, module, ...)

Arguments

Value

a list of the returned table and report text

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
module_run(psychsci[[1]], "all_p_values")

## End(Not run)

Description

Create a Module from a Template

Usage

module_template(module_name, path = "./modules")

Arguments

Value

the file path (invisibly)

Description

Downloads the latest commit of the branch or tag each repository was installed from (see module_install()). A repository that is already up to date is not downloaded again.

Usage

module_update(repo = NULL)

Arguments

Value

a data frame of the installed repositories (see module_installed()), invisibly

Examples

## Not run: 
module_update()

## End(Not run)

Description

See details for a list of root-level fields that can be selected.

Usage

openalex_doi(doi, select = NULL)

Arguments

Details

See https://docs.openalex.org/api-entities/works/work-object for explanations of the information you can retrieve about works.

Root-level fields for the select argument:

• id

• doi

• title

• display_name

• publication_year

• publication_date

• ids

• language

• primary_location

• type

• type_crossref

• indexed_in

• open_access

• authorships

• institution_assertions

• countries_distinct_count

• institutions_distinct_count

• corresponding_author_ids

• corresponding_institution_ids

• apc_list

• apc_paid

• fwci

• has_fulltext

• fulltext_origin

• cited_by_count

• citation_normalized_percentile

• cited_by_percentile_year

• biblio

• is_retracted

• is_paratext

• primary_topic

• topics

• keywords

• concepts

• mesh

• locations_count

• locations

• best_oa_location

• sustainable_development_goals

• grants

• datasets

• versions

• referenced_works_count

• referenced_works

• related_works

• abstract_inverted_index

• abstract_inverted_index_v3

• cited_by_api_url

• counts_by_year

• updated_date

• created_date

Value

list with DOIs and info

Examples

doi <- "10.7717/peerj.4375"
## Not run: 
oa_info <- openalex_doi(doi)
oa_info <- openalex_doi(doi, "title")

## End(Not run)

Description

Look up a reference in OpenAlex

Usage

openalex_query(title, source = NA, authors = NA, strict = TRUE)

Arguments

Value

A data frame with citation info

Examples

## Not run: 
openalex_query("Sample Size Justification", "Collabra Psychology")

## End(Not run)

Description

Check the status of the OSF API server.

Usage

osf_api_check(
  osf_api = getOption("metacheck.osf.api"),
  on_error = c("stop", "warn", "ignore")
)

Arguments

Details

The OSF API server is down a lot, so it's often good to check it before you run a bunch of OSF functions. When the server is down, it can take several seconds to return an error, so scripts where you are checking many URLs can take a long time before you realise they aren't working.

You can only make 100 API requests per hour, unless you authorise your requests, when you can make 10K requests per day. The osf functions in metacheck often make several requests per URL to get all of the info. You can authorise them by creating an OSF token at https://osf.io/settings/tokens and including the following line in your .Renviron file:

OSF_PAT="replace-with-your-token-string"

Value

the OSF status

Examples

osf_api_check()

Description

Launch the OSF app: enter an OSF user or project ID, search and tick the projects you want, then download them with osf_file_download().

Usage

osf_app(quiet = FALSE, ...)

Arguments

Details

Listing a user's projects uses osf_user_projects(), and a single project ID is shown as a one-row list so both routes end in the same place. Private projects need a token, which is entered in the app and set for that session only with osf_pat().

Value

NULL (invisibly)

Examples

## Not run: 
osf_app()

## End(Not run)

Description

Clear the session cache of OSF listings

Usage

osf_cache_clear()

Value

the number of cached listings removed, invisibly

Description

Check if strings are valid OSF IDs, URLs, or waterbutler IDs. Basically an improved wrapper for osfr::as_id() that returns NA for invalid IDs in a vector.

Usage

osf_check_id(osf_id)

Arguments

Value

a vector of valid IDs, with NA in place of invalid IDs

Examples

osf_check_id("pngda")
osf_check_id("osf.io/pngda")
osf_check_id("https://osf.io/pngda")
osf_check_id("https://osf .io/png da") # rogue whitespace
osf_check_id("pnda") # invalid

Description

Sometimes the OSF gets fussy if you make too many calls, so you can set a delay of a few seconds before each call. Use osf_delay() to get or set the OSF delay.

Usage

osf_delay(delay = NULL)

Arguments

Examples

osf_delay()

Description

Creates a directory for the OSF ID and downloads all of the files using a folder structure from the OSF project nodes and file storage structure. Returns (invisibly) a data frame with file info.

Usage

osf_file_download(
  osf_id,
  download_to = ".",
  max_file_size = NULL,
  max_download_size = NULL,
  max_folder_length = Inf,
  ignore_folder_structure = FALSE,
  mode = c("all", "select", "files", "zip"),
  unzip = TRUE,
  metadata = TRUE,
  osf_pat = NULL,
  pb = NULL
)

Arguments

Details

Some differences may exist because the OSF allows longer file names with characters that may not be allowed on a file system, so these are cleaned up when downloading.

Everything is downloaded by default: no size limits apply, because this function exists to retrieve a repository in full and someone archiving their own work wants their own files whatever size they are. Limits are available for when that is not what you want – looking at somebody else's repository, say. In the default mode = "files", files over max_file_size are omitted individually, while max_download_size is an all-or-nothing gate for the remaining repository total. Omitted files are reported as messages and appear in the returned data frame with downloaded = FALSE and attempted = FALSE.

In mode = "zip", OSF's Waterbutler API serves a folder as one generated zip archive, which is far fewer requests than fetching each file. That endpoint covers one node's osfstorage at a time, so a project whose files sit in components, or on a linked add-on such as GitHub or Dropbox, is not one archive: one archive is requested per node that holds osfstorage files, and anything no archive can hold is downloaded individually, so the whole project is still retrieved. In this mode, max_download_size is a budget for the whole project. The OSF does not report an archive's size in advance, so a node's archive is taken only when its listed files fit in what is left of the budget, and its download is stopped if it grows past that. The files of a node whose archive does not fit, or was stopped, are downloaded individually, smallest first, as many as fit in the budget. max_file_size cannot filter files inside an archive before download. Archives can either be kept as zips or unzipped after download.

Value

data frame of file info, one row per file (osf_id is each file's own ID). It carries download_path, the absolute folder the project was saved in, plus osf_project and osf_url identifying the project, so the result can be passed straight to zenodo_upload(). downloaded, size_on_disk, and attempted report the verification described above.

In mode = "all" there is no file listing, so the table has one row per node instead: folder, osf_project, osf_url, title, files (how many arrived), bytes, download_path, and downloaded. It can still be passed to zenodo_upload(), which uses download_path.

Downloading a whole account, or part of one

Given a user ID, every project that user contributes to is downloaded. Components are not listed separately, because downloading a project already brings its components' files with it, at any depth.

To download only some of them, list the projects first with osf_user_projects(), filter that table however you like, and pass it back:

projects <- osf_user_projects("4i578")
subset(projects, public) |> osf_file_download(download_to = "my_osf")

Checking the download

Every file that was meant to arrive is checked against the file system afterwards, and against the size the OSF reported for it, so a transfer that failed silently or wrote a truncated file is reported rather than passing as complete. Two columns record the outcome: downloaded is TRUE only for a file actually present at the right size, and attempted is FALSE for a file deliberately excluded by max_file_size or max_download_size. Files that were attempted but did not arrive raise a warning naming them.

Examples

## Not run: 
osf_file_download("6nt4v")

# download everything one user has, then archive it on Zenodo
osf_file_download("4i578", download_to = "my_osf",
                  max_file_size = NULL) |>
  zenodo_upload()

## End(Not run)

Description

OSF API queries only return up to 10 items per page, so this helper functions checks for extra pages and returns all of them

Usage

osf_get_all_pages(url, page_end = Inf)

Arguments

Value

a table of the returned data. When the request could not be completed (e.g. a private, embargoed, withdrawn, or deleted resource, or a network failure), this is an empty list() with an osf_error attribute set to "forbidden", "not_found", "gone", or "request_failed" (a bare NULL cannot carry attributes in R, so it would silently discard this) – callers that only check length(result) == 0 keep working unchanged, and callers that need to tell "inaccessible" apart from "genuinely empty" can check attr(result, "osf_error").

Examples

# get the 20 newest preprints
## Not run: 
osf_api <- getOption("metacheck.osf.api")
url <- sprintf("%s/preprints/?search=date_created-desc", osf_api)
preprints <- osf_get_all_pages(url, 2)

## End(Not run)

Description

Repository listings are cached for the session (keyed by URL and recursive), so repeated calls do not re-query the OSF API; clear the cache with osf_cache_clear() or disable it with options(metacheck.osf.cache = FALSE).

Usage

osf_info(osf_url, id_col = 1, recursive = FALSE, pb = NULL, cache = FALSE)

Arguments

Value

a data frame of information

Examples

## Not run: 
# get info on one OSF node
osf_info("pngda")

# also get child nodes and files
osf_info("https://osf.io/6nt4v", recursive = TRUE)

## End(Not run)

Description

Get all OSF links: real hyperlinks from the paper's own url table, plus a body-text fallback for a BARE mention like "osf.io/gms8z/" that the source PDF/HTML never encoded as an actual hyperlink (common in PDF-converted papers, where a plain-text URL mention loses its link formatting) — the url table only ever contains links the source document itself made clickable, so a repository this important cannot rely on that alone. Same two-tier approach github_links() already uses for GitHub.

Usage

osf_links(paper)

Arguments

Value

a table with the OSF url in the first (href) column

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
osf_links(psychsci)

## End(Not run)

Description

Use osf_pat() to get the token used to authorise OSF API requests, or osf_pat("your-token") to set it for the rest of the session.

Usage

osf_pat(pat = NULL)

Arguments

Details

Without a token you can make 100 API requests per hour; with one you can make 10,000 per day, so a token is worth setting before downloading whole projects or listing everything a user has.

To create one, sign in at https://osf.io/settings/tokens, click "Create token", give it a name, and tick the osf.full_read scope (add osf.full_write only if you also intend to write to the OSF). Copy the token immediately, as the OSF does not show it again.

The usual way to store it is a line in your .Renviron file (open it with usethis::edit_r_environ()), which is read every time R starts:

OSF_PAT="replace-with-your-token-string"

Setting the token with osf_pat() overrides that for the current session only, which is useful when you cannot edit .Renviron or want to use a different account for one run.

Value

the current token (character; "" when none is set)

Examples

osf_pat() # returns "" unless a token is set

Description

Get A list of preprints from the OSF

Usage

osf_preprint_list(
  provider = NULL,
  date_created = NULL,
  date_modified = NULL,
  page_start = 1,
  page_end = page_start
)

Arguments

Value

a table of preprint info

Examples

## Not run: 
dc <- c("2025-09-01", "2025-10-01")
pp <- osf_preprint_list("psyarxiv", date_created = dc)
files <- pp$primary_file

## End(Not run)

Description

Get OSF GUID Type

Usage

osf_type(guid)

Arguments

Value

the type, or "inaccessible" when the GUID is a validly-formed OSF ID but the resource itself could not be reached (private, embargoed, withdrawn, or deleted) – distinct from NA, which means the input was not a valid OSF ID at all

Examples

# osf_type("pngda")

Description

Every project an OSF user contributes to, as a table you can read and filter before downloading anything. Pass the whole table, or any subset of it, to osf_file_download().

Usage

osf_user_projects(user_id, pb = NULL)

Arguments

Details

⁠/users/{id}/nodes/⁠ returns each node the user can see, which includes components as separate rows alongside the projects that contain them. Downloading a project pulls in its components' files automatically (the folder structure in osf_file_download() nests them, at any depth), so listing a component separately would only download the same files twice. Each node is therefore reduced to its root (relationships$root, which .osf_node_data() exposes as the project column); a node with no root recorded stands as its own project.

No file counts or sizes are reported. They would cost an extra request per project and could only ever count files at the project's own root, missing everything inside folders and components – while the download itself already lists each project in full, so the true size is discovered there anyway.

Value

a data frame with one row per project: osf_id, name, category, public, and osf_url. Zero rows when the user has no projects that could be listed.

Examples

## Not run: 
# see what there is
projects <- osf_user_projects("4i578")

# download only the public ones
projects |>
  subset(public) |>
  osf_file_download(download_to = "my_osf")

# or pick by name
projects |>
  subset(grepl("ManyLabs", name)) |>
  osf_file_download(download_to = "manylabs")

## End(Not run)

Description

Get Paper IDs

Usage

paper_id(paper)

Arguments

Value

a vector of paper_ids

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
paper_id(psychsci)

## End(Not run)

Description

Return a table from a paper object or concatenate tables across a list of paper objects.

Usage

paper_table(paper, table, cols = NULL)

Arguments

Value

a merged table

Examples

## Not run: 
psychsci <- papers_load("psychsci", cache = TRUE)
biblio <- paper_table(psychsci[1:10], "bib")
xrefs <- paper_table(psychsci[1:10], "xref")

## End(Not run)

Description

Checks if a paper object conforms to the JSON schema.

Usage

paper_validate(paper)

Arguments

Value

TRUE or error

Examples

paper <- list(paper_id = "Not a paper object")
tryCatch(
  paper_validate(paper),
  error = \(e) print(e$message)
)

paper <- demopaper()
paper_validate(paper)

Description

Save a paper as a JSON file.

Usage

paper_write(paper, file_name = NULL, save_path = ".", schema_version = NULL)

Arguments