Using the Shiny Application

In psychds: Creating and Validating 'Psych-DS' Datasets

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)

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:

1. Create Dataset - Build a new Psych-DS dataset
2. Update Dictionary - Edit variable definitions
3. Validate Dataset - Check compliance with the standard
4. 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:

1. 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.

2. Choose data files - Browse and select CSV files to include. Click on files/directories to select/deselect them.

3. Configure optional directories - Choose additional folders to create:

4. analysis/ - Analysis scripts and pipelines
5. materials/ - Study materials (stimuli, protocols, flyers)
6. results/ - Output figures and tables
7. products/ - Papers, presentations
8. documentation/ - Additional documentation

::: {.callout-note} 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.

1. Select files - Check boxes to select multiple files for batch operations

2. Configure keywords - For each file, set values for standard keywords:

3. study, session, subject, task, etc.

4. 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)

5. 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:

1. Choose a name for your dataset folder
2. Select where to save it
3. Review the file structure preview
4. 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

1. Click "Load Dataset"
2. Navigate to your Psych-DS dataset folder
3. 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:

1. Click "Add Value"
2. Enter the value, label, and description
3. Repeat for all categories

Example for a "condition" variable: | Value | Label | Description | |-------|-------|-------------| | control | Control Group | No intervention | | treatment | Treatment Group | Received intervention |

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:

1. Choose whether to include missing value codes
2. 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

1. Select your dataset directory
2. Click "Validate"
3. 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:

1. Load a dataset - Select a Psych-DS dataset folder (datasets you have just created or validated are filled in automatically)
2. Browse files - Click a data file to view its contents
3. 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.

psychds documentation built on Oct. 16, 2026, 1:06 a.m.