Using the Shiny Application

Overview

The psychds Shiny application provides a guided, step-by-step interface for creating Psych-DS compliant datasets. This guide walks through each section of the application.

Launching the App

library(psychds)
run_psych_ds_app()

Application Sections

The app has five sections accessible from the sidebar. After the Welcome page, the four tools are:

Create Dataset - Build a new Psych-DS dataset
Update Dictionary - Edit variable definitions
Validate Dataset - Check compliance with the standard
Dataset Explorer - Browse and filter any Psych-DS dataset

Create Dataset

The dataset creation wizard has three steps:

Step 1: Project Directory and Data Files

In this step, you:

Select a project directory - This is the folder containing your research materials. We will be building a new dataset using the files you select from this directory.
Choose data files - Browse and select CSV files to include. Click on files/directories to select/deselect them.
Configure optional directories - Choose additional folders to create:
- analysis/ - Analysis scripts and pipelines
- materials/ - Study materials (stimuli, protocols, flyers)
- results/ - Output figures and tables
- products/ - Papers, presentations
- documentation/ - Additional documentation

Your original files are safe! The app only reads from your existing files to create standardized copies. Your original data is never modified.

Step 2: Dataset Metadata

Enter information about your dataset:

Required fields:

Name - A descriptive name for your dataset
Description - Brief description of what the data contains

Author information:

Add authors with their names and optional ORCID iDs
Click “Add New Author” to add multiple authors

Detected Variables:

The app automatically detects column names from your CSV files. Variables with the same name across files are assumed to have identical definitions.

Step 3: Standardize Filenames

Rename your data files using Psych-DS naming conventions.

If you selected exactly one data file, a simplified guided panel appears instead: pick your first keyword (usually study), give it a value, and optionally add more keyword-value pairs. The full interface below appears when two or more files are selected.

Select files - Check boxes to select multiple files for batch operations
Configure keywords - For each file, set values for standard keywords:
- study, session, subject, task, etc.
Auto-Name from Data - Automatically fill keyword values from constant columns in your data (for instance, if each file contains a column like “subject_id” with the same value in every row, you can use this column to name the file)
Preview - See the new filename as you configure keywords

Example transformation:

Original: experiment_data_2024.csv
New:      study-attention_session-1_data.csv

Saving Your Dataset

After Step 3, you’ll be prompted to:

Choose a name for your dataset folder
Select where to save it
Review the file structure preview
Click “Create Dataset” to generate the Psych-DS compliant dataset

Update Dictionary

The data dictionary editor allows you to document all variables in your dataset.

Loading a Dataset

Click “Load Dataset”
Navigate to your Psych-DS dataset folder
The app will detect all CSV files and extract variable names

Editing Variables

Select a variable from the list to edit its properties:

Basic Properties:

Description - What this variable represents
Data Type - string, integer, number, boolean, date, etc.
Unit - Measurement unit (if applicable)

Constraints:

Required - Whether the variable must have a value
Unique - Whether all values must be unique
Min/Max - Valid range for numeric variables
Pattern - Regex pattern for string validation

Categorical Values:

For variables with a fixed set of allowed values:

Click “Add Value”
Enter the value, label, and description
Repeat for all categories

Global Missing Value Codes

Define codes that represent missing values across all variables:

Common codes: NA, N/A, -999, ., null
Add custom codes specific to your data

Generating a Data Dictionary

Click “Generate Human-Readable Dictionary” to create a formatted HTML document:

Choose whether to include missing value codes
Click “Generate Dictionary”

The HTML file is saved to your dataset folder and can be: - Opened in any web browser - Printed to PDF using Ctrl+P / Cmd+P - Shared with collaborators

Validate Dataset

Check your dataset against the Psych-DS specification:

Running Validation

Select your dataset directory
Click “Validate”
Review the results

Validation Checks

The validator checks:

✅ Required files present (dataset_description.json)
✅ Valid JSON syntax and structure
✅ Required metadata fields populated
✅ Data files in correct location
✅ Filename conventions followed
✅ Schema.org vocabulary used correctly

Understanding Results

Results are shown as a checklist with:

Pass (green) - Check passed
Fail (red) - Issue found that must be fixed

Click on any item to see details and suggestions for fixing issues.

Dataset Explorer

Browse any Psych-DS dataset interactively:

Load a dataset - Select a Psych-DS dataset folder (datasets you have just created or validated are filled in automatically)
Browse files - Click a data file to view its contents
Filter and summarize - Filter rows by keyword values, select columns, and view summaries including missing-data counts

Because all Psych-DS datasets share the same structure, the explorer works on any compliant dataset, not just ones created with this app.

Troubleshooting

App won’t start

# Check dependencies
check_psychds_deps(detailed = TRUE)

# Try forcing external browser
run_psych_ds_app(force_browser = TRUE)

Validation errors

Read the error message carefully
Check that dataset_description.json exists and is valid JSON
Ensure the data/ folder exists with at least one data file

For more help, open an issue.