docs/shiny_user_guide.md

---
layout: default
title: User Guide
parent: Shiny App
nav_order: 1
---

# Shiny App User Guide

Step-by-step instructions for using the Polyphenol Estimation Pipeline Shiny application.

## Quick Start

1. Open the app (hosted version or run locally)
2. Go to the **Input** tab
3. Click **Load Demo Data** to try with sample data, or upload your own file
4. Click **Run Pipeline**
5. View results in the **Results** tab
6. Use Chart/Table buttons to switch between visualizations and data tables
7. Download results as CSV files

## Data Requirements

### ASA24 Data

Use the **Items Analysis File** from the ASA24 Researcher Site.

**Required columns:**
- `UserName` - Participant identifier
- `FoodCode` - WWEIA food code
- `RecallNo` - Recall number (1, 2, etc.)
- `FoodAmt` - Amount consumed in grams

**Recommended columns for DII calculation:**
- `KCAL`, `PROT`, `TFAT`, `CARB`, `FIBE` and other nutrient columns

**Important:** Each participant must have at least 2 completed recalls.

### NHANES Data

Use the **Individual Foods** file from NHANES dietary data.

**Required columns:**
- `SEQN` - Participant sequence number
- `DRXIFDCD` - Food code
- `RecallNo` - Recall day

**Recommended columns:**
- `DRXIGRMS` - Amount consumed in grams
- `DRXIKCAL`, `DRXIPROT`, `DRXITFAT` and other nutrient columns

## Using the Application

### Step 1: Get Started Tab

The Get Started tab provides:
- Overview of what the pipeline does
- Three-step guide to using the app
- Pipeline workflow diagram

Click **Go to Input** to proceed.

### Step 2: Input Tab

**Select Data Source**

Choose your data format:
- **ASA24** for ASA24 Items files
- **NHANES** for NHANES Individual Foods files

**Upload Data**

Click the upload area or drag and drop your file. Accepted formats:
- CSV (.csv)
- Excel (.xlsx, .xls)

Click "Data format help" for column requirements.

The app validates your data and shows a preview on the right.

**Or Load Demo Data**

Click **Load Demo Data** to test with included sample ASA24 data.

**Configure Options**

- **Include DII Calculation** - Check to compute the 42-component Dietary Inflammatory Index

### Step 3: Run Pipeline

Click **Run Pipeline** to process your data.

A progress indicator shows each step:
1. Preparing dietary data
2. Calculating nutrient totals
3. Disaggregating foods (FDA FDD)
4. Mapping to FooDB
5. Calculating polyphenol content
6. Summarizing total intake
7. Calculating class-level intake
8. Identifying food contributors
9. Calculating DII scores (if enabled)
10. Generating QA/QC report

The app navigates to Results when complete.

### Step 4: View Results

**Summary Cards**

Four cards at the top show:
- Subjects Analyzed
- Mean Polyphenol Intake (mg/day)
- Polyphenol Classes
- Unmapped Foods

**Results Tabs**

Each tab has **Chart** and **Table** buttons in the header. Click to switch views.

**Total Intake**
- Bar chart: Mean intake by subject (top 30)
- Histogram: Distribution of intake across subjects
- Table: Subject-level values

**By Polyphenol Class**
- Bar chart: Mean intake by polyphenol class
- Table: Class-level breakdown per subject

**Food Contributors**
- Treemap: Top 50 foods by polyphenol contribution
- Table: Food contribution details

**DII Scores** (if enabled)
- Histogram: Distribution of DII scores
- Bar chart: Per-subject scores (green = anti-inflammatory, red = pro-inflammatory)
- Table: DII scores with all/no-alcohol variants

### Step 5: QA/QC Tab

The QA/QC tab reports foods that could not be mapped to FooDB.

These items do not contribute to polyphenol estimates. Review the list to assess data quality.

Use Chart/Table buttons to switch between:
- Chart: Distribution of unmapped food percentage by recall
- Table: List of unmapped food items

### Step 6: Download Results

**Individual Downloads**

Each results tab has a download button (download icon) to export that specific table.

**Download All**

Click **Download All Results** at the bottom of the Results tab to get a ZIP file containing:

| File | Contents |
|------|----------|
| `total_intake_by_subject.csv` | Mean polyphenol intake per subject |
| `total_intake_by_recall.csv` | Polyphenol intake per recall |
| `class_intake_by_subject.csv` | Class-level intake per subject |
| `class_intake_by_recall.csv` | Class-level intake per recall |
| `food_contributors.csv` | Food contribution rankings |
| `dii_scores_by_subject.csv` | DII scores per subject (if enabled) |
| `dii_scores_by_recall.csv` | DII scores per recall (if enabled) |
| `unmapped_foods.csv` | Foods not mapped to FooDB (if any) |

## Tips

- **Test first:** Use "Load Demo Data" to explore the app before uploading your data
- **Check QA/QC:** Review unmapped foods to understand data coverage
- **Large files:** Allow extra processing time for datasets with many subjects
- **Reset:** Click "Reset" to clear all data and start over
- **Full screen:** Click the expand icon on any card for full-screen view

## About Page

The About tab contains:
- Pipeline methodology explanation
- Three-step process description
- Information about the 42-component DII calculation
- Credits for pipeline and application development
- Citation information for DII methodology