psychds
Creating and Validating 'Psych-DS' Datasets
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.
psychds
Overview
psychds provides tools for creating, editing, and validating psychological research datasets following the Psych-DS standard. The package includes:
- An interactive Shiny application for building Psych-DS compliant datasets from existing directories
- Functions for validating existing datasets against the standard
- Tools for generating data dictionaries with professional formatting
Installation
From CRAN (not currently available)
install.packages("psychds")
Development version from GitHub
# install.packages("remotes")
remotes::install_github("psych-ds/psychds-r", dependencies = TRUE)
Quick Start
Launch the Shiny Application
The easiest way to use psychds is through the interactive Shiny app:
library(psychds)
run_psych_ds_app()
This opens a guided interface for:
- Selecting your project directory and data files
- Adding dataset metadata (name, description, authors)
- Standardizing filenames with Psych-DS keywords
- Generating data dictionaries
- Validating your dataset
- Exploring your dataset
Check Dependencies
Before running the app, verify that all required packages are installed:
check_psychds_deps(detailed = TRUE)
Features
📁 Dataset Creation
Build Psych-DS compliant datasets with a step-by-step wizard:
- Select and organize data files
- Auto-detect CSV column structures
- Apply standardized naming conventions
- Generate
dataset_description.jsonmetadata
📋 Data Dictionaries
Create professional, human-readable data dictionaries:
- Document all variables with descriptions, types, and constraints
- Include categorical value definitions
- Generate professional readable dictionaries in HTML/PDF
✅ Validation
Validate datasets against the Psych-DS specification:
- Check required files and structure
- Validate JSON metadata against schemas
- Verify data file integrity
- Get detailed error messages and suggestions
The Psych-DS Standard
Psych-DS (Psychological Dataset Standard) provides a specification for organizing behavioral and psychological research data. Key components include:
dataset_description.json: Metadata about the dataset using Schema.org vocabularydata/: Directory containing data files with standardized names- Keyword-based filenames: e.g.,
study-attention_session-1_data.csv - Data dictionaries: Documentation of all variables
Learn more at psych-ds.github.io
Requirements
- R >= 4.1.0
- Required packages: shiny, shinydashboard, shinyjs, DT, jsonlite
- Optional: sortable, zip, pointblank (for full functionality)
- Optional: Node.js >= 18 (for the
validate_dataset()command-line validator)
Getting Help
Contributing
Contributions are welcome! Please read our Contributing Guide for details on:
- Reporting bugs
- Suggesting features
- Submitting pull requests
Citation
If you use psychds in your research, please cite:
@software{psychds,
title = {psychds: Tools for Creating and Validating Psych-DS Datasets},
author = {{Psych-DS Development Team}},
year = {2026},
url = {https://github.com/psych-ds/psychds-r}
}
License
MIT © Psych-DS Development Team