---
title: "Using the Shiny Application"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Using the Shiny Application}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
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

```{r}
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:
   - `analysis/` - Analysis scripts and pipelines
   - `materials/` - Study materials (stimuli, protocols, flyers)
   - `results/` - Output figures and tables
   - `products/` - Papers, presentations
   - `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:
   - 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

```{r}
# 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](https://github.com/psych-ds/psychds-r/issues).