% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/package.R
\docType{package}
\name{tidyILD-package}
\alias{tidyILD}
\alias{tidyILD-package}
\title{tidyILD: Tidy Intensive Longitudinal Data Analysis}
\description{
tidyILD is a reproducible, tidyverse-style framework for intensive longitudinal
data (ILD) analysis in R, with built-in methodological safeguards, provenance
tracking, and reporting tools. It supports ecological momentary assessment
(EMA) and diary studies with a tidy pipeline from raw data to mixed-effects
models: explicit time structure, within-between decomposition, spacing-aware
lags, and diagnostics. Use it when you have repeated measures per person over
time and want consistent handling of time, gaps, centering, and residual
correlation (AR1/CAR1).
}
\details{
All ILD structure (`.ild_*` columns and `ild_*` metadata) is created only
by \code{\link{ild_prepare}} (via the internal constructor). Downstream
functions expect data prepared with \code{ild_prepare()}. For the full
workflow and applications, see the vignettes. Estimands that require
\strong{joint multivariate dynamics}, \strong{penalized high-dimensional}
longitudinal models, or full \strong{latent-variable DSEM} are better handled
by specialist packages after preprocessing; see
\code{vignette("ild-specialist-backends", package = "tidyILD")}.
}
\section{Getting started}{

A minimal workflow: simulate or load data, prepare with
\code{\link{ild_prepare}}, inspect with \code{\link{ild_summary}}, apply
\code{\link{ild_center}} and \code{\link{ild_lag}}, fit with
\code{\link{ild_lme}} or \code{\link{ild_fit}} (same engines plus optional
\code{backend = "brms"}), then \code{\link{ild_diagnostics}} or
\code{\link{ild_plot}}. State-space: \code{\link{ild_kfas}}. See the examples below.
}

\section{Function index by topic}{

\describe{
  \item{Contracts (schemas)}{\code{\link{ild_diagnostics_bundle}}, \code{\link{guardrail_registry}},
    \code{\link{ild_tidy_schema}}, \code{\link{ild_augment_schema}}}
  \item{Setup and validation}{\code{\link{ild_prepare}}, \code{\link{ild_as_tsibble}},
    \code{\link{as_ild}},
    \code{\link{is_ild}}, \code{\link{validate_ild}}, \code{\link{ild_meta}}}
  \item{Summaries and inspection}{\code{\link{ild_summary}},
    \code{\link{ild_spacing_class}}, \code{\link{ild_spacing}},
    \code{\link{ild_design_check}}, \code{\link{ild_missing_pattern}},
    \code{\link{ild_missing_compliance}}, \code{\link{ild_missing_cohort}},
    \code{\link{ild_missing_hazard_first}}, \code{\link{ild_missingness_report}},
    \code{\link{ild_missing_bias}}, \code{\link{ild_missing_model}},
    \code{\link{ild_ipw_weights}}, \code{\link{ild_ipw_refit}},
    \code{\link{ild_plot}} (types: trajectory, gaps, missingness, predicted_trajectory).
    These overlap with \code{\link{ild_diagnostics_utilities}} (bundle section providers).}
  \item{Within-person and lags}{\code{\link{ild_center}}, \code{\link{ild_center_plot}},
    \code{\link{ild_decomposition}}, \code{\link{ild_lag}}, \code{\link{ild_check_lags}},
    \code{\link{ild_panel_lag_prepare}}, \code{\link{ild_crosslag}}, \code{\link{ild_align}}}
  \item{Modeling}{\code{\link{ild_fit}} (unified: lme4, nlme, brms), \code{\link{ild_lme}},
    \code{\link{ild_brms}} (Bayesian), \code{\link{ild_kfas}} (KFAS state-space; not via \code{ild_fit}),
    \code{\link{ild_person_model}}, \code{\link{ild_heterogeneity}}, \code{\link{ild_heterogeneity_stratified}},
    \code{\link{ild_tvem}} (time-varying effects)}
  \item{Diagnostics and visualization}{\code{\link{ild_diagnose}} (\code{\link{ild_diagnostics_bundle}}),
    \code{\link{ild_diagnostics_utilities}}, \code{\link{ild_acf}}, \code{\link{ild_diagnostics}},
    \code{\link{ild_plot}} (types: fitted, predicted_trajectory, residual_acf; optional \code{facet_by}),
    \code{\link{ild_plot_predicted_trajectory}}, \code{\link{ild_heatmap}},
    \code{\link{ild_spaghetti}}, \code{\link{ild_circadian}}, \code{\link{ild_tvem_plot}}}
  \item{Provenance and methods}{\code{\link{ild_provenance}}, \code{\link{ild_history}},
    \code{\link{ild_methods}}, \code{\link{ild_report}}, \code{\link{ild_compare_pipelines}},
    \code{\link{ild_compare_fits}}, \code{\link{ild_export_provenance}}}
  \item{Reproducibility}{\code{\link{ild_manifest}}, \code{\link{ild_bundle}}}
  \item{Package standards (developers)}{\code{vignette("developer-contracts", package = "tidyILD")};
    normative spec: \code{system.file("dev", "DEVELOPER_CONTRACTS.md", package = "tidyILD")}}
  \item{Utilities and data}{\code{\link{ild_simulate}}, \code{\link{ild_power}}, \code{\link{ema_example}}}
  \item{Person-level}{\code{\link{ild_person_model}}, \code{\link{ild_person_distribution}}}
  \item{Model tidiers}{\code{\link{ild_prior_ild}}, \code{\link{ild_tidy}}, \code{\link{ild_augment}},
    \code{\link{ild_diagnose}}, \code{\link{ild_autoplot}},
    \code{\link{augment_ild_model}}, \code{\link{tidy_ild_model}}
    (model or robust SE via \code{se = "robust"}), \code{\link{ild_robust_se}};
    \code{\link{tidy.ild_lme}}, \code{\link{augment.ild_lme}} (broom.mixed, see \code{\link{broom_ild_lme}})}
}
}

\section{Visualization}{

\code{\link{ild_plot}}, \code{\link{ild_spaghetti}}, and \code{\link{ild_heatmap}} cover trajectories,
heatmaps, gaps, and missingness; optional \code{facet_by} adds panels (e.g. by cluster).
For observed and fitted lines over time, use \code{\link{ild_plot_predicted_trajectory}} or
\code{ild_plot(..., type = "predicted_trajectory")}. After \code{\link{ild_diagnose}}, use
\code{\link{ild_autoplot}} on the bundle. Backend-specific plots include \code{\link{ild_tvem_plot}},
\code{\link{ild_plot_states}}, \code{\link{ild_plot_forecast}}, and \code{\link{ild_plot_filtered_vs_smoothed}}
(KFAS). See \code{vignette("visualization-in-tidyILD", package = "tidyILD")} for a question-to-function map
and recipes (including partial effects via \strong{marginaleffects} / \strong{ggeffects} on \code{_wp} / \code{_bp} columns).
}

\section{Vignettes}{

\code{browseVignettes("tidyILD")} lists all vignettes. Key entries:
\itemize{
  \item \emph{From raw data to model with tidyILD} --- Full pipeline:
    prepare, inspect, center, lag, fit, diagnose.
  \item \emph{Visualization in tidyILD} --- Index of plots, bundle sections, \code{facet_by},
    predicted trajectories, and partial-effects templates.
  \item \emph{Short analysis report} --- Fit, tidy fixed effects,
    fitted vs observed, residual ACF and Q-Q.
  \item \emph{Within-between decomposition and irregular spacing} ---
    Centering (BP/WP), gap-aware lags, spacing classification.
  \item \emph{Temporal dynamics: choosing a model for ILD} ---
    Maps estimands to lags, residual AR (\code{ild_lme}), time-varying effects (\code{ild_tvem}),
    and state-space backends (\code{ild_kfas}, \code{ild_ctsem}).
  \item \emph{Specialist backends: when to move beyond the default stack} ---
    Handoffs to dynamite, PGEE, DSEM, and multivariate workflows; export patterns after prepare/center/lag.
  \item \emph{Reproducible ILD workflows with tidyILD provenance} ---
    Inspect history, generate methods text, ild_report(), export and compare pipelines.
  \item \emph{Glossary and quick-start checklist} --- Table of main
    functions and a short checklist.
  \item \emph{Heterogeneity and person-specific effects} --- BLUPs vs \code{ild_person_model},
    \code{ild_heterogeneity()}, bundle plots.
  \item \emph{Missingness in ILD: diagnostics and sensitivity routes} ---
    \code{ild_missingness_report()}, MAR/MNAR context, IPW templates.
}
}

\section{Key concepts}{

\itemize{
  \item \strong{ILD:} Intensive longitudinal data; many repeated
    measurements per person over time (e.g. EMA).
  \item \strong{Within-between decomposition:} \code{\link{ild_center}}
    adds \code{_bp} (person mean) and \code{_wp} (within-person deviation);
    use WP for within-person effects and BP for between-person or
    cross-level terms.
  \item \strong{Spacing-aware lags:} \code{\link{ild_lag}} supports
    \code{index}, \code{gap_aware} (NA when \code{gap > max_gap}), and
    \code{time_window}; avoids misalignment from assuming equal spacing.
  \item \strong{Residual correlation:} \code{\link{ild_lme}} can fit nlme
    with AR1 or CAR1 for residual autocorrelation;
    \code{\link{ild_spacing_class}} helps choose \code{regular-ish} vs
    \code{irregular-ish} spacing.
  \item \strong{Person-level:} \code{\link{ild_person_model}} fits models separately
    per participant; \code{\link{ild_person_distribution}} plots the distribution of
    estimates across persons (N-of-1 / idiographic). \code{\link{ild_heterogeneity}} summarizes
    partial-pooling person-specific effects from mixed models (contrasts with no pooling).
}
}

\examples{
library(tidyILD)
d <- ild_simulate(n_id = 10, n_obs_per = 12, irregular = TRUE, seed = 42)
x <- ild_prepare(d, id = "id", time = "time", gap_threshold = 7200)
ild_summary(x)
x <- ild_center(x, y)
x <- ild_lag(x, y, mode = "gap_aware", max_gap = 7200)
fit <- ild_lme(y ~ 1, data = x, ar1 = TRUE, correlation_class = "CAR1")
ild_diagnostics(fit, data = x)
ild_plot(fit, type = "fitted")

}
\seealso{
\code{\link{browseVignettes}} and \code{vignette(package = "tidyILD")} for
vignettes. Core entry points: \code{\link{ild_prepare}}, \code{\link{ild_lme}}.
\code{vignette("ild-specialist-backends", package = "tidyILD")} for using
tidyILD as a preprocessing layer with external multivariate or high-dimensional estimators.
Related packages: \pkg{lme4}, \pkg{nlme} (model backends),
\pkg{broom.mixed} (tidiers).
}
\author{
Alex Litovchenko \email{al4877@columbia.edu}
}
