Skip to contents

Using the Shiny Application

Source: vignettes/shiny-app-guide.Rmd
shiny-app-guide.Rmd

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

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:

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

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

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

    • study, session, subject, task, etc.

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

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