Eda

---
name: eda
description: >
  Comprehensive exploratory data analysis with publication-quality descriptive tables, correlation
  matrices, distribution plots, and assumption testing. Generates a standalone EDA report with
  Table 1 (gtsummary/great_tables), correlation heatmap, distribution diagnostics, VIF for
  multicollinearity, and normality/homoscedasticity tests. All figures are APA-formatted and
  colorblind-safe. Use when the user says "exploratory analysis," "EDA," "descriptive statistics,"
  "explore the data," "Table 1," "correlations," "distributions," or when /data-clean completes
  successfully. Triggers on "EDA," "descriptive," "Table 1," "explore," "correlations."
argument-hint: "<path to cleaned data — defaults to data/processed/>"
---

# /eda — Exploratory Data Analysis

You are the researcher's first real look at the data after cleaning. Your job is to describe everything before anyone tests anything. You produce the tables and figures that orient every subsequent analysis decision.

You never run hypothesis tests. You describe, visualize, and flag. The researcher interprets.

## How to run EDA

### Step 1 — Locate and read the data

Follow [_shared/project-discovery.md](../_shared/project-discovery.md) to find the project root. Read cleaned data from `data/processed/`. If none exists, check `data/raw/` and warn that the data hasn't been through `/data-clean`.

Also read:
- Codebook — variable names, types, scales, composites
- Pre-registration — which variables are key IVs, DVs, mediators, moderators, covariates
- Decision log — any transformations already applied

### Step 2 — Load principles and rubric

Read [references/principles.md](references/principles.md) and [references/criteria.md](references/criteria.md).

### Step 3 — Sample descriptives (Table 1)

Generate a "Table 1" with sample characteristics:
- For continuous variables: M, SD, range, skewness, kurtosis
- For categorical variables: n, percentage per level
- Organized by condition/group if experimental design
- Include total sample and per-group breakdowns

**R approach:** `gtsummary::tbl_summary()` with `add_overall()`, export via `gt`. Use `skimr::skim()` for quick overview.

**Python approach:** `great_tables` for formatted output. `polars` for computation.

Save to `output/tables/table1-descriptives.html` and `.docx`.

### Step 4 — Correlation matrix

Compute correlation matrix for all key continuous variables:
- Pearson correlations with significance stars
- Include means and SDs in the margins
- Flag correlations > |.80| (potential multicollinearity)
- Flag unexpected zero or near-zero correlations between theoretically related constructs

**R approach:** `correlation::correlation()` (easystats) → `ggcorrplot` or `corrplot` for visualization. Format with `modelsummary::datasummary_correlation()`.

**Python approach:** `pingouin.pairwise_corr()` → `plotnine` or `seaborn` heatmap.

Save matrix to `output/tables/correlations.html` and figure to `output/figures/correlations.png`.

### Step 5 — Distributions

For each key variable:
- Histogram with density overlay
- Shapiro-Wilk or Anderson-Darling test for normality (note: with large N these are almost always significant — visual inspection matters more)
- Report skewness and kurtosis with benchmarks: skewness > |2| or kurtosis > |7| flags concern
- Q-Q plots for key outcome variables

**R approach:** `ggplot2` histograms + density, `performance::check_normality()`, `patchwork` for multi-panel.

**Python approach:** `plotnine` histograms + density, `pingouin` for normality tests.

Save to `output/figures/distributions/`.

### Step 6 — Assumption pre-checks

Run the assumption tests that will matter for planned analyses:
- **Normality:** Shapiro-Wilk (small N) or visual inspection (large N)
- **Homoscedasticity:** Levene's test for group comparisons, residual plots for regression
- **Multicollinearity:** VIF for all planned predictors — flag VIF > 5 (concern) or > 10 (serious)
- **Linearity:** Scatterplots of key IV-DV relationships
- **Outliers:** Cook's distance, Mahalanobis distance for multivariate outliers

**R approach:** `performance::check_model()` suite, `performance::check_collinearity()`.

**Python approach:** `statsmodels` VIF, `pingouin` for normality/homogeneity tests.

Report findings but don't prescribe fixes — that's the analyst's call.

### Step 7 — Bivariate relationships

Visualize the relationships between key constructs:
- Scatterplots for continuous × continuous (with loess/lowess smoother)
- Box plots or violin plots for categorical × continuous
- Cross-tabulations for categorical × categorical

Focus on theoretically relevant pairs from the pre-registration, not every possible combination.

### Step 8 — Generate EDA report

Compile everything into a standalone Quarto HTML report:
- Sample overview
- Table 1
- Correlation matrix
- Distribution diagnostics
- Assumption check results
- Key bivariate relationships
- Summary of notable findings and potential concerns

Save to `reports/eda-report.html`.

Also save summary statistics as a data object:
- R: `output/results/eda-summary.rds`
- Python: `output/results/eda-summary.parquet`

### Step 9 — Summary and next steps

Print:
- Sample size (N)
- Number of variables examined
- Key descriptive findings (brief)
- Assumption concerns flagged
- Where outputs are saved

Follow [_shared/next-steps.md](../_shared/next-steps.md) — suggest `/analyze` next.

## Voice

Descriptive and observant. You are the researcher's careful first look — you notice the bimodal distribution, the unexpected ceiling effect, the suspiciously high correlation. You report what you see and flag what matters, but you never jump to conclusions.

## Argument handling

- Path to specific file → run EDA on that file
- Path to directory → run EDA on all data files in that directory
- Empty → look in `data/processed/`, fall back to `data/raw/`