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 ild_prepare (via the internal constructor). Downstream functions expect data prepared with ild_prepare(). For the full workflow and applications, see the vignettes. Estimands that require joint multivariate dynamics, penalized high-dimensional longitudinal models, or full latent-variable DSEM are better handled by specialist packages after preprocessing; see vignette("ild-specialist-backends", package = "tidyILD").

Getting started

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

Function index by topic

Contracts (schemas)

ild_diagnostics_bundle, guardrail_registry, ild_tidy_schema, ild_augment_schema

Setup and validation

ild_prepare, ild_as_tsibble, as_ild, is_ild, validate_ild, ild_meta

Summaries and inspection

ild_summary, ild_spacing_class, ild_spacing, ild_design_check, ild_missing_pattern, ild_missing_compliance, ild_missing_cohort, ild_missing_hazard_first, ild_missingness_report, ild_missing_bias, ild_missing_model, ild_ipw_weights, ild_ipw_refit, ild_plot (types: trajectory, gaps, missingness, predicted_trajectory). These overlap with ild_diagnostics_utilities (bundle section providers).

Within-person and lags

ild_center, ild_center_plot, ild_decomposition, ild_lag, ild_check_lags, ild_panel_lag_prepare, ild_crosslag, ild_align

Modeling

ild_fit (unified: lme4, nlme, brms), ild_lme, ild_brms (Bayesian), ild_kfas (KFAS state-space; not via ild_fit), ild_person_model, ild_heterogeneity, ild_heterogeneity_stratified, ild_tvem (time-varying effects)

Diagnostics and visualization

ild_diagnose (ild_diagnostics_bundle), ild_diagnostics_utilities, ild_acf, ild_diagnostics, ild_plot (types: fitted, predicted_trajectory, residual_acf; optional facet_by), ild_plot_predicted_trajectory, ild_heatmap, ild_spaghetti, ild_circadian, ild_tvem_plot

Provenance and methods

ild_provenance, ild_history, ild_methods, ild_report, ild_compare_pipelines, ild_compare_fits, ild_export_provenance

Reproducibility

ild_manifest, ild_bundle

Package standards (developers)

vignette("developer-contracts", package = "tidyILD"); normative spec: system.file("dev", "DEVELOPER_CONTRACTS.md", package = "tidyILD")

Utilities and data

ild_simulate, ild_power, ema_example

Person-level

ild_person_model, ild_person_distribution

Model tidiers

ild_prior_ild, ild_tidy, ild_augment, ild_diagnose, ild_autoplot, augment_ild_model, tidy_ild_model (model or robust SE via se = "robust"), ild_robust_se; tidy.ild_lme, augment.ild_lme (broom.mixed, see broom_ild_lme)

Visualization

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

Vignettes

browseVignettes("tidyILD") lists all vignettes. Key entries:

• From raw data to model with tidyILD — Full pipeline: prepare, inspect, center, lag, fit, diagnose.

• Visualization in tidyILD — Index of plots, bundle sections, facet_by, predicted trajectories, and partial-effects templates.

• Short analysis report — Fit, tidy fixed effects, fitted vs observed, residual ACF and Q-Q.

• Within-between decomposition and irregular spacing — Centering (BP/WP), gap-aware lags, spacing classification.

• Temporal dynamics: choosing a model for ILD — Maps estimands to lags, residual AR (ild_lme), time-varying effects (ild_tvem), and state-space backends (ild_kfas, ild_ctsem).

• Specialist backends: when to move beyond the default stack — Handoffs to dynamite, PGEE, DSEM, and multivariate workflows; export patterns after prepare/center/lag.

• Reproducible ILD workflows with tidyILD provenance — Inspect history, generate methods text, ild_report(), export and compare pipelines.

• Glossary and quick-start checklist — Table of main functions and a short checklist.

• Heterogeneity and person-specific effects — BLUPs vs ild_person_model, ild_heterogeneity(), bundle plots.

• Missingness in ILD: diagnostics and sensitivity routes — ild_missingness_report(), MAR/MNAR context, IPW templates.

Key concepts

• ILD: Intensive longitudinal data; many repeated measurements per person over time (e.g. EMA).

• Within-between decomposition: ild_center adds _bp (person mean) and _wp (within-person deviation); use WP for within-person effects and BP for between-person or cross-level terms.

• Spacing-aware lags: ild_lag supports index, gap_aware (NA when gap > max_gap), and time_window; avoids misalignment from assuming equal spacing.

• Residual correlation: ild_lme can fit nlme with AR1 or CAR1 for residual autocorrelation; ild_spacing_class helps choose regular-ish vs irregular-ish spacing.

• Person-level: ild_person_model fits models separately per participant; ild_person_distribution plots the distribution of estimates across persons (N-of-1 / idiographic). ild_heterogeneity summarizes partial-pooling person-specific effects from mixed models (contrasts with no pooling).

Author(s)

Alex Litovchenko al4877@columbia.edu

See Also

browseVignettes and vignette(package = "tidyILD") for vignettes. Core entry points: ild_prepare, ild_lme. vignette("ild-specialist-backends", package = "tidyILD") for using tidyILD as a preprocessing layer with external multivariate or high-dimensional estimators. Related packages: lme4, nlme (model backends), broom.mixed (tidiers).

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")

Coerce to ILD object

Description

If the object already has the required '.ild_*' columns and attributes, validates and returns it (with tidyild_df and ild_tbl class if missing). Otherwise errors.

Usage

as_ild(x)

Arguments

Value

An ILD tibble with class tidyild_df and ild_tbl.

Augment an ILD model fit with fitted values and residuals

Description

Returns a tibble conforming to ild_augment_schema: .ild_id, .ild_time, .outcome, .fitted, .resid, .resid_std, engine, model_class, plus optional columns (see schema). .resid_std is Pearson-type when residuals(fit, type = "pearson") is available and length-matched; otherwise NA (principled but sparse). Used internally by [ild_diagnostics()] and [ild_plot()]. Requires attr(fit, "ild_data"); refit with [ild_lme()] if missing.

Usage

augment_ild_model(fit, ...)

Arguments

Value

A tibble; see ild_augment_schema.

Tidy and augment ild_lme fits with broom.mixed

Description

These S3 methods delegate to [broom.mixed::tidy()] and [broom.mixed::augment()] on the underlying model object so that ild_lme fits work in tidy workflows. Package broom.mixed must be attached (e.g. library(broom.mixed)).

Usage

tidy.ild_lme(x, ...)

augment.ild_lme(x, ...)

Arguments

Value

Same as the corresponding broom.mixed method.

Example EMA-style intensive longitudinal dataset

Description

A small simulated dataset with 10 persons and 14 observations per person, irregular timing, and two variables (mood, stress). For use in examples and vignettes. Use [ild_prepare()] to convert to an ILD object.

Format

A data frame with 140 rows and 4 columns:

id

Person identifier (1–10).

time

POSIXct timestamp (irregular within person).

mood

Simulated mood score.

stress

Simulated stress score.

Source

Simulated with a fixed seed (12345) for reproducibility.

Guardrail rule registry (analysis safety layer)

Description

Returns the canonical catalog of guardrail rules tidyILD may use. Each rule has a stable rule_id, section (bundle slot), severity, and default default_message / default_recommendation text. When you call ild_diagnose, triggered rules appear as rows in ild_diagnostics_bundle$guardrails with message and recommendation possibly customized for the run.

Usage

guardrail_registry()

Value

A tibble with columns rule_id, section, severity, default_message, default_recommendation.

See Also

ild_diagnose, ild_diagnostics_bundle

Autocorrelation function for ILD variables or model residuals

Description

Computes ACF on a variable in ILD data or on residuals from an [ild_lme()] fit. Use this to check whether AR1 is appropriate before fitting models. ACF is computed over the ordered observation sequence (pooled or within person); it does not adjust for irregular time gaps.

Usage

ild_acf(x, ..., by_id = FALSE)

Arguments

Value

A list with acf: a tibble with columns lag and acf (pooled). If by_id = TRUE, acf_by_id is a named list of tibbles (one per person).

Examples

d <- ild_simulate(n_id = 5, n_obs_per = 10, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
ild_acf(x, "y")
fit <- ild_lme(y ~ 1 + (1 | id), data = x, ar1 = FALSE, warn_no_ar1 = FALSE)
ild_acf(fit)

Align a secondary stream to primary ILD within a time window

Description

For each row in the primary ILD, finds observations in the secondary data set (same id, time within window before the primary time) and attaches an aggregated value (e.g. mean, median, or closest). Use when combining self-report with wearables or other streams that have different timestamps.

Usage

ild_align(
  primary,
  secondary,
  value_var,
  window,
  time_secondary = "time",
  fun = c("mean", "median", "closest")
)

Arguments

Value

The primary data with a new column <value_var>_aligned (numeric; NA where no secondary obs in window).

Examples

prim <- ild_prepare(
  data.frame(
    id = rep(1:2, each = 3),
    time = as.POSIXct(rep(c(0, 3600, 7200), 2), origin = "1970-01-01"),
    y = rnorm(6)
  ),
  id = "id", time = "time"
)
sec <- data.frame(
  id = rep(1:2, each = 4),
  time = as.POSIXct(rep(c(0, 1800, 3600, 5400), 2), origin = "1970-01-01"),
  heart_rate = 60 + rnorm(8, 0, 5)
)
ild_align(prim, sec, "heart_rate", window = 3600, fun = "mean")

Convert an ILD object to a tsibble

Description

Wraps [tsibble::as_tsibble()] using the subject and time column names from [ild_meta()] as key and index. When [ild_prepare()] recorded tsibble provenance (ild_tsibble_meta() is non-NULL), the regular argument is set from the stored is_regular flag so the reconstructed interval often matches the original for unchanged data. Otherwise defaults to regular = TRUE.

Usage

ild_as_tsibble(x, ...)

Arguments

Value

A tbl_ts object (see tsibble).

See Also

vignette("tsibble-interoperability", package = "tidyILD")

Examples

d <- ild_simulate(n_id = 4, n_obs_per = 5, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
if (requireNamespace("tsibble", quietly = TRUE)) {
  ts <- ild_as_tsibble(x)
  class(ts)
}

Augment observations with fitted values and residuals (S3 generic)

Description

Dispatches to [augment_ild_model()] for lmerMod and lme objects from [ild_lme()], or the brmsfit method for [ild_brms()]. All methods return tables conforming to ild_augment_schema.

Usage

ild_augment(x, ...)

## S3 method for class 'lmerMod'
ild_augment(x, ...)

## S3 method for class 'lme'
ild_augment(x, ...)

## Default S3 method:
ild_augment(x, ...)

## S3 method for class 'brmsfit'
ild_augment(x, summary = TRUE, ...)

## S3 method for class 'ild_fit_ctsem'
ild_augment(x, ...)

## S3 method for class 'ild_fit_kfas'
ild_augment(x, ...)

Arguments

Column dictionary for ild_augment() outputs

Description

Defines the minimum stable contract for augmented observation-level tables. augment_ild_model and ild_augment methods emit all required columns; see augment_ild_model for .resid_std semantics.

Usage

ild_augment_schema()

Details

**Required columns**

**Optional:** .fitted_lower, .fitted_upper, .influence, .state, .state_lower, .state_upper.

Value

A list with required and optional character vectors.

See Also

ild_tidy_schema, ild_diagnostics_bundle. Reserved prefixes and migration notes: vignette("developer-contracts", package = "tidyILD").

Per-row latent states (long format) for complex multi-state models

Description

For local_level only, use [ild_augment()] which already provides .state for the level. This function is reserved for future multi-state models.

Usage

ild_augment_states(x, ...)

Arguments

Value

A tibble.

Autoplot for ILD model fits or diagnostics (S3 generic)

Description

For ild_diagnostics_bundle from [ild_diagnose()], dispatches by section and type (section-first; see ?ild_autoplot method for ild_diagnostics_bundle). For [ild_diagnostics()], calls [plot_ild_diagnostics()] directly. For lmerMod or lme fits from [ild_lme()], calls [ild_plot()] (default type = "fitted_vs_actual").

Usage

ild_autoplot(x, ...)

## S3 method for class 'ild_diagnostics'
ild_autoplot(x, ...)

## S3 method for class 'lmerMod'
ild_autoplot(x, type = "fitted_vs_actual", ...)

## S3 method for class 'lme'
ild_autoplot(x, type = "fitted_vs_actual", ...)

## Default S3 method:
ild_autoplot(x, ...)

## S3 method for class 'brmsfit'
ild_autoplot(x, type = "pp_check", ...)

## S3 method for class 'ild_fit_ctsem'
ild_autoplot(x, type = c("fitted_vs_actual", "residual_time", "qq"), ...)

## S3 method for class 'ild_fit_kfas'
ild_autoplot(x, type = c("states", "innovations", "signal"), ...)

## S3 method for class 'ild_diagnostics_bundle'
ild_autoplot(x, section = "residual", type = NULL, ...)

Arguments

Fit a Bayesian mixed model to ILD data with brms

Description

Wraps [brms::brm()] with ILD validation, default priors for common longitudinal mixed models, standardized posterior metadata in attr(fit, "ild_posterior"), and analysis provenance (priors, chains, iterations). Attach ild_data for use with [ild_tidy()], [ild_augment()], [ild_diagnose()], and [ild_methods()].

Usage

ild_brms(
  formula,
  data,
  prior = NULL,
  prior_template = c("default", "weakly_informative", "minimal_shrinkage"),
  warn_uncentered = TRUE,
  ...
)

Arguments

Details

Requires packages brms and a Stan backend (rstan or cmdstanr).

Value

A brmsfit object with attributes:

ild_data

The ILD data frame.

ild_posterior

List: sampler settings, prior summary, divergences, etc.

ild_provenance

Standard tidyILD analysis provenance.

See Also

[ild_fit()] with backend = "brms" is equivalent to ild_brms(). For IPW/MSM workflows, full Bayesian joint MSM is not in tidyILD; see [ild_msm_inference].

Template brms formula for person-varying lag slope

Description

Returns a suggested formula and notes for fitting with [ild_brms()]. This does **not** run the model. Identification, priors, and convergence depend on N, T, and scaling; see vignette("brms-dynamics-recipes", package = "tidyILD").

Usage

ild_brms_dynamics_formula(outcome, lag_var, id_var = "id")

Arguments

Value

A list: formula (formula object), notes (character).

See Also

[ild_brms()], [ild_panel_lag_prepare()].

Build MSM lagged history columns from a spec

Description

Applies [ild_lag()] repeatedly according to an [ild_msm_history_spec()] and records a manifest under attr(x, "ild_msm_history_manifest").

Usage

ild_build_msm_history(data, spec, mode = NULL, max_gap = NULL)

Arguments

Value

ILD object with lagged columns added; attributes include ild_msm_history_manifest (tibble with variable, lag, column).

Examples

d <- ild_simulate(n_id = 6, n_obs_per = 5, seed = 1)
d$stress <- rnorm(nrow(d))
d$trt <- rbinom(nrow(d), 1, 0.4)
d <- ild_prepare(d, id = "id", time = "time")
hs <- ild_msm_history_spec(c("stress", "trt"), lags = 1:2)
d2 <- ild_build_msm_history(d, hs)
attr(d2, "ild_msm_history_manifest")

Bundle a result with a reproducibility manifest

Description

Combines a result (e.g. a fit from [ild_lme()] or output from [ild_diagnostics()]) with a manifest and optional label for one-shot saving. Typical use: saveRDS(ild_bundle(fit, label = "model_ar1"), "run.rds"). You can build a manifest with [ild_manifest()] and pass scenario (e.g. from [ild_summary()]) and seed before bundling.

Usage

ild_bundle(result, manifest = NULL, label = NULL)

Arguments

Value

A list with elements result, manifest, label, suitable for [saveRDS()].

Examples

dat <- ild_prepare(ild_simulate(seed = 1), "id", "time")
fit <- ild_lme(y ~ 1 + (1 | id), dat, ar1 = FALSE, warn_no_ar1 = FALSE)
b <- ild_bundle(fit, label = "ar1")
names(b)
b <- ild_bundle(fit, manifest = ild_manifest(seed = 1, scenario = list(n_obs = 50)), label = "run1")

Within-person and between-person decomposition (centering)

Description

For each selected variable, computes the person mean (between-person component) and the within-person deviation (variable minus person mean). Use '*_wp' at level-1 and '*_bp' at level-2 or in cross-level interactions to avoid ecological fallacy and conflation bias. Selected variables must be numeric.

Usage

ild_center(
  x,
  ...,
  type = c("person_mean", "grand_mean"),
  naming = c("suffix", "prefix")
)

Arguments

Value

The same ILD tibble with additional columns. ILD attributes are preserved.

Standalone WP/BP centering plot

Description

Shows within-person deviation and between-person (person mean) distribution for selected variable(s). Uses the same plot as [ild_decomposition(..., plot = TRUE)]. Useful when you only want the visualization without the variance table.

Usage

ild_center_plot(x, ...)

Arguments

Value

A ggplot object (WP vs BP density overlay for the first selected variable).

Examples

d <- ild_simulate(n_id = 10, n_obs_per = 8, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
ild_center_plot(x, y)

Check lag variable validity (gap-aware)

Description

Given an ILD object and lag variable names, reports how many lagged values are valid vs invalid (NA because the time distance to the lagged row exceeded a threshold). Useful to audit lag columns before modeling without re-specifying max_gap.

Usage

ild_check_lags(x, lag_vars = NULL, max_gap = NULL)

Arguments

Value

A data frame with one row per lag variable: var, lag (parsed lag order or "window"), n_valid, n_invalid, n_first, n_total, pct_valid, pct_invalid.

Time-of-day pattern plot for ILD (circadian-style)

Description

Plots a variable by hour of day (or time-of-day) when .ild_time is POSIXct. Useful for EMA (e.g. mood or activity by hour). Does not add columns to the ILD object; hour is derived internally for plotting.

Usage

ild_circadian(x, var, type = c("boxplot", "line"))

Arguments

Value

A ggplot object (variable by hour of day).

Examples

d <- ild_simulate(n_id = 5, n_obs_per = 12, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
ild_circadian(x, y)

Compare fitted models (AIC, BIC, nobs)

Description

Builds a compact comparison table for a named list of fitted objects. Uses [stats::AIC()], [stats::BIC()], and [stats::nobs()] where those methods exist. This is **not** a likelihood-ratio test and does not establish that models are nested; interpret only when model comparison is scientifically appropriate for your estimand.

Usage

ild_compare_fits(fits, guardrail_bundles = NULL)

Arguments

Value

A tibble with columns model, engine (from [ild_methods()] truncated to one line when long), aic, bic, n_obs, converged (best-effort), n_guardrails (if bundles given), and notes (fit-specific caveats).

See Also

vignette("temporal-dynamics-model-choice", package = "tidyILD").

Compare provenance of two objects and report differences

Description

Flattens provenance for each object (data steps plus analysis steps), then compares step sequences and key arguments. Useful to compare preprocessing pipelines, model settings, or to see what changed between two analyses.

Usage

ild_compare_pipelines(x1, x2)

Arguments

Value

A list of class ild_compare_pipelines with only_in_first (step names only in x1), only_in_second, differing (list of per-step arg differences), and summary (character vector of human-readable differences). If either object has no provenance, returns a list with message and empty comparison components.

Examples

set.seed(1)
d <- ild_simulate(n_id = 5, n_obs_per = 6, seed = 1)
x1 <- ild_prepare(d, id = "id", time = "time")
x1 <- ild_center(x1, y)
x2 <- ild_prepare(d, id = "id", time = "time")
x2 <- ild_center(x2, y)
ild_compare_pipelines(x1, x2)

Cross-lag model: lag predictor then fit outcome ~ lag

Description

One-call pipeline: [ild_lag()] the predictor, [ild_check_lags()] to audit, then [ild_lme()] to fit outcome on the lagged predictor. Returns the fit, the lag-term coefficient (estimate, CI, p), and lag validity check.

Usage

ild_crosslag(
  data,
  outcome,
  predictor,
  lag = 1L,
  mode = c("gap_aware", "index", "time_window"),
  max_gap = NULL,
  ar1 = FALSE,
  include_diagnostics = FALSE,
  ...
)

Arguments

Value

A list: fit (fitted model), lag_term (one-row tibble from [tidy_ild_model()] for the lag variable), lag_check (tibble from [ild_check_lags()]), data (ILD with lag column), and optionally diagnostics.

Examples

d <- ild_simulate(n_id = 10, n_obs_per = 8, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
out <- ild_crosslag(x, "y", "y", lag = 1, ar1 = FALSE, warn_no_ar1 = FALSE)
out$lag_term
out$lag_check

Fit a continuous-time state-space model via ctsem

Description

First-class tidyILD wrapper for ctsem. This backend is designed for irregularly spaced ILD where continuous-time dynamics are preferable to discrete-time approximations.

Usage

ild_ctsem(
  data,
  outcome,
  ct_model = NULL,
  model_type = c("stanct", "ctfit"),
  id_col = ".ild_id",
  time_col = ".ild_time_num",
  time_scale = 1,
  ...
)

Arguments

Details

v1 focuses on a conservative single-outcome pathway with explicit class, provenance, and diagnostics compatibility. Users may supply a custom ctsem model object; otherwise a simple 1-manifest local-level style template is used.

Value

An object of class c("ild_fit_ctsem", "ild_fit_model", "ild_analysis"). Attributes ild_data and ild_provenance are attached.

See Also

[ild_tidy()], [ild_augment()], [ild_diagnose()], [ild_autoplot()].

Within-person and between-person variance decomposition

Description

Reports WP and BP variance and their ratio for selected variables. Use as a diagnostic and teaching tool: large ratio suggests within-person variance dominates; small ratio suggests between-person differences dominate. Helps avoid conflating WP and BP effects in modeling.

Usage

ild_decomposition(x, ..., plot = FALSE)

Arguments

Value

A tibble with columns variable, wp_var, bp_var, ratio (wp_var / bp_var; Inf if bp_var is 0). If plot = TRUE, a list with table and plot (ggplot).

Examples

d <- ild_simulate(n_id = 10, n_obs_per = 8, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
ild_decomposition(x, y)

ILD design diagnostics: spacing, WP/BP, missingness, and recommendations

Description

Aggregates [ild_summary()], [ild_spacing()], [ild_spacing_class()], and optionally [ild_decomposition()] and [ild_missing_pattern()] into one design summary. Use before modeling to see spacing class, correlation recommendation, within- vs between-person variance, and missingness.

Usage

ild_design_check(x, vars = NULL)

Arguments

Details

Also a **section provider** for [ild_diagnose()] (see [ild_diagnostics_utilities]).

Value

A list of class ild_design_check: summary (from ild_summary), spacing_class (regular-ish / irregular-ish), spacing (from ild_spacing), recommendation (AR1/CAR1 text), wp_bp (decomposition tibble or NULL), missingness (list with summary tibble and pct_na overall, or NULL). Use print() for a human-readable summary.

Bundle integration

[ild_diagnose()] embeds this object in design$ild_design_check on the ild_diagnostics_bundle.

See Also

[ild_diagnose()], [ild_diagnostics_bundle()]

Other ild_diagnostics_utilities: ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

d <- ild_simulate(n_id = 10, n_obs_per = 8, irregular = TRUE, seed = 1)
x <- ild_prepare(d, id = "id", time = "time", gap_threshold = 7200)
ild_design_check(x, vars = "y")

Engine-agnostic diagnostics façade

Description

Returns a single ild_diagnostics_bundle for lmerMod, lme, brmsfit, ild_fit_kfas, and ild_fit_ctsem. Sections are parallel across engines; see ?ild_diagnostics_bundle. Residual ACF/Q-Q for frequentist models are stored in residual$legacy_ild_diagnostics for [plot_ild_diagnostics()]. For raw residual-only computation without the bundle, call [ild_diagnostics()] directly.

Usage

ild_diagnose(object, ...)

## S3 method for class 'ild_fit_kfas'
ild_diagnose(object, data = NULL, type = NULL, by_id = NULL, ...)

## S3 method for class 'lmerMod'
ild_diagnose(
  object,
  data = NULL,
  type = c("residual_acf", "residual_time", "qq"),
  by_id = TRUE,
  missing_model = FALSE,
  missing_model_predictors = NULL,
  causal_detail = FALSE,
  balance = FALSE,
  balance_treatment = NULL,
  balance_covariates = NULL,
  balance_weights_col = ".ipw_treat",
  balance_by_occasion = FALSE,
  ...
)

## S3 method for class 'lme'
ild_diagnose(
  object,
  data = NULL,
  type = c("residual_acf", "residual_time", "qq"),
  by_id = TRUE,
  missing_model = FALSE,
  missing_model_predictors = NULL,
  causal_detail = FALSE,
  balance = FALSE,
  balance_treatment = NULL,
  balance_covariates = NULL,
  balance_weights_col = ".ipw_treat",
  balance_by_occasion = FALSE,
  ...
)

## S3 method for class 'brmsfit'
ild_diagnose(
  object,
  data = NULL,
  type = c("all", "convergence", "sampler", "ppc"),
  by_id = TRUE,
  ppc_ndraws = 500L,
  missing_model = FALSE,
  missing_model_predictors = NULL,
  causal_detail = FALSE,
  balance = FALSE,
  balance_treatment = NULL,
  balance_covariates = NULL,
  balance_weights_col = ".ipw_treat",
  balance_by_occasion = FALSE,
  ...
)

## S3 method for class 'ild_fit_ctsem'
ild_diagnose(
  object,
  data = NULL,
  type = NULL,
  by_id = NULL,
  missing_model = FALSE,
  missing_model_predictors = NULL,
  causal_detail = FALSE,
  balance = FALSE,
  balance_treatment = NULL,
  balance_covariates = NULL,
  balance_weights_col = ".ipw_treat",
  balance_by_occasion = FALSE,
  ...
)

## Default S3 method:
ild_diagnose(object, ...)

Arguments

Details

**Building blocks:** the same analyses are available as standalone functions ([ild_design_check()], [ild_missing_pattern()], etc.); see [ild_diagnostics_utilities].

Value

An ild_diagnostics_bundle.

See Also

ild_autoplot, ild_diagnostics_bundle, guardrail_registry, ild_diagnostics_utilities, ild_diagnostics

Residual diagnostics for an ILD model

Description

Computes residual ACF (by person and/or pooled), residual vs fitted, residual vs time, and optional Q-Q. Use 'type' to request only specific diagnostics. For 'ild_lme' models with 'ar1 = TRUE', the estimated AR/CAR parameter is reported when 'type' includes '"residual_acf"'.

Usage

ild_diagnostics(
  object,
  data = NULL,
  type = c("residual_acf", "residual_time", "qq"),
  by_id = TRUE,
  ...
)

Arguments

Details

The return value follows a stable schema: 'meta' (engine, ar1, id/time columns, n_obs, n_id), 'data$residuals' (tibble with '.ild_id', '.ild_time', response, '.resid', '.fitted'), and 'stats' (e.g. 'acf', 'ar1_param'). Plots are not stored in the object; use [plot_ild_diagnostics()] to generate them from a diagnostics object. The column .resid is always filled; .fitted is filled when it can be computed without refitting, otherwise it is NA (same for both engines and all type values).

Residual ACF is computed over the ordered observation sequence within person; it does not adjust for irregular time gaps.

Value

A list of class 'ild_diagnostics' with: 'meta' (engine, ar1, id_col, time_col, n_obs, n_id, type, by_id), 'data' (list with 'residuals' = tibble of .ild_id, .ild_time, response (name from formula), .resid, .fitted; data$residuals always exists, .resid is always filled, .fitted is returned when it can be computed without refitting, otherwise NA), 'stats' (list with 'acf' = list(pooled = tibble, by_id = list) when requested, 'ar1_param' = numeric or NULL for lme). Use [plot_ild_diagnostics()] for plots.

Examples

x <- ild_prepare(ild_simulate(n_id = 3, n_obs_per = 6, seed = 1), id = "id", time = "time")
fit <- ild_lme(y ~ 1 + (1 | id), data = x, ar1 = FALSE, warn_no_ar1 = FALSE)
diag <- ild_diagnostics(fit, type = c("residual_acf", "qq"))
plot_ild_diagnostics(diag)

Canonical ILD diagnostics bundle

Description

The bundle has identical top-level slot names for every estimation backend. Content differs by engine; unavailable sections are NULL. warnings and guardrails are always tibbles (possibly 0 rows). Guardrails use the canonical schema documented in guardrail_registry: rule_id, section, severity, triggered, message, recommendation (only triggered rules are stored as rows).

Usage

ild_diagnostics_bundle(
  meta = NULL,
  data = NULL,
  design = NULL,
  fit = NULL,
  residual = NULL,
  predictive = NULL,
  missingness = NULL,
  causal = NULL,
  warnings = NULL,
  guardrails = NULL,
  summary_text = character()
)

new_ild_diagnostics_bundle(
  meta = NULL,
  data = NULL,
  design = NULL,
  fit = NULL,
  residual = NULL,
  predictive = NULL,
  missingness = NULL,
  causal = NULL,
  warnings = NULL,
  guardrails = NULL,
  summary_text = character()
)

is_ild_diagnostics_bundle(x)

Arguments

Details

Several standalone functions **feed** these slots when you use ild_diagnose; see ild_diagnostics_utilities (ild_design_check, ild_missing_pattern, ild_missing_model, ild_ipw_weights).

Bundles returned by ild_diagnose also set attr(bundle, "ild_fit") and attr(bundle, "ild_data") for ild_autoplot; re-run ild_diagnose if these are missing (e.g. after loading a saved bundle without the fitted object).

The print method lists each slot and prints a short summary line: number of warning rows, number of guardrail rows, highest guardrail severity (info < warning), and up to five triggered rule_id values.

Value

An object of class ild_diagnostics_bundle.

is_ild_diagnostics_bundle: logical.

Slots

meta

List or NULL: run ids, engine, dimensions.

data

List or NULL: spacing, gaps, compliance, missingness, distributions.

design

List or NULL: within/between variation, time coverage, occasions, imbalance.

fit

List or NULL: convergence, singularity, optimizer / MCMC diagnostics.

residual

List or NULL: ACF, Q-Q, fitted vs observed, heteroskedasticity.

predictive

List or NULL: CV, PPC, forecast error.

missingness

List or NULL: IPW / imputation summaries when applicable.

causal

List or NULL: weights, positivity, causal diagnostics when applicable.

warnings

Tibble: structured warnings.

guardrails

Tibble: methodological guardrails (see guardrail_registry).

summary_text

Character: short narrative summary.

See Also

ild_diagnose, guardrail_registry, ild_diagnostics_utilities, ild_tidy_schema, ild_augment_schema. Per-section field semantics: vignette("developer-contracts", package = "tidyILD").

Standalone diagnostics utilities and bundle section providers

Description

These functions are **standalone utilities** you can run on prepared ILD data at any time (typically before or alongside modeling). The same logic also **feeds** ild_diagnostics_bundle sections when you call ild_diagnose on a fitted model, so the package presents one coherent diagnostics story: a top-level façade (ild_diagnose) plus reusable building blocks below.

Relationship to ild_diagnose

ild_design_check

Populates the bundle design slot (embedded as design$ild_design_check) and contributes WP/BP and design-time missingness views.

ild_missing_pattern

Drives data (data$missing_pattern, global columns) and missingness (variable-specific summaries when model predictors are known).

ild_missing_model

Not called automatically by ild_diagnose. Use when you fit a missingness model for IPW or interpretation; it is the usual prerequisite for ild_ipw_weights.

ild_ipw_weights

Adds .ipw (and related steps in the IPW workflow). When those columns are present on the ILD data attached to the fit, ild_diagnose fills the bundle causal slot with weight summaries.

ild_iptw_weights, ild_iptw_msm_weights, ild_ipcw_weights, ild_joint_msm_weights

MSM-style inverse-probability weights for treatment (pooled or sequential A_t) and monotone censoring, combined into .ipw. Distinct from outcome missingness IPW above.

ild_msm_bootstrap, tidy_ild_msm_bootstrap

Person-level bootstrap for weighted lmer after ild_ipw_refit; see ild_msm_inference.

ild_msm_balance, ild_ipw_ess, ild_msm_overlap_plot

Weighted covariate balance (SMD), effective sample size, and propensity overlap plots for MSM / IPW workflows.

ild_msm_estimand, ild_msm_fit, ild_msm_diagnose, ild_msm_contrast_over_time, ild_msm_history_spec, ild_build_msm_history, ild_msm_recovery

Estimand-first MSM workflow, one-call diagnostics bridge, time-indexed contrasts, history construction, and simulation-based recovery checks.

See Also

ild_diagnose, ild_diagnostics_bundle, ild_diagnostics

Export provenance to a JSON or YAML file

Description

Writes the full provenance structure (data or analysis) to a file for reproducibility supplements, preregistration appendices, or lab archiving. Requires the jsonlite package for JSON or yaml for YAML.

Usage

ild_export_provenance(x, path, format = c("auto", "json", "yaml"))

Arguments

Value

The path invisibly, after writing the file.

Fit a mixed model to ILD data (unified entry point)

Description

Façade that selects the estimation backend explicitly. Equivalent to calling [ild_lme()] for "lme4" / "nlme", or [ild_brms()] for "brms". Named functions remain the primary APIs for full documentation and examples.

Usage

ild_fit(
  formula,
  data,
  backend = c("lme4", "nlme", "brms"),
  correlation_class = c("auto", "AR1", "CAR1"),
  random = ~1 | .ild_id,
  warn_no_ar1 = TRUE,
  warn_uncentered = TRUE,
  prior = NULL,
  prior_template = c("default", "weakly_informative", "minimal_shrinkage"),
  ...
)

Arguments

Details

**State-space / latent-dynamics models** are not mixed-model formulas: use [ild_kfas()] or [ild_ctsem()] directly; see vignette("kfas-choosing-backend", package = "tidyILD").

To pass backend to brms::brm() (e.g. "rstan" vs "cmdstanr"), use [ild_brms()] directly: ild_fit() reserves backend for the tidyILD engine ("lme4", "nlme", "brms").

Value

A fitted model: lmerMod / lme from [ild_lme()], or brmsfit from [ild_brms()], each with the same attributes as those functions document.

See Also

[ild_kfas()] and [ild_ctsem()] for state-space / latent-dynamics backends (not available via ild_fit()).

ILD heatmap (alias for ild_plot with type = "heatmap")

Description

Person x time heatmap of a variable. See [ild_plot()].

Usage

ild_heatmap(x, var = NULL, facet_by = NULL, ...)

Arguments

Value

A ggplot object.

Heterogeneity and person-specific effects from mixed models

Description

Summarizes **conditional modes** (empirical Bayes / BLUP deviations) and **person-specific coefficients** (fixef + ranef) for hierarchical models fit with [ild_lme()] or [ild_brms()]. Outputs are labeled as **partial-pooling** estimates; they are not the same as no-pooling separate regressions (see [ild_person_model()]) or population-average fixed effects alone.

Usage

ild_heterogeneity(fit, ...)

## S3 method for class 'lmerMod'
ild_heterogeneity(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  conf_level = 0.95,
  ...
)

## S3 method for class 'lme'
ild_heterogeneity(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  conf_level = 0.95,
  ...
)

ild_heterogeneity_stratified(formula, data, subgroup, min_n_id = 5L, ...)

## S3 method for class 'ild_heterogeneity'
ild_tidy(x, ...)

## S3 method for class 'ild_heterogeneity'
ild_autoplot(x, type = c("caterpillar", "histogram"), term = NULL, ...)

## S3 method for class 'brmsfit'
ild_heterogeneity(
  fit,
  term = NULL,
  group = NULL,
  threshold = NULL,
  scale = c("raw", "sd_x", "sd_y"),
  n_draws = 500L,
  ...
)

Arguments

Value

An object of class ild_heterogeneity: a list with meta, random_effects (long tibble), varcorr (tibble), summary (per-term metrics), and fit.

A tibble with one row per successful subgroup fit, including key columns from ild_heterogeneity()$summary flattened (subgroup_level, term, etc.). This is a **descriptive** comparison across refits, not a formal test of variance heterogeneity.

Methods (by generic)

• ild_tidy(ild_heterogeneity): Tidy long table of person-level random effects (for ild_heterogeneity objects).

• ild_autoplot(ild_heterogeneity): Caterpillar or histogram of person-specific effects.

See Also

[ild_tidy.ild_heterogeneity()], [ild_autoplot.ild_heterogeneity()], [ild_heterogeneity_stratified()], [ild_person_model()]

Print a human-readable log of preprocessing or analysis steps

Description

For ILD data, displays data provenance steps. For analysis objects (e.g. from [ild_lme()], [ild_diagnostics()]), displays source data provenance (if any) and analysis steps. Use [ild_provenance()] to get the raw structured object.

Usage

ild_history(x)

Arguments

Value

The provenance object (from [ild_provenance()]) invisibly, or a message if none.

Inverse probability of censoring weights (IPCW) for monotone dropout

Description

Builds **discrete-time** IPCW weights for **monotone loss-to-follow-up**: each person contributes a sequence of observed visits; after the last visit the person is censored. This differs from [ild_missing_model()] + [ild_ipw_weights()], which model **sporadic item missingness** on an outcome.

Usage

ild_ipcw_weights(x, predictors, stabilize = TRUE, trim = c(0.01, 0.99), ...)

Arguments

Details

Internally, each person-occasion row is labeled with an indicator drop_next: whether the person drops before the next scheduled occasion (including the last observed row). A pooled logistic regression models drop_next given covariates; stabilized or unstabilized inverse probabilities are accumulated within person (product over follow-up) to yield .ipw_censor.

**Assumptions:** Monotone censoring, positivity, correct censoring model.

Value

x with added column .ipw_censor. Attribute ild_ipcw_fit holds the fitted glm.

Bundle integration

Adds .ipw_censor. Combine with [ild_iptw_weights()] or [ild_iptw_msm_weights()] via [ild_joint_msm_weights()].

See Also

[ild_iptw_weights()], [ild_joint_msm_weights()]

Other ild_diagnostics_utilities: ild_design_check(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(3)
d <- ild_simulate(n_id = 18, n_obs_per = 7, seed = 3)
d$stress <- rnorm(nrow(d))
x <- ild_prepare(d, id = "id", time = "time")
x <- ild_ipcw_weights(x, predictors = "stress")
summary(x$.ipw_censor)

Sequential MSM inverse probability of treatment weights (IPTW for A_t)

Description

For **time-varying binary treatment** A_t, fits a separate treatment propensity model at each occasion t (pooling persons at that time): P(A_t \mid \bar{L}_t) where \bar{L}_t is supplied by the user (e.g. lags from [ild_lag()], prior treatment, time-varying confounders). The stabilized factor at each person-occasion is multiplied **within person** over time to yield a **cumulative** MSM IPTW in .ipw_treat.

Usage

ild_iptw_msm_weights(
  x,
  treatment,
  history,
  time_var = ".ild_seq",
  stabilize = c("marginal", "prior_treatment", "none"),
  prior_treatment = NULL,
  trim = c(0.01, 0.99),
  ...
)

Arguments

Details

This differs from [ild_iptw_weights()], which fits **one pooled** logistic over all rows (appropriate for a single treatment decision or descriptive pooling, not the standard sequential MSM estimand for \bar{A}_K).

**Assumptions:** Sequential exchangeability given \bar{L}_t, positivity at each t, and correct models. Variance (e.g. bootstrap by person) is not computed here.

Value

x with .ipw_treat set to the cumulative sequential weight. Attributes: ild_iptw_msm_fits (named list of denominator glm fits by occasion), ild_iptw_msm_numerator_fits (same for numerator when prior_treatment).

Stabilization

marginal

Numerator at each occasion uses the sample marginal P(A_t = 1) among rows at that time (same pattern as pooled stabilized IPTW).

prior_treatment

Numerator uses P(A_t \mid A_{t-1}) from a logistic model A_t ~ prior_treatment fit at each occasion (pass prior_treatment column name). Denominator remains P(A_t \mid \bar{L}_t).

none

Unstabilized 1/P(A_t \mid \bar{L}_t) for the observed A_t.

Bundle integration

Sets .ipw_treat for use with [ild_ipcw_weights()] and [ild_joint_msm_weights()].

See Also

[ild_iptw_weights()], [ild_ipcw_weights()], [ild_joint_msm_weights()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(11)
d <- ild_simulate(n_id = 20, n_obs_per = 6, seed = 11)
d$stress <- rnorm(nrow(d))
d$trt <- as.integer(stats::rbinom(nrow(d), 1L, 0.4))
d <- ild_prepare(d, id = "id", time = "time")
d <- ild_lag(d, stress, mode = "gap_aware", max_gap = Inf)
d <- ild_lag(d, trt, mode = "gap_aware", max_gap = Inf)
x <- ild_iptw_msm_weights(d, treatment = "trt", history = ~ stress_lag1 + trt_lag1)
summary(x$.ipw_treat)

Inverse probability of treatment weights (IPTW)

Description

Fits a **single pooled** treatment propensity model (logistic regression) over all person-occasions and computes stabilized or unstabilized IPTW weights (one factor per row). Use this for a **time-invariant** treatment or descriptive pooling. For **time-varying** A_t with a sequential MSM estimand, use [ild_iptw_msm_weights()] instead. Outcome missingness IPW is [ild_missing_model()] + [ild_ipw_weights()].

Usage

ild_iptw_weights(
  x,
  treatment,
  predictors,
  stabilize = TRUE,
  trim = c(0.01, 0.99),
  ...
)

Arguments

Details

**Assumptions:** Positivity (0 < P(A|X) < 1), correct specification of the treatment model. This is sensitivity / MSM-style tooling, not a substitute for careful causal design.

Value

x with added column .ipw_treat. Attributes include ild_iptw_fit (the fitted glm object).

Bundle integration

Adds .ipw_treat. Use [ild_joint_msm_weights()] to combine with .ipw_censor into .ipw for [ild_ipw_refit()] and [ild_diagnose()].

See Also

[ild_iptw_msm_weights()], [ild_ipcw_weights()], [ild_joint_msm_weights()], [ild_ipw_refit()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(2)
d <- ild_simulate(n_id = 20, n_obs_per = 6, seed = 2)
d$stress <- rnorm(nrow(d))
d$trt <- as.integer(d$stress > 0)
x <- ild_prepare(d, id = "id", time = "time")
x <- ild_iptw_weights(x, treatment = "trt", predictors = "stress")
summary(x$.ipw_treat)

Effective sample size from weights

Description

For nonnegative weights w, \mathrm{ESS} = (\sum w)^2 / \sum w^2.

Usage

ild_ipw_ess(
  data,
  weights_col = ".ipw",
  by_occasion = FALSE,
  time_var = ".ild_seq"
)

Arguments

Value

A single numeric (pooled) or a tibble with occasion and ess when by_occasion = TRUE.

Examples

set.seed(1)
d <- ild_simulate(n_id = 10, n_obs_per = 5, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
x$.ipw <- runif(nrow(x), 0.5, 1.5)
ild_ipw_ess(x, ".ipw")
ild_ipw_ess(x, ".ipw", by_occasion = TRUE)

Refit an ILD model with inverse-probability weights (sensitivity analysis)

Description

Takes a fit from [ild_lme()] (or a formula and data) and refits the model using observation weights from [ild_ipw_weights()]. Only the lme4 (lmer) path is supported; nlme (ar1 = TRUE) is not supported for weighted refits. This is a sensitivity tool, not a full MNAR solution.

Usage

ild_ipw_refit(fit_or_formula, data, weights = ".ipw", ar1 = FALSE, ...)

Arguments

Value

A fitted model (lmerMod) with attr(..., "ild_data") set so that [tidy_ild_model()] and [ild_diagnostics()] work. For inference under estimated weights, see [ild_msm_bootstrap()] and [ild_msm_inference].

Examples

set.seed(1)
d <- ild_simulate(n_id = 12, n_obs_per = 10, seed = 1)
d$stress <- rnorm(nrow(d))
d$mood <- d$y
d$mood[sample(nrow(d), 25)] <- NA
x <- ild_prepare(d, id = "id", time = "time")
x <- ild_center(x, mood)
mm <- ild_missing_model(x, "mood", "stress")
xw <- ild_ipw_weights(x, mm, stabilize = TRUE)
fit0 <- ild_lme(mood ~ mood_bp + mood_wp + stress + (1 | id), data = xw,
  ar1 = FALSE, warn_no_ar1 = FALSE)
fitw <- ild_ipw_refit(fit0, data = xw)
tidy_ild_model(fitw)

Compute inverse-probability-of-observation weights from a missingness model

Description

Uses the fitted missingness model from [ild_missing_model()] to compute weights: unstabilized w = 1 / p_obs or stabilized w = mean(p_obs) / p_obs. Weights are trimmed to avoid extremes. Use with [ild_ipw_refit()] for sensitivity analysis. This is diagnostic and sensitivity tooling, not a full MNAR solution.

Usage

ild_ipw_weights(x, miss_fit, stabilize = TRUE, trim = c(0.01, 0.99))

Arguments

Details

Also a **section provider** for [ild_diagnose()] when .ipw is present on the analysis data (see [ild_diagnostics_utilities]).

Value

x with an added column .ipw (numeric). ILD attributes are preserved.

Bundle integration

Adds .ipw to x. When that column is on the ILD data attached to the fit, [ild_diagnose()] fills causal (weight summaries) on ild_diagnostics_bundle.

See Also

[ild_diagnose()], [ild_diagnostics_bundle()], [ild_missing_model()], [ild_iptw_weights()], [ild_ipcw_weights()], [ild_joint_msm_weights()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(1)
d <- ild_simulate(n_id = 15, n_obs_per = 8, seed = 1)
d$stress <- rnorm(nrow(d))
d$mood <- d$y
d$mood[sample(nrow(d), 20)] <- NA
x <- ild_prepare(d, id = "id", time = "time")
mm <- ild_missing_model(x, "mood", "stress")
xw <- ild_ipw_weights(x, mm, stabilize = TRUE)
summary(xw$.ipw)

Joint MSM weights from IPTW and IPCW components

Description

Multiplies .ipw_treat and .ipw_censor into a single analysis weight column (default .ipw) for use with [ild_ipw_refit()] and [ild_diagnose()]. Optional scaling sets the mean joint weight to 1.

Usage

ild_joint_msm_weights(
  x,
  stabilize = c("mean1", "none"),
  trim = c(0.01, 0.99),
  joint_name = ".ipw"
)

Arguments

Value

x with joint_name set; component columns unchanged.

Bundle integration

Sets .ipw (or joint_name) so existing causal diagnostics and guardrails apply to the **joint** weight.

See Also

[ild_iptw_weights()], [ild_iptw_msm_weights()], [ild_ipcw_weights()], [ild_ipw_refit()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(4)
d <- ild_simulate(n_id = 15, n_obs_per = 8, seed = 4)
d$stress <- rnorm(nrow(d))
d$trt <- as.integer(d$stress > 0)
x <- ild_prepare(d, id = "id", time = "time")
x <- ild_iptw_weights(x, "trt", "stress")
x <- ild_ipcw_weights(x, "stress")
x <- ild_joint_msm_weights(x)
summary(x$.ipw)

Fit a Gaussian state-space model via KFAS (single-subject ILD)

Description

Opinionated entry point for **local level** models in v1. Requires the KFAS package. One distinct .ild_id per fit; subset your data first.

Usage

ild_kfas(
  data,
  outcome,
  state_spec = "local_level",
  observation_family = "gaussian",
  time_units,
  irregular_time = FALSE,
  smoother = TRUE,
  forecast_horizon = 0L,
  fit_context = c("single_series", "independent_series_per_id"),
  ...
)

Arguments

Value

An object of class c("ild_fit_kfas", "ild_fit_model", "ild_analysis") with list slots kfas_model, kfs, spec, state_labels, mapping, schema_version, preprocessing. Attributes ild_data and ild_provenance are set.

See Also

inst/dev/KFAS_V1_BACKEND.md, [ild_tidy()], [ild_augment()], [ild_diagnose()].

Conceptual vignettes:

• vignette("kfas-state-space-modeling", package = "tidyILD")

• vignette("kfas-irregular-timing-spacing", package = "tidyILD")

• vignette("kfas-choosing-backend", package = "tidyILD")

Spacing-aware lag within person

Description

Computes lagged values within each person. Use this instead of [dplyr::lag()], which assumes equal spacing and no gaps and is unsafe for irregular ILD.

Usage

ild_lag(
  x,
  ...,
  n = 1L,
  mode = c("index", "gap_aware", "time_window"),
  max_gap = NULL,
  window = NULL,
  resolution = c("closest_prior", "last_in_window", "mean_in_window")
)

Arguments

Value

The same ILD tibble with new lag columns. ILD attributes preserved.

Fit a linear mixed-effects model to ILD

Description

When 'ar1 = FALSE', fits with [lme4::lmer()] (no residual correlation). When 'ar1 = TRUE', fits with [nlme::lme()] using a residual correlation structure: CAR1 (continuous-time) by default for irregular spacing, or AR1 when spacing is regular-ish. Use [ild_spacing_class()] to inform the choice; override with 'correlation_class'.

Usage

ild_lme(
  formula,
  data,
  ar1 = FALSE,
  correlation_class = c("auto", "AR1", "CAR1"),
  random = ~1 | .ild_id,
  warn_no_ar1 = TRUE,
  warn_uncentered = TRUE,
  ...
)

Arguments

Value

A fitted model object (class 'lmerMod' or 'lme') with attribute 'ild_data' (the ILD data) and 'ild_ar1' (logical). When 'ar1 = TRUE', the returned object has class 'ild_lme' prepended and attribute 'ild_random_resolved' (the formula actually passed to nlme, e.g. '~ 1 | M2ID'). See [ild_diagnostics()] and [ild_plot()].

Examples

# lme4 path: formula includes random effects
set.seed(1)
dat <- ild_simulate(n_id = 5, n_obs_per = 6, seed = 1)
dat <- ild_prepare(dat, id = "id", time = "time")
dat <- ild_center(dat, y)
fit_lmer <- ild_lme(y ~ y_bp + y_wp + (1 | id), data = dat,
                    ar1 = FALSE, warn_no_ar1 = FALSE)
# nlme path (may not converge on all platforms; see ?nlme::lme)
## Not run: 
fit_lme <- ild_lme(y ~ y_bp + y_wp, data = dat,
                   random = ~ 1 | id, ar1 = TRUE)

## End(Not run)

Create a reproducibility manifest

Description

Captures timestamp, optional seed, optional scenario fingerprint, session info, and optional git SHA for use when saving or serializing results (e.g. after [ild_lme()] or [ild_diagnostics()]). The return value is a serializable list suitable for [saveRDS()] or [ild_bundle()].

Usage

ild_manifest(
  seed = NULL,
  scenario = NULL,
  include_session = TRUE,
  include_git = FALSE,
  git_path = "."
)

Arguments

Value

A list with elements timestamp (POSIXct), seed (integer or NULL), scenario (as provided or NULL), session_info (list from sessionInfo() or NULL), git_sha (length-1 character or NA). All elements are serializable.

Examples

m <- ild_manifest()
names(m)
m <- ild_manifest(seed = 42, scenario = list(n_obs = 100, formula = "y ~ x"))
m$seed
m$scenario

Get ILD metadata attributes

Description

Returns the metadata attributes set by [ild_prepare()]: user-facing id/time column names, gap threshold, n_units, n_obs, and spacing (descriptive stats only).

Usage

ild_meta(x)

Arguments

Value

A named list of metadata (ild_id, ild_time, ild_gap_threshold, ild_n_units, ild_n_obs, ild_spacing). ild_spacing includes overall stats and may contain by_id, a tibble of per-person spacing stats.

Generate methods-style narrative from provenance

Description

Takes an ILD data object, a model fit, or a diagnostics object and produces a concise methods-style paragraph based on the recorded provenance (data preparation, centering, lagging, modeling, etc.).

Usage

ild_methods(x, robust_se = NULL, bundle = NULL, ...)

Arguments

Details

After fitting, call diag <- ild_diagnose(fit) and pass bundle = diag to surface triggered guardrails in the methods narrative without duplicating [ild_report()]'s structured diagnostics_summary.

Value

A single character string (one or more sentences) suitable for a methods section. Use cat() or print() to display.

Examples

set.seed(1)
d <- ild_simulate(n_id = 5, n_obs_per = 6, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
x <- ild_center(x, y)
ild_methods(x)

Test whether missingness is associated with a predictor (informative missingness)

Description

Fits a logistic model of missingness (binary: is the outcome NA?) on a predictor variable. Use as a diagnostic: if the predictor is significant, missingness may be informative and results could be biased. This function does not correct for missingness; it flags the assumption for sensitivity analyses.

Usage

ild_missing_bias(x, outcome_var, predictor_var, random = FALSE)

Arguments

Value

A list with predictor (name), estimate, std_error, p_value, and message (short note about informative missingness).

Examples

set.seed(1)
d <- ild_simulate(n_id = 20, n_obs_per = 10, seed = 1)
d$stress <- rnorm(nrow(d))
d$mood <- d$y
d$mood[sample(nrow(d), 30)] <- NA  # some missing
x <- ild_prepare(d, id = "id", time = "time")
ild_missing_bias(x, "mood", "stress")

Cohort-level fraction observed by occasion index

Description

For each distinct '.ild_seq' value, computes how many rows exist and what fraction has a non-missing outcome. Optional line plot.

Usage

ild_missing_cohort(x, outcome, plot = TRUE)

Arguments

Details

Uses **within-study sequence** ('.ild_seq'), not calendar time. For irregular timing, interpret as ordinal wave position rather than equal time spacing.

Value

A list with 'by_occasion' (tibble: '.ild_seq', 'n_rows', 'n_obs', 'pct_observed') and if 'plot = TRUE', 'plot'.

See Also

[ild_missing_pattern()], [ild_missing_compliance()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Person-level missingness compliance for one outcome

Description

Per person (after sorting by '.ild_seq'), returns coverage on the outcome, longest streak of observed values, whether missingness is monotone (dropout pattern: once missing, stays missing), and optional comparison to an expected number of occasions.

Usage

ild_missing_compliance(x, outcome, expected_occasions = NULL)

Arguments

Details

**Monotone missing** is defined only when the person has at least one missing outcome: all observations after the first missing are missing. Intermittent missing yields 'FALSE'. **Discrete hazard** for first missing is provided by [ild_missing_hazard_first()] (cohort-level by '.ild_seq').

Value

A tibble with columns '.ild_id', 'n_rows', 'n_obs_outcome', 'pct_nonmissing_outcome', 'longest_run_observed', 'monotone_missing' ('NA' if no missing values on the outcome for that person), and if 'expected_occasions' is set, 'pct_of_expected' and 'meets_expected_rows'.

See Also

[ild_missing_pattern()], [ild_missingness_report()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Discrete hazard of first missing outcome on an ordinal schedule

Description

For each '.ild_seq', estimates the fraction of person-occasions **at risk** (previous occasion observed, or first occasion) that are **missing** on the outcome. This is a coarse discrete-time hazard for **first** missing spell when missingness is intermittent; under **monotone dropout** it matches the usual discrete hazard of dropout.

Usage

ild_missing_hazard_first(x, outcome)

Arguments

Details

**Assumptions:** Rows are ordered within person by '.ild_seq'. The first row per person is always at risk. Later rows are at risk only if the previous row (same person) was non-missing—so a person who is already missing is not counted again. This targets a **first event** narrative; it is not a full repeated-events model.

Value

A tibble with '.ild_seq', 'n_at_risk', 'n_missing', 'hazard'.

See Also

[ild_missing_cohort()], [ild_missing_compliance()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_model(), ild_missing_pattern(), ild_missingness_report()

Fit a model for missingness (diagnostic / sensitivity)

Description

Fits a logistic model predicting whether the outcome is missing from covariates. Use as a diagnostic; then [ild_ipw_weights()] to compute inverse-probability weights and [ild_ipw_refit()] for a sensitivity analysis. This is not a full MNAR solution—treat as diagnostic and sensitivity tooling.

Usage

ild_missing_model(
  x,
  outcome,
  predictors,
  random = FALSE,
  family = stats::binomial(),
  ...
)

Arguments

Details

**Not** run automatically by [ild_diagnose()]; it is the usual prerequisite for [ild_ipw_weights()] when you want IPW summaries in the bundle (see [ild_diagnostics_utilities]).

Value

A list with fit (the fitted model or NULL if no/all missing), tidy (tibble: term, estimate, std_error, p_value), outcome, predictors, and message. If fit is not NULL, p_missing is a numeric vector of predicted P(missing) per row (aligned to x).

Bundle integration

There is no separate “missingness model” slot on the bundle. This function supports the IPW workflow; after [ild_ipw_weights()], [ild_diagnose()] can summarize weights in causal on ild_diagnostics_bundle.

See Also

[ild_diagnose()], [ild_diagnostics_bundle()], [ild_ipw_weights()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_pattern(), ild_missingness_report()

Examples

set.seed(1)
d <- ild_simulate(n_id = 15, n_obs_per = 8, seed = 1)
d$stress <- rnorm(nrow(d))
d$mood <- d$y
d$mood[sample(nrow(d), 20)] <- NA
x <- ild_prepare(d, id = "id", time = "time")
mm <- ild_missing_model(x, "mood", "stress")
mm$tidy

Summarize missingness pattern in ILD

Description

Returns a tabular summary of missingness by person and/or by variable, plus an optional heatmap plot. Complements [ild_summary()] and supports checking data before modeling. When vars = NULL, all non-internal data columns are used (observation presence across variables).

Usage

ild_missing_pattern(
  x,
  vars = NULL,
  max_ids = NULL,
  seed = NULL,
  outcome = NULL,
  expected_occasions = NULL
)

Arguments

Details

Also a **section provider** for [ild_diagnose()] (see [ild_diagnostics_utilities]).

Value

A list with: summary (tibble: one row per var, columns var, n_obs, n_na, pct_na), plot (ggplot2 object for missingness heatmap), by_id, overall, n_complete, vars. When outcome is set, by_id includes compliance columns (see [ild_missing_compliance()]).

Bundle integration

[ild_diagnose()] passes summaries into data$missing_pattern (global) and missingness (model variables) on the ild_diagnostics_bundle.

See Also

[ild_diagnose()], [ild_diagnostics_bundle()]

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missingness_report()

Missingness workflow report (orchestration)

Description

Bundles person-level compliance, pattern summaries, cohort and hazard tables, optional [ild_missing_model()], heuristic flags, and short text snippets for methods sections. This is **diagnostic and reporting** tooling, not a substitute for formal sensitivity analysis or MNAR models.

Usage

ild_missingness_report(
  x,
  outcome,
  predictors = NULL,
  fit_missing_model = TRUE,
  random = FALSE,
  expected_occasions = NULL,
  max_ids = NULL,
  seed = NULL,
  cohort_plot = TRUE
)

Arguments

Value

A list (class 'ild_missingness_report') with:

compliance

Tibble from [ild_missing_compliance()].

pattern

Output of [ild_missing_pattern()] (includes compliance columns on 'by_id' if 'outcome' was passed through).

cohort

List from [ild_missing_cohort()].

hazard

Tibble from [ild_missing_hazard_first()].

flags

Named list: 'dropout_late_pooled' (logical from same heuristic as guardrail 'GR_DROPOUT_LATE_CONCENTRATION').

missing_model

Result of [ild_missing_model()] or 'NULL'.

snippets

Character vector of short paragraphs for copy-paste.

See Also

[ild_missing_pattern()], [ild_missing_bias()], [ild_ipw_weights()], 'vignette("ild-missingness-workflow", package = "tidyILD")'

Other ild_diagnostics_utilities: ild_design_check(), ild_ipcw_weights(), ild_iptw_msm_weights(), ild_iptw_weights(), ild_ipw_weights(), ild_joint_msm_weights(), ild_missing_cohort(), ild_missing_compliance(), ild_missing_hazard_first(), ild_missing_model(), ild_missing_pattern()

Covariate balance (weighted SMD) for MSM / IPW

Description

Computes **standardized mean differences** between weighted treated and control groups for each named covariate. When by_occasion = TRUE, balance is computed **within** each occasion (stratum); when FALSE, all rows are pooled into one pseudo-population.

Usage

ild_msm_balance(
  data,
  treatment,
  covariates,
  weights_col = ".ipw_treat",
  by_occasion = FALSE,
  time_var = ".ild_seq"
)

Arguments

Value

A tibble with columns stratum, covariate, smd, mean_treated, mean_control, ess_stratum, weight_col.

Examples

set.seed(2)
d <- ild_simulate(n_id = 12, n_obs_per = 6, seed = 2)
d$stress <- rnorm(nrow(d))
d$trt <- as.integer(stats::rbinom(nrow(d), 1L, 0.45))
x <- ild_prepare(d, id = "id", time = "time")
x$.ipw_treat <- runif(nrow(x), 0.8, 1.2)
ild_msm_balance(x, treatment = "trt", covariates = "stress", weights_col = ".ipw_treat")

MSM and IPW balance diagnostics

Description

After building weights ([ild_iptw_weights()], [ild_iptw_msm_weights()], [ild_joint_msm_weights()]), assess **covariate balance** (weighted SMD), **effective sample size** (ESS), and **overlap** of fitted propensities. These complement weight summaries in [fill_diagnostics_causal()] and guardrails on weight ranges.

**Weights:** Use .ipw_treat to check balance for the **treatment** mechanism; use .ipw for balance in the **joint** MSM pseudo-population used in the weighted outcome model—they need not coincide.

See Also

[ild_msm_balance()], [ild_ipw_ess()], [ild_msm_overlap_plot()], [ild_iptw_weights()], [ild_iptw_msm_weights()], [ild_joint_msm_weights()], [ild_msm_estimand()], [ild_msm_fit()], [ild_msm_recovery()]

Cluster bootstrap inference for weighted lmer (MSM / IPW sensitivity)

Description

Resamples **clusters** (persons) with replacement, subsets attr(fit, "ild_data") (or data), optionally re-estimates weights, and refits lmer with the same formula. Collects fixed effects across replicates for bootstrap standard errors and percentile confidence intervals.

Usage

ild_msm_bootstrap(
  fit = NULL,
  formula = NULL,
  data = NULL,
  weights_col = ".ipw",
  n_boot = 200L,
  weight_policy = c("fixed_weights", "reestimate_weights"),
  weights_fn = NULL,
  cluster = c("id", "data"),
  cluster_vec = NULL,
  coef_fun = function(f) lme4::fixef(f),
  seed = NULL,
  verbose = FALSE,
  ...
)

Arguments

Value

An object of class ild_msm_bootstrap: replicates (matrix n_boot x p), estimate (point estimates from fit), bootstrap_se, conf_low, conf_high, term_names, n_boot, n_success, n_cluster, metadata, and fit (original). Use [tidy_ild_msm_bootstrap()] for an ild_tidy_schema tibble.

See Also

[ild_msm_inference], [ild_ipw_refit()], [tidy_ild_msm_bootstrap()]

Examples

if (requireNamespace("lme4", quietly = TRUE)) {
  set.seed(5001)
  d <- ild_simulate(n_id = 12, n_obs_per = 6, seed = 5001)
  d$stress <- rnorm(nrow(d))
  d <- ild_prepare(d, id = "id", time = "time")
  d <- ild_center(d, y)
  d$.ipw <- runif(nrow(d), 0.8, 1.2)
  f0 <- ild_lme(y ~ y_bp + y_wp + stress + (1 | id), data = d, ar1 = FALSE,
    warn_no_ar1 = FALSE, warn_uncentered = FALSE)
  fw <- ild_ipw_refit(f0, data = d, weights = ".ipw")
  b <- ild_msm_bootstrap(fw, n_boot = 15L, weight_policy = "fixed_weights", seed = 2)
  print(b)
  tidy_ild_msm_bootstrap(b)
}

Compute MSM contrasts over time from a fitted weighted model

Description

Computes marginal treatment contrasts by occasion using model fixed effects. This helper is intentionally standalone: it accepts either an ild_msm_fit object or a weighted lmerMod with attached ild_data.

Usage

ild_msm_contrast_over_time(
  object,
  treatment = NULL,
  time_var = ".ild_seq",
  target_time = "all",
  conf_level = 0.95
)

Arguments

Value

Tibble with 'ild_tidy_schema' columns plus method, terms, and target_time.

Diagnose an ild_msm_fit result in one call

Description

Convenience bridge to [ild_diagnose()] using object$fit and object$weights_data.

Usage

ild_msm_diagnose(object, ...)

Arguments

Value

An ild_diagnostics_bundle.

Define an MSM estimand specification

Description

Creates a lightweight estimand object used by [ild_msm_fit()]. v1.1 preserves backward compatibility with v1 static ATE calls while adding explicit slots for regime specification, time targeting, and contrasts.

Usage

ild_msm_estimand(
  type = c("ate", "att"),
  regime = "static",
  treatment,
  time_var = ".ild_seq",
  contrast = NULL,
  target_time = "all",
  regime_value = 1,
  dynamic_rule = NULL
)

Arguments

Value

Object of class ild_msm_estimand.

Examples

e <- ild_msm_estimand(treatment = "trt")
e

Fit an MSM-style weighted mixed model from an estimand spec

Description

High-level runner that takes an [ild_msm_estimand()] plus ILD data, builds treatment (and optional censoring) weights, refits a weighted lmer, and optionally computes inference via robust SEs or cluster bootstrap.

Usage

ild_msm_fit(
  estimand,
  data,
  outcome_formula,
  history,
  history_spec = NULL,
  treatment_engine = c("sequential_msm", "pooled"),
  predictors_censor = NULL,
  weights_col = ".ipw",
  stabilize_treat = c("marginal", "prior_treatment", "none"),
  prior_treatment = NULL,
  stabilize_joint = c("mean1", "none"),
  trim = c(0.01, 0.99),
  inference = c("none", "robust", "bootstrap"),
  robust_type = c("CR2", "CR3", "CR0"),
  n_boot = 200L,
  weight_policy = c("fixed_weights", "reestimate_weights"),
  weights_fn = NULL,
  seed = NULL,
  strict_inference = FALSE,
  ...
)

Arguments

Details

v1.1 keeps the v1 workflow and adds explicit capability signaling for inference/regime paths that are degraded or unsupported.

Value

Object of class ild_msm_fit with elements: estimand, history_spec, weights_data, fit, inference, treatment_engine, weights_col. Analysis provenance is attached.

Examples

set.seed(31)
d <- ild_simulate(n_id = 12, n_obs_per = 6, seed = 31)
d$stress <- rnorm(nrow(d))
d$trt <- as.integer(stats::rbinom(nrow(d), 1L, 0.45))
d <- ild_prepare(d, id = "id", time = "time")
d <- ild_center(d, y)
d <- ild_lag(d, stress, max_gap = Inf)
d <- ild_lag(d, trt, max_gap = Inf)
est <- ild_msm_estimand(treatment = "trt")
res <- ild_msm_fit(
  estimand = est,
  data = d,
  outcome_formula = y ~ y_bp + y_wp + stress + trt + (1 | id),
  history = ~ stress_lag1 + trt_lag1,
  predictors_censor = "stress",
  inference = "none",
  warn_no_ar1 = FALSE,
  warn_uncentered = FALSE
)
res$fit

Build a declarative MSM history specification

Description

Creates a lightweight spec object used by [ild_build_msm_history()] to generate lagged confounder/treatment history columns with deterministic names (e.g. stress_lag1, trt_lag2).

Usage

ild_msm_history_spec(
  vars,
  lags = 1L,
  mode = c("gap_aware", "index", "time_window"),
  max_gap = Inf
)

Arguments

Value

Object of class ild_msm_history_spec.

Examples

s <- ild_msm_history_spec(vars = c("stress", "trt"), lags = 1:2)
s

MSM and IPW inference for weighted mixed models

Description

After [ild_ipw_refit()] (or any lmer(..., weights =) with attr(fit, "ild_data")), uncertainty for MSM-style **estimands** should not rely on default lmer standard errors. tidyILD supports:

• Cluster bootstrap — [ild_msm_bootstrap()] resamples persons (clusters), refits the weighted model, and collects fixed effects; use weight_policy = "reestimate_weights" and a weights_fn to re-fit propensity weights on each replicate when that matches your estimand (computationally heavier; preferred for many MSM workflows). weight_policy = "fixed_weights" keeps the weights from the resampled rows (fast approximation; ignores first-stage uncertainty).

• Cluster-robust sandwich Wald — [ild_robust_se()] / [tidy_ild_model(..., se = "robust")] apply clubSandwich at the **person** level on the **weighted outcome model only**; they do **not** account for estimation error in IPW/IPCW weights unless you treat weights as fixed.

• Bayesian — Full joint Bayesian MSM is not built in. See [ild_brms()] for hierarchical outcome models; combining external IPW row weights with Stan is delicate; prefer explicit joint/sensitivity designs and specialized causal packages for Bayes MSM.

See Also

[ild_msm_bootstrap()], [tidy_ild_msm_bootstrap()], [ild_ipw_refit()], [ild_robust_se()], [tidy_ild_model()], [ild_brms()], [ild_msm_estimand()], [ild_msm_fit()]

Propensity overlap plot (pooled or sequential MSM IPTW)

Description

For **pooled** [ild_iptw_weights()], uses attr(data, "ild_iptw_fit") and plots the distribution of fitted P(A=1\mid L) by treatment level.

Usage

ild_msm_overlap_plot(data, treatment, source = c("auto", "pooled", "msm"))

Arguments

Details

For **sequential** [ild_iptw_msm_weights()], uses attr(data, "ild_iptw_msm_fits") and facets by occasion: fitted denominator propensity at each t.

Value

A ggplot object.

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  set.seed(3)
  d <- ild_simulate(n_id = 15, n_obs_per = 5, seed = 3)
  d$stress <- rnorm(nrow(d))
  d$trt <- as.integer(stats::rbinom(nrow(d), 1L, 0.45))
  x <- ild_prepare(d, id = "id", time = "time")
  x <- ild_iptw_weights(x, treatment = "trt", predictors = "stress")
  ild_msm_overlap_plot(x, treatment = "trt", source = "pooled")
}

MSM recovery simulation harness

Description

Repeats an MSM analysis over simulated datasets with known true_ate and summarizes estimation bias, RMSE, CI coverage, and positivity stress summaries.

Usage

ild_msm_recovery(
  n_sim = 100L,
  n_id = 80L,
  n_obs_per = 10L,
  true_ate = 0.5,
  n_boot = 200L,
  inference = c("bootstrap", "robust", "none"),
  seed = 1001L,
  censoring = TRUE,
  scenario_grid = NULL
)

Arguments

Value

List with summary, summary_by_scenario, and sim_results.

Examples

## Not run: 
out <- ild_msm_recovery(n_sim = 10, n_id = 40, n_obs_per = 10, true_ate = 0.5, n_boot = 50)
out$summary

## End(Not run)

Simulate a simple longitudinal MSM scenario

Description

Generates ILD with time-varying treatment, confounding, and optional monotone censoring/dropout under a known treatment effect (true_ate).

Usage

ild_msm_simulate_scenario(
  n_id = 60L,
  n_obs_per = 10L,
  true_ate = 0.5,
  censoring = TRUE,
  positivity_stress = 1,
  treatment_strength = 0.8,
  censoring_strength = 0.6,
  seed = 42L
)

Arguments

Value

ILD object with columns stress and binary trt; attributes include true_ate.

Examples

d <- ild_msm_simulate_scenario(n_id = 20, n_obs_per = 8, true_ate = 0.5, seed = 12)
ild_summary(d)$summary

Prepare several lag columns and audit them

Description

Sequentially applies [ild_lag()] to each named variable with the same mode, max_gap, window, and resolution, then runs [ild_check_lags()] once on all created lag columns. Use this when building multivariate lag specifications (e.g. several predictors or lag orders) with consistent gap or time-window semantics.

Usage

ild_panel_lag_prepare(
  data,
  variables,
  n = 1L,
  mode = c("gap_aware", "index", "time_window"),
  max_gap = NULL,
  window = NULL,
  resolution = c("closest_prior", "last_in_window", "mean_in_window")
)

Arguments

Value

A list with data (ILD with lag columns), lag_vars (names of created columns), check (tibble from [ild_check_lags()]), and spec (list of arguments for provenance).

See Also

vignette("temporal-dynamics-model-choice", package = "tidyILD"), [ild_crosslag()], [ild_lag()].

Plot distribution of person-level estimates from ild_person_model

Description

Draws a histogram or density of the selected term's estimates across persons. Useful to visualize heterogeneity (e.g. distribution of slopes or intercepts).

Usage

ild_person_distribution(
  person_fit,
  term = NULL,
  type = c("histogram", "density")
)

Arguments

Value

A ggplot object.

Fit a model separately per person (N-of-1 / idiographic)

Description

Splits the ILD by person and fits the same formula (e.g. lm) within each. Returns a tibble of person-level estimates for teaching, N-of-1 analysis, or inspecting heterogeneity. Use [ild_person_distribution()] to visualize the distribution of estimates across persons.

Usage

ild_person_model(formula, data, method = c("lm"), min_obs = 2L)

Arguments

Value

A tibble with columns .ild_id (or the id column name from metadata), term, estimate, std_error, p_value, and optionally sigma, n_obs. One row per person per term (long format).

Examples

d <- ild_simulate(n_id = 5, n_obs_per = 8, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
pm <- ild_person_model(y ~ 1, x)
ild_person_distribution(pm, term = "(Intercept)")

ILD-specific plots

Description

Produces trajectory (spaghetti), heatmap, gaps, and (if a fitted model is provided) fitted vs actual and residual ACF. Works for both lmerMod and lme (ild_lme with ar1 = TRUE).

Usage

ild_plot(
  x,
  type = c("trajectory", "heatmap", "gaps", "missingness", "fitted", "fitted_vs_actual",
    "predicted_trajectory", "residual_acf"),
  var = NULL,
  id_var = ".ild_id",
  time_var = c(".ild_time_num", ".ild_seq"),
  max_ids = 20L,
  seed = 42L,
  facet_by = NULL,
  ...
)

Arguments

Value

A single ggplot when 'length(type) == 1', or a named list of ggplots when 'length(type) > 1'.

Examples

x <- ild_prepare(ild_simulate(n_id = 3, n_obs_per = 6, seed = 1), id = "id", time = "time")
fit <- ild_lme(y ~ 1 + (1 | id), data = x, ar1 = FALSE, warn_no_ar1 = FALSE)
ild_plot(fit, type = "fitted_vs_actual")
ild_plot(fit, type = c("fitted_vs_actual", "residual_acf"))

Plot filtered vs smoothed state (first state)

Description

Compares one-step filtered state (att) with smoothed (alphahat) when available.

Usage

ild_plot_filtered_vs_smoothed(x)

Arguments

Value

A ggplot object.

Plot forecast or future simulation (stub when no horizon)

Description

When forecast_horizon > 0 was used in [ild_kfas()], attempts a short ahead forecast via KFAS; otherwise returns an informative empty panel.

Usage

ild_plot_forecast(x, ...)

Arguments

Value

A ggplot object.

Observed and fitted values vs time (trajectory overlay)

Description

Uses [augment_ild_model()] or [ild_augment()] on the fitted object and plots two lines per person (observed vs fitted) against 'time_var'. For a scatter of observed vs fitted, use [ild_plot()] with 'type = "fitted"'.

Usage

ild_plot_predicted_trajectory(
  fit,
  time_var = c(".ild_time_num", ".ild_seq"),
  max_ids = 20L,
  seed = 42L,
  facet_by = NULL
)

Arguments

Value

A 'ggplot' object.

Plot smoothed latent states (first state by default)

Description

Plot smoothed latent states (first state by default)

Usage

ild_plot_states(x, state_index = 1L, ...)

Arguments

Value

A ggplot object.

Simulation-based power analysis for a fixed effect in ILD models

Description

Estimates empirical power by repeatedly simulating data with a known effect (via [ild_simulate()] plus one added predictor), fitting with [ild_lme()], and counting the proportion of runs where the target term is significant (Wald p < alpha). The workflow (simulate, fit, reject/retain) mirrors simulation-based power in packages like mixpower; ild_power() is focused on ILD and ild_lme(). For multi-parameter grids, LRT, or general LMMs, consider mixpower.

Usage

ild_power(
  formula,
  n_sim = 500L,
  n_id,
  n_obs_per,
  effect_size,
  test_term = NULL,
  alpha = 0.05,
  ar1 = FALSE,
  seed = 42L,
  return_sims = FALSE,
  verbose = TRUE,
  ...
)

Arguments

Details

The data-generating process adds one predictor (name from test_term) as standard normal and adds effect_size * predictor to the outcome on top of the base [ild_simulate()] DGP (id, time, y). No change to ild_simulate() is required.

For ar1 = FALSE (lmer), the lme4 backend does not report p-values; inference for the test term uses a Wald z-approximation (estimate / SE) so that power is still computed. For ar1 = TRUE (nlme), p-values come from the model summary.

Value

A list: power (proportion of converged runs with p < alpha), n_sim, n_reject, n_converged, n_failed, alpha, test_term. If return_sims = TRUE, also sim_results (tibble of per-run results).

See Also

[ild_recovery_metrics()] to summarize bias, RMSE, and coverage from return_sims. vignette("benchmark-simulation-recovery", package = "tidyILD") (worked example).

Examples

set.seed(42)
res <- ild_power(
  formula = y ~ x + (1 | id),
  n_sim = 25L,
  n_id = 15L,
  n_obs_per = 10L,
  effect_size = 0.3,
  seed = 42L,
  verbose = FALSE
)
res$power
res$n_reject

Prepare a data frame as an ILD (intensive longitudinal data) object

Description

Validates and encodes longitudinal structure: parses time, sorts by id and time, handles duplicate timestamps, and adds internal columns ('.ild_*') and metadata. All downstream functions assume the result of 'ild_prepare()'.

Usage

ild_prepare(
  data,
  id = NULL,
  time = NULL,
  gap_threshold = Inf,
  duplicate_handling = c("first", "last", "error", "collapse"),
  collapse_fn = NULL
)

Arguments

Value

An ILD tibble with '.ild_*' columns and metadata attributes. Spacing metadata (see [ild_meta()]) includes overall stats and a by_id tibble of per-person spacing stats (median_dt, iqr_dt, n_intervals, pct_gap). Use [ild_summary()] to inspect and check gap flags before modeling.

See Also

vignette("tsibble-interoperability", package = "tidyILD") (tsibble ingestion, provenance, ild_as_tsibble()).

Prior specifications for common ILD mixed models

Description

Returns a brmsprior object suitable for the prior argument of [ild_brms()] / [brms::brm()]. Templates follow weakly informative defaults: Student-t on intercepts and group SDs, normal on regression coefficients, and exponential on residual SD where applicable.

Usage

ild_prior_ild(
  template = c("default", "weakly_informative", "minimal_shrinkage")
)

Arguments

Value

A brmsprior data frame (class brmsprior).

See Also

[ild_brms()]

Return the raw provenance object

Description

For ILD data: returns attr(x, "tidyILD")$provenance (version + steps from preprocessing). For analysis objects (e.g. fits from [ild_lme()], [ild_diagnostics()], [ild_tvem()], [ild_power()], [ild_missing_model()]): returns attr(x, "ild_provenance"), which has source_data_provenance (snapshot of data provenance) and analysis_steps (list of analysis step records).

Usage

ild_provenance(x)

Arguments

Value

For data: list with version and steps. For analysis: list with version, source_data_provenance, analysis_steps. NULL if none.

Recovery metrics from simulation replications

Description

Summarizes **bias**, **RMSE**, and **nominal Wald interval coverage** for a known coefficient using the per-replication table from [ild_power()] when return_sims = TRUE. Purely descriptive; does not run new simulations.

Usage

ild_recovery_metrics(sim_results, truth, level = 0.95, converged_only = TRUE)

Arguments

Value

A one-row tibble with truth, n (rows used), n_total (rows in sim_results if converged_only), mean_estimate, bias, rmse, coverage, level.

See Also

[ild_power()]

Assemble a light report from a model fit

Description

Builds a structured list with methods narrative (from [ild_methods()]), fixed-effects table (from [tidy_ild_model()]), a short diagnostics summary, and the raw provenance. Optionally exports provenance to a file.

Usage

ild_report(fit, export_provenance_path = NULL, robust_se = NULL, ...)

Arguments

Value

A list with a stable schema: meta (list with n_obs, n_id, engine when available), methods, model_table, diagnostics_summary (includes guardrails_narrative and guardrails when [ild_diagnose()] succeeds), provenance, provenance_export_path (character or NULL). When guardrails are triggered, methods_with_guardrails repeats the methods paragraph with guardrails appended (same pattern as ild_methods(fit, bundle = d)).

Examples

set.seed(1)
x <- ild_prepare(ild_simulate(n_id = 5, n_obs_per = 6, seed = 1), id = "id", time = "time")
fit <- ild_lme(y ~ 1 + (1 | id), data = x, ar1 = FALSE, warn_no_ar1 = FALSE)
r <- ild_report(fit)
r$methods
r$model_table

Cluster-robust variance-covariance matrix for ILD model fits

Description

Computes cluster-robust (sandwich) variance estimators with small-sample corrections via the clubSandwich package. Use with [tidy_ild_model()] via se = "robust" for fixed-effect inference. Requires attr(fit, "ild_data"); refit with [ild_lme()] if missing.

Usage

ild_robust_se(
  fit,
  type = c("CR2", "CR3", "CR0"),
  cluster = c("id", "data"),
  cluster_vec = NULL,
  ...
)

Arguments

Details

For fits from [ild_ipw_refit()] with **estimated** IPW/IPCW weights, these SEs apply to the **weighted outcome (mixed) model** only; they do **not** incorporate first-stage uncertainty from the propensity/censoring models unless you treat weights as fixed. For MSM-style inference, prefer [ild_msm_bootstrap()] with an appropriate weight_policy; see [ild_msm_inference].

Value

A list with vcov (matrix), type, cluster_name, engine ("lmer" or "lme"), and optionally message if a fallback was used (e.g. lme not fully supported on this build).

See Also

[tidy_ild_model()] with se = "robust", clubSandwich::vcovCR, [ild_msm_bootstrap()], [ild_msm_inference].

Examples

if (requireNamespace("clubSandwich", quietly = TRUE)) {
  set.seed(1)
  dat <- ild_simulate(n_id = 8, n_obs_per = 6, seed = 1)
  dat <- ild_prepare(dat, id = "id", time = "time")
  dat <- ild_center(dat, y)
  fit <- ild_lme(y ~ y_bp + y_wp + (1 | id), data = dat, ar1 = FALSE, warn_no_ar1 = FALSE)
  rv <- ild_robust_se(fit, type = "CR2")
  rv$engine
  dim(rv$vcov)
}

Simulate simple ILD for examples, tests, and power analysis

Description

Generates a tibble with id, time, and outcome y. Optionally uses AR(1) within-person correlation and configurable WP/BP variance. Use [ild_prepare()] after to get a proper ILD object.

Usage

ild_simulate(
  n_id = 5L,
  n_obs_per = 10L,
  n_time = NULL,
  irregular = FALSE,
  ar1 = NULL,
  wp_effect = 0.5,
  bp_effect = 1,
  seed = 42L
)

Arguments

Value

A data frame with columns id, time (POSIXct), and y.

See Also

vignette("benchmark-simulation-recovery", package = "tidyILD") (simulation benchmarks and DGP description).

Examples

d <- ild_simulate(n_id = 3, n_obs_per = 5, seed = 1)
x <- ild_prepare(d, id = "id", time = "time")
d2 <- ild_simulate(n_id = 100, n_time = 50, ar1 = 0.4, wp_effect = 0.6,
  bp_effect = 0.3, irregular = TRUE, seed = 1)

Spacing diagnostics and correlation-structure recommendation

Description

Reports observation intervals in human-friendly units (e.g. hours) and recommends AR1 vs CAR1 for use in [ild_lme()]. Surfaces the same logic that ild_lme(..., ar1 = TRUE) uses internally so users can see why a correlation structure was chosen.

Usage

ild_spacing(x, gap_large_hours = 12)

Arguments

Value

A list with median_interval (hours), iqr (hours), large_gaps_pct (percent of intervals > gap_large_hours), coefficient_of_variation, recommendation (character: use CAR1 or AR1), and spacing_class (regular-ish or irregular-ish).

Examples

d <- ild_simulate(n_id = 5, n_obs_per = 10, irregular = TRUE, seed = 1)
x <- ild_prepare(d, id = "id", time = "time", gap_threshold = 7200)
ild_spacing(x)

Classify spacing as regular-ish vs irregular-ish

Description

Returns a simple classification for use in documentation or when choosing correlation structure (e.g. AR1 vs CAR1 in [ild_lme()]). The rule is documented and overridable via arguments. Does not change core ILD behavior.

Usage

ild_spacing_class(x, cv_threshold = 0.2, pct_gap_threshold = 10)

Arguments

Value

Character: '"regular-ish"' or '"irregular-ish"'.

See Also

vignette("kfas-irregular-timing-spacing", package = "tidyILD") (KFAS and irregular timing). vignette("ild-decomposition-and-spacing", package = "tidyILD") (within-between and spacing).

ILD spaghetti / person trajectories (alias for ild_plot with type = "trajectory")

Description

Line plot of variable over time, one line per person. See [ild_plot()].

Usage

ild_spaghetti(x, var = NULL, facet_by = NULL, ...)

Arguments

Value

A ggplot object.

One-shot summary of an ILD object

Description

Reports number of persons, number of observations, time range, descriptive spacing (median/IQR of intervals, percent gaps), and duplicate info. Uses [ild_meta()] and '.ild_*' columns only. No hard "regular"/"irregular" label; use [ild_spacing_class()] for that.

Usage

ild_summary(x)

Arguments

Value

A list with elements: summary (one-row tibble with n_id, n_obs, time_min, time_max, prop_gap, median_dt_sec, iqr_dt_sec), n_units, n_obs, time_range, spacing, n_gaps, pct_gap. If ild_prepare() was run on a tbl_ts, tsibble is also present (same as [ild_tsibble_meta()]). The summary tibble is the primary contract for programmatic use.

Tidy fixed effects from an ILD model fit (S3 generic)

Description

Dispatches to [tidy_ild_model()] for lmerMod and lme objects from [ild_lme()], or the brmsfit method for [ild_brms()]. All methods return tables conforming to ild_tidy_schema.

Usage

ild_tidy(x, ...)

## S3 method for class 'lmerMod'
ild_tidy(x, ...)

## S3 method for class 'lme'
ild_tidy(x, ...)

## Default S3 method:
ild_tidy(x, ...)

## S3 method for class 'brmsfit'
ild_tidy(x, intervals = TRUE, object = FALSE, ...)

## S3 method for class 'ild_fit_ctsem'
ild_tidy(x, ...)

## S3 method for class 'ild_fit_kfas'
ild_tidy(x, ...)

Arguments

Column dictionary for ild_tidy() outputs

Description

Minimum stable contract for parameter-level tables returned by ild_tidy. Implementations (tidy_ild_model, ild_tidy.brmsfit) emit all required columns; conf_low / conf_high replace legacy ci_low / ci_high.

Usage

ild_tidy_schema()

Details

**Required columns:** term, component, effect_level, estimate, std_error, conf_low, conf_high, statistic, p_value, interval_type, engine, model_class.

**Optional:** rhat, ess_bulk, ess_tail, pd, rope_low, rope_high.

**interval_type:** Frequentist rows are typically Wald (model or robust; see tidy_ild_model). Bootstrap output from tidy_ild_msm_bootstrap uses bootstrap_percentile (equal-tailed over replicate coefficients).

Value

A list with required and optional character vectors.

See Also

ild_augment_schema, ild_diagnostics_bundle. Full semantics for component, effect_level, and interval_type: vignette("developer-contracts", package = "tidyILD").

Tidy per-time state summaries for ild_kfas

Description

Returns a tibble with one row per time index and columns for the smoothed level (and optional variance). Separate from [ild_tidy()] which tidies **parameters**.

Usage

ild_tidy_states(x, ...)

Arguments

Value

A tibble.

Tsibble provenance from an ILD object

Description

If [ild_prepare()] was called on a tbl_ts, metadata from the source tsibble (key, index, interval summary, regularity) is stored in attr(x, "tidyILD")$tsibble. Returns NULL if the object was not prepared from a tsibble.

Usage

ild_tsibble_meta(x)

Arguments

Value

A named list or NULL.

See Also

[ild_prepare()], [ild_as_tsibble()], vignette("tsibble-interoperability", package = "tidyILD")

Fit a time-varying effects model (TVEM) for ILD

Description

Fits a GAM with a smooth in time and a time-varying coefficient for a predictor using [mgcv::gam()]. Use [ild_tvem_plot()] to plot the time-varying effect. Requires .ild_time_num (or a numeric time column).

Usage

ild_tvem(
  data,
  outcome,
  predictor,
  time_var = ".ild_time_num",
  k = 10L,
  re_id = TRUE,
  ...
)

Arguments

Value

A fitted gam object with class c("tidyild_tvem", "gam", ...) and attribute ild_tvem_meta (list with outcome, predictor, time_var, k, re_id).

Examples

set.seed(1)
d <- ild_simulate(n_id = 10, n_obs_per = 15, seed = 1)
d$x <- rnorm(nrow(d))
x <- ild_prepare(d, id = "id", time = "time")
tv <- ild_tvem(x, "y", "x", k = 5, re_id = TRUE)
ild_tvem_plot(tv)

Plot the time-varying coefficient from a TVEM fit

Description

Builds a line plot of the smooth term for the time-varying effect of the predictor (with optional confidence band). Uses a grid over the time variable and [mgcv::predict.gam()] with type = "terms".

Usage

ild_tvem_plot(tvem_fit, n_grid = 100L, level = 0.95)

Arguments

Value

A ggplot object (time on x-axis, estimated effect on y-axis).

Examples

set.seed(1)
d <- ild_simulate(n_id = 10, n_obs_per = 15, seed = 1)
d$x <- rnorm(nrow(d))
x <- ild_prepare(d, id = "id", time = "time")
tv <- ild_tvem(x, "y", "x", k = 5, re_id = TRUE)
ild_tvem_plot(tv)

Check if an object is a valid ILD tibble

Description

Returns TRUE if the object has all required '.ild_*' columns and 'ild_*' metadata attributes (as set by [ild_prepare()]).

Usage

is_ild(x)

Arguments

Value

Logical.

Plot diagnostics from an ild_diagnostics object

Description

Generates ggplot objects for the requested diagnostic types. Plots are not stored in the diagnostics object; call this function to create them.

Usage

plot_ild_diagnostics(diag, type = NULL)

Arguments

Value

A named list of ggplot objects (e.g. residual_acf, residuals_vs_fitted, residuals_vs_time, qq).

Tidy fixed effects from an ILD model fit

Description

Returns a tibble conforming to ild_tidy_schema: required columns include term, component, effect_level, estimate, std_error, conf_low, conf_high, statistic, p_value, interval_type, engine, model_class; optional Bayesian columns are NA for these engines. component is "fixed" for coefficient rows; effect_level is inferred conservatively from term names (e.g. ⁠_wp⁠/⁠_bp⁠ suffixes) or "population" for the intercept, "unknown" when ambiguous.

Usage

tidy_ild_model(
  fit,
  conf_level = 0.95,
  object = FALSE,
  se = c("model", "robust"),
  robust_type = c("CR2", "CR3", "CR0"),
  ...
)

Arguments

Details

With object = TRUE, returns an object of class tidyild_model (meta + table) for use with print.tidyild_model.

Value

A tibble, or when object = TRUE a list of class tidyild_model.

Model-based vs robust SE

With se = "model" (default), standard errors and CIs come from the fitted model. With se = "robust", cluster-robust (sandwich) SEs are used; CIs and p-values are based on a Wald normal approximation. Install the clubSandwich package to use robust SEs. For **IPW / MSM** weighted lmer fits ([ild_ipw_refit()]), robust SEs do not account for estimated weights; use [ild_msm_bootstrap()] and [tidy_ild_msm_bootstrap()] when you need bootstrap CIs; see [ild_msm_inference].

Tidy fixed effects from ild_msm_bootstrap

Description

Returns a tibble matching ild_tidy_schema with interval_type bootstrap_percentile (equal-tailed over replicate coefficients).

Usage

tidy_ild_msm_bootstrap(x, conf_level = 0.95, ...)

Arguments

Value

A tibble; see ild_tidy_schema.

See Also

[ild_msm_bootstrap()], [ild_msm_inference]

Validate an ILD object and error if invalid

Description

Checks presence and types of '.ild_*' columns and 'ild_*' attributes. Errors with a clear message if anything is missing or invalid. Calls ild_normalize_internal() so legacy objects get attr(x, "tidyILD") and class tidyild_df.

Usage

validate_ild(x)

Arguments

Value

Invisibly returns x if valid.