# Glossary and quick-start checklist

#### tidyILD authors

#### 2026-06-12

## Glossary of main functions

Function | Purpose
--- | ---
[ild_prepare()] | Turn a data frame into an ILD object: parse time, sort, add `.ild_*` columns and spacing metadata.
[ild_summary()] | One-shot summary: n persons, n observations, time range, spacing stats, gaps.
[ild_center()] | Within-between decomposition: add `_bp` (person mean) and `_wp` (within-person) columns.
[ild_lag()] | Spacing-aware lags: index, gap_aware, or time_window with a resolution rule.
[ild_check_lags()] | Audit lag columns: count valid vs invalid (e.g. beyond `max_gap`).
[ild_spacing_class()] | Classify spacing as “regular-ish” or “irregular-ish” (overridable).
[ild_missing_pattern()] | Tabular and (via [ild_plot()] type `"missingness"`) heatmap of missingness.
[ild_lme()] | Fit mixed-effects model: lmer (no AR) or nlme with AR1/CAR1.
[ild_diagnostics()] | Residual ACF, residuals vs fitted/time, Q-Q; optional AR parameter.
[ild_plot()] | Trajectory, heatmap, gaps, missingness, fitted vs observed, residual ACF.
[ild_simulate()] | Simulate simple ILD for examples and tests.

## Quick-start checklist

1. Prepare: `x <- ild_prepare(data, id = "id", time = "time", gap_threshold = ...)`
2. Inspect: `ild_summary(x)`, `ild_plot(x, type = "gaps")`, `ild_plot(x, type = "missingness")`
3. Center: `x <- ild_center(x, var1, var2)` (adds `_bp` and `_wp`)
4. Lag: `x <- ild_lag(x, var1, mode = "gap_aware", max_gap = ...)` or `mode = "time_window", window = ...`
5. Check lags (optional): `ild_check_lags(x, lag_vars = c("var1_lag1"))`
6. Fit: `fit <- ild_lme(formula, data = x, ar1 = TRUE)` (or `ar1 = FALSE`)
7. Diagnose: `ild_diagnostics(fit)` and `ild_plot(fit, type = "fitted")`, `type = "residual_acf"`

## Wide input (strict and explicit)

`ild_prepare()` now supports strict wide-to-long ingestion via `input_format = "wide"`. This conversion runs before standard ILD checks; all downstream functions still receive the same canonical long `ild_tbl`.

    wide <- data.frame(
      id = c(1, 2),
      age = c(30, 40),
      mood_t1 = c(10, 20), mood_t2 = c(11, 21),
      stress_t1 = c(5, 6), stress_t2 = c(7, 8)
    )

    x <- ild_prepare(
      wide,
      id = "id",
      input_format = "wide",
      wide_keep_cols = "age",
      wide_names_pattern = "^(.+)_t(.+)$",
      wide_time_parser = "numeric"
    )

Safety defaults: - non-id columns must match `wide_names_pattern` unless declared in `wide_keep_cols`; - parsed `(measure, time)` slots must be unique; - time tokens must parse cleanly under `wide_time_parser`.

## Comparison with generic workflows

Task | Generic R | tidyILD
--- | --- | ---
Time structure | Manual sort, manual lags, no gap checks | [ild_prepare()] + [ild_lag()] with gap or time-window rules
Within-between | Manual person means, ad hoc naming | [ild_center()] with consistent `_bp`/`_wp`
Residual correlation | nlme syntax heavy; easy to mis-specify | [ild_lme(ar1 = TRUE)] with auto or override AR1/CAR1
Lag validity | Often unchecked | [ild_check_lags()], gap_aware and time_window modes

Same goals, less code and fewer silent errors.