Package 'tidyILD'

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 [email protected]

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

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.

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.

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.

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.

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

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)

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

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

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

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

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.

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

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].

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()].

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

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

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.

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)

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.

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)

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

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)

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

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()].

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)

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

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

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)

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

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

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.

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()).

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.

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()]

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.

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)

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)

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)

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)

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)

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)

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)

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

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.

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)

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

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.

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)

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

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

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

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

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

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

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

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

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

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.

Description

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

Usage

ild_msm_diagnose(object, ...)

Arguments

Value

An ild_diagnostics_bundle.

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

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

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

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

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