Package {psychds}

Title:	Creating and Validating 'Psych-DS' Datasets
Version:	0.1.0
Description:	Provides a 'Shiny' application and helper functions for adopting 'Psych-DS' (https://psych-ds.github.io/), a community data standard for organizing and documenting datasets in the psychological and behavioral sciences inspired by the Brain Imaging Data Structure ('BIDS'). A guided interface walks researchers through the dataset creation process, organizing tabular data files into proper 'Psych-DS' directory structures, generating new, compliant, keyword-based filenames, and generating machine-readable 'JSON' metadata. Additional tools support building and editing data dictionaries with variable-level descriptions, validating datasets against the full 'Psych-DS' specification via a bundled 'JavaScript' validator, and exploring dataset contents interactively.
License:	MIT + file LICENSE
URL:	https://psych-ds.github.io/psychds-r/, https://github.com/psych-ds/psychds-r
BugReports:	https://github.com/psych-ds/psychds-r/issues
Copyright:	see file inst/COPYRIGHTS for bundled 'JavaScript' library copyrights and licenses
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1.0)
Imports:	cli, jsonlite, rstudioapi, shiny (≥ 1.7.0), tools, utils
Suggests:	crosstalk, DT, fs, knitr, miniUI, pointblank, rmarkdown, shinydashboard, shinyjs, sortable, spelling, testthat (≥ 3.0.0), zip
Config/testthat/edition:	3
SystemRequirements:	Node.js (>= 18.0.0)
VignetteBuilder:	knitr
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-10-05 15:38:54 UTC; brianleonard
Author:	Massachusetts Institute of Technology [cph], Brian Leonard [aut, cre], Melissa Kline Struhl [aut]
Maintainer:	Brian Leonard <bleonard@mit.edu>
Repository:	CRAN
Date/Publication:	2026-10-15 17:30:07 UTC

Check and Load Package Dependencies

Description

This function provides robust package management following CRAN policies. It checks versions, handles conflicts, and provides clear user feedback.

Usage

check_dependencies(
  min_versions = NULL,
  recommended_versions = NULL,
  startup_mode = getOption("psychds.startup_mode", "recommended")
)

Arguments

Value

Logical indicating success

Check psychds Dependencies

Description

Verifies that all required and optional package dependencies are installed and meet minimum version requirements.

Usage

check_psychds_deps(
  install_missing = interactive(),
  detailed = FALSE,
  check_pdf = TRUE
)

Arguments

Details

This function checks for:

• Required packages: shiny, shinydashboard, shinyjs, DT, jsonlite

• Optional packages: sortable, zip, pointblank

• Minimum version requirements for each package

If dependencies are missing, the function provides installation instructions.

Value

Invisibly returns a list with missing_required and missing_recommended character vectors.

Examples

# Quick check
check_psychds_deps()

# Detailed check with environment info
check_psychds_deps(detailed = TRUE)

Copy data files to the Psych-DS data directory

Description

Copy data files to the Psych-DS data directory

Usage

copy_data_files(files, dest_dir)

Arguments

Value

Character vector of copied file paths

Create a datapackage.json file

Description

Create a datapackage.json file

Usage

create_datapackage(dir_path, files, dataset_info)

Arguments

Value

Invisible NULL

Create a dataset_description.json file

Description

Create a dataset_description.json file

Usage

create_dataset_description(dir_path, dataset_info)

Arguments

Value

Invisible NULL

Create a Psych-DS directory structure

Description

Create a Psych-DS directory structure

Usage

create_psych_ds_structure(base_dir, opt_dirs = NULL)

Arguments

Value

Invisible NULL

Extract CSV file structure for dictionary creation

Description

Extract CSV file structure for dictionary creation

Usage

extract_csv_structure(file_path)

Arguments

Value

Data frame with column information

Generate a data dictionary from CSV files

Description

Generate a data dictionary from CSV files

Usage

generate_data_dictionary(files)

Arguments

Value

List of data frames, one for each file

Check if a directory is a valid Psych-DS dataset

Description

Check if a directory is a valid Psych-DS dataset

Usage

is_valid_psych_ds_dir(dir_path)

Arguments

Value

Logical indicating if the directory is a valid Psych-DS dataset

Initialize Shiny App with Robust Package Management

Description

Main entry point that ensures all dependencies are met

Usage

run_app_safe(app_dir = system.file("shiny", package = "psychds"), ...)

Arguments

Value

No return value. Called for its side effect of launching the 'Shiny' application; blocks until the app is closed.

Run the Psych-DS Shiny Application

Description

Launches the interactive Shiny application for creating, editing, and validating Psych-DS compliant datasets.

Usage

run_psych_ds_app(
  launch.browser = getOption("shiny.launch.browser", interactive()),
  port = getOption("shiny.port"),
  host = getOption("shiny.host", "127.0.0.1"),
  startup_mode = getOption("psychds.startup_mode", "recommended"),
  force_browser = getOption("psychds.force_browser", FALSE),
  ...
)

Arguments

Details

The application provides a guided interface for:

• Selecting project directories and data files

• Adding dataset metadata

• Standardizing filenames with Psych-DS keywords

• Generating data dictionaries

• Validating datasets against the Psych-DS specification

Value

This function does not return a value. It launches the Shiny application and blocks until the app is closed.

See Also

check_psychds_deps() for verifying dependencies before running.

Examples

if (interactive()) {
  # Standard launch
  run_psych_ds_app()

  # Force external browser (if RStudio viewer has issues)
  run_psych_ds_app(force_browser = TRUE)

  # Minimal checking for faster startup
  run_psych_ds_app(startup_mode = "minimal")

  # Specific port
  run_psych_ds_app(port = 3838)
}

Validate a Psych-DS Dataset

Description

Validates a dataset directory against the full 'Psych-DS' specification using the same validator used by the 'psychds-validator' command-line tool.

Usage

validate_dataset(dir_path, json = FALSE, verbose = FALSE, use_events = FALSE)

Arguments

Details

Requires 'Node.js' to be installed and available on the system PATH. Install 'Node.js' from https://nodejs.org.

Value

Invisibly returns the exit status. Called for its side effect of printing validation results to the console.

Examples

## Not run: 
# Standard text output
validate_dataset("path/to/my-study")

# JSON output for programmatic use
validate_dataset("path/to/my-study", json = TRUE)

# Verbose with warnings
validate_dataset("path/to/my-study", verbose = TRUE)

# Live checklist
validate_dataset("path/to/my-study", use_events = TRUE)

## End(Not run)