Getting Started with cdid

cdid estimates treatment effects from changes within units, even when some outcomes are missing. This guide fits a cohort model, summarizes the results in an event study, and then shows how to estimate effects when treatment can stop or restart. See the full user guide for other specifications. The package builds on Callaway and Sant’Anna (2021) and Bellégo, Benatia and Dortet-Bernadet (2025).

1. Create an incomplete panel

This example follows 900 units for up to five periods. Treatment starts in period 3 for one group. The other group remains untreated. Each unit has two consecutive observed outcomes, so different units contribute changes over different intervals. The treatment effect starts at 1 and increases by 0.25 per period.

library(cdid)
set.seed(20261029)

n_units <- 900
n_periods <- 5

units <- data.frame(
  id = seq_len(n_units),
  x = rbinom(n_units, size = 1, prob = 0.5)
)
units$g <- ifelse(
  runif(n_units) < plogis(-0.2 + 0.4 * units$x),
  3,
  0
)
unit_alpha <- rnorm(n_units)
window_start <- sample.int(n_periods - 1L, size = n_units, replace = TRUE)

panel_data <- data.frame(
  id = rep(units$id, each = n_periods),
  time = rep(seq_len(n_periods), times = n_units),
  g = rep(units$g, each = n_periods),
  x = rep(units$x, each = n_periods)
)

treated_post <- panel_data$g == 3 & panel_data$time >= 3
true_effect <- ifelse(treated_post, 1 + 0.25 * (panel_data$time - 3), 0)
y_latent <- rep(unit_alpha, each = n_periods) +
  (0.4 + 0.2 * panel_data$x) * panel_data$time +
  true_effect +
  rnorm(nrow(panel_data), sd = 0.5)

in_window <- panel_data$time == rep(window_start, each = n_periods) |
  panel_data$time == rep(window_start + 1L, each = n_periods)
panel_data$y <- ifelse(in_window, y_latent, NA_real_)

We verify that (id, time) pairs are unique and count observed outcomes per unit across the unit table units:

stopifnot(!anyDuplicated(panel_data[c("id", "time")]))
obs_per_unit <- tabulate(
  match(panel_data$id[!is.na(panel_data$y)], units$id),
  nbins = nrow(units)
)
table(cohort = units$g, observed_dates = obs_per_unit)
#>       observed_dates
#> cohort   2
#>      0 461
#>      3 439

2. Data requirements and identification conditions

In chained mode, data must have unique (idname, tname) rows, finite numeric calendar dates tname, numeric outcomes yname that are finite when observed and kept as NA when missing (never replaced by 0), and a constant known treatment cohort gname per unit (0 for never treated). No unit is required to have a complete history or an observed outcome at the cohort baseline date (\(t = 2\)). The unit table frame defines the study population \(F\) of size \(N = |F|\): units observed at two or more dates (\(A\)) supply within-unit changes \(\Delta Y_{s,t} = Y_t - Y_s\), while singletons (one observed outcome) and units with no observed outcomes supply no differences but remain in \(F\) for population counts, cohort shares, active selection or imputation models, and influence functions for all study units.

With the default selection = "none", no observation-probability or imputation model is fitted. Instead, for each cohort and each date pair \((s, t)\) used by the estimator, the subset of units observed at both \(s\) and \(t\) is assumed representative of its cohort in the study population with respect to the mean outcome change: \[E[Y_t - Y_s \mid G = g, S_{s,t} = 1] = E[Y_t - Y_s \mid G = g].\] This is a population expectation condition in the study population; it does not require individual units to have identical outcome changes, realized sample means to agree across observation windows, or arbitrary missingness patterns to identify every target. Observation may depend on the time-invariant unit fixed effect \(\alpha_i\) removed by within-unit differencing, provided it does not select on the mean change.

Identification and inference also require: no treatment anticipation before \(g\) (anticipation = 0, so \(t = 2\) is cohort 3’s reference date); conditional parallel trends from the reference period (pt_assumption = "post"); overlap in the active comparison risk sets; for doubly robust estimation (est_method = "dr"), either a correctly specified treatment propensity logit or a correctly specified control outcome-change regression given xformla; and catalog support connecting each target date to the reference date with eligible controls.

In this design, the untreated conditional mean change from \(s\) to \(t\) is \((t - s)(0.4 + 0.2x)\) in both cohorts, so conditional parallel trends and the control regressions hold under either outcome-pooling choice. By default, outcome_pooling = "separate" lets each comparison have its own outcome-regression slopes. Set outcome_pooling = "pooled" to share slopes per calendar step when that restriction is credible. The treatment logit is also correctly specified by ~ x, and the independently assigned observation windows preserve the cohort mean changes in population.

3. Estimating and inspecting group-time effects

We fit chained doubly robust estimation with xformla = ~ x and selection = "none", combining the overlapping adjacent-period comparisons by feasible two-step GMM (gmm_weighting = "optimal"). Here we set bstrap = FALSE and cband = FALSE to compute fast analytical standard errors and pointwise normal confidence intervals; by default (bstrap = TRUE, cband = TRUE), cdid computes multiplier-bootstrap standard errors and simultaneous confidence bands.

fit <- cdid::att_gt(
  yname = "y",
  tname = "time",
  idname = "id",
  gname = "g",
  xformla = ~ x,
  data = panel_data,
  frame = units,
  control_group = "nevertreated",
  est_method = "dr",
  mode = "chained",
  selection = "none",
  pt_assumption = "post",
  bstrap = FALSE,
  cband = FALSE
)
summary(fit)
#> 
#> cdid chained difference-in-differences (chained doubly robust GMM): cdid_MP
#>   cdid 1.3.0.1 result built on did 2.5.1 (tested: did 2.5.1); did's MP methods tabulate the estimates below.
#>   Chained estimators: Bellego C., Benatia D. and V. Dortet-Bernadet (2025). "The Chained Difference-in-Differences." Journal of Econometrics 248, 105783. doi:10.1016/j.jeconom.2024.105783.
#>   Ordinary estimators: Callaway B. and P. H. C. Sant'Anna (2021). "Difference-in-Differences with Multiple Time Periods." Journal of Econometrics 225(2), 200-230. doi:10.1016/j.jeconom.2020.12.001.
#> 
#> Call:
#> cdid::att_gt(yname = "y", tname = "time", idname = "id", gname = "g", 
#>     xformla = ~x, data = panel_data, frame = units, control_group = "nevertreated", 
#>     est_method = "dr", mode = "chained", selection = "none", 
#>     pt_assumption = "post", bstrap = FALSE, cband = FALSE)
#> 
#> Group-Time Average Treatment Effects:
#>  Group Time ATT(g,t) Std. Error [95% Pointwise  Conf. Band]  
#>      3    2   0.0496     0.0917         -0.1302      0.2293  
#>      3    3   0.7934     0.0932          0.6107      0.9761 *
#>      3    4   1.2238     0.1356          0.9579      1.4896 *
#>      3    5   1.4039     0.1659          1.0788      1.7290 *
#> ---
#> Signif. codes: `*' confidence band does not cover 0
#> 
#> P-value for pre-test of parallel trends assumption:  0.588958075147391
#> Control Group:  Never Treated,  Anticipation Periods:  0
#> Estimation Method:  Doubly Robust
#> 
#> Chained support: 4 of 4 requested cells available.
#>   Units: 900 in the unit table, 0 observed at all 5 dates, 900 with at least two observed outcomes.
#>   Observation correction: none (selection = "none").
#>   Parallel trends: PT-post; base_period = "varying".
#>   GMM weighting: optimal (two-step); covariance regularization: not applied (moment covariance well conditioned).
#>   Inference: analytic standard errors, unit-level; pointwise intervals.
#>   Parallel-trends pre-test: W = 0.291974, df = 1, p = 0.589 (Wald test of the pretrend cell).

Compare the estimates with the population targets: 0 for the pre-treatment comparison reported at period 2, and 1.00, 1.25, 1.50 at periods 3, 4, 5. Realized estimates vary across samples; one draw does not establish bias, coverage, or relative efficiency. tidy() exposes cell-level estimates, availability and support reasons; glance() gives a one-row fit summary:

cells <- cdid::tidy(fit)
cells[, c("target.id", "role", "estimate", "std.error",
          "conf.low", "conf.high", "available",
          "support.status", "support.reason")]
#>      target.id role   estimate  std.error   conf.low conf.high available
#> 1 pre(g=3,t=2)  pre 0.04955105 0.09170237 -0.1301823 0.2292844      TRUE
#> 2 ATT(g=3,t=3) post 0.79343581 0.09322092  0.6107262 0.9761455      TRUE
#> 3 ATT(g=3,t=4) post 1.22375601 0.13563479  0.9579167 1.4895953      TRUE
#> 4 ATT(g=3,t=5) post 1.40388077 0.16587612  1.0787695 1.7289920      TRUE
#>              support.status
#> 1 supported_direct_pretrend
#> 2                 estimable
#> 3                 estimable
#> 4                 estimable
#>                                                                         support.reason
#> 1                                 direct auxiliary comparison 1->2 with controls {Inf}
#> 2 level anchored to the cohort reference through retained comparison rows (prop:graph)
#> 3 level anchored to the cohort reference through retained comparison rows (prop:graph)
#> 4 level anchored to the cohort reference through retained comparison rows (prop:graph)
cdid::glance(fit)
#>   nobs ngroup ntime control.group est.method                 estimator
#> 1  900      1     5  nevertreated         dr chained doubly robust GMM
#>   n.requested n.available                         band.family inference
#> 1           4           4 pointwise_normal_over_supported_ids  analytic
#>   clustered
#> 1     FALSE

4. Aggregating effects and event-study plotting

cdid::aggte() aggregates the retained cdid_MP result without refitting and inherits its inference settings unless overridden. We compute the overall post-treatment average (type = "simple") and event-time estimates (type = "dynamic"), inspect the tidy dynamic table, and plot the event study with cdid::ggdid():

agg_simple <- cdid::aggte(fit, type = "simple")
agg_dynamic <- cdid::aggte(fit, type = "dynamic")

summary(agg_simple)
#> 
#> cdid chained difference-in-differences (chained doubly robust GMM): cdid_AGGTEobj
#>   cdid 1.3.0.1 result built on did 2.5.1 (tested: did 2.5.1); did's AGGTEobj methods tabulate the estimates below.
#>   Chained estimators: Bellego C., Benatia D. and V. Dortet-Bernadet (2025). "The Chained Difference-in-Differences." Journal of Econometrics 248, 105783. doi:10.1016/j.jeconom.2024.105783.
#>   Ordinary estimators: Callaway B. and P. H. C. Sant'Anna (2021). "Difference-in-Differences with Multiple Time Periods." Journal of Econometrics 225(2), 200-230. doi:10.1016/j.jeconom.2020.12.001.
#> 
#> Call:
#> cdid::aggte(fit, type = "simple")
#> 
#>     ATT    Std. Error     [ 95%  Conf. Int.]  
#>  1.1404        0.1184     0.9083      1.3724 *
#> 
#> 
#> ---
#> Signif. codes: `*' confidence band does not cover 0
#> 
#> Control Group:  Never Treated,  Anticipation Periods:  0
#> Estimation Method:  Doubly Robust
#> 
#> Chained simple aggregation: 1 of 1 intended aggregate(s) available; na.rm = FALSE.
#>   Parallel trends: PT-post; base_period = "varying".
#>   Inference: analytic standard errors, unit-level; pointwise intervals.
cdid::tidy(agg_dynamic)[, c("label", "estimate",
                            "std.error", "conf.low", "conf.high",
                            "available", "reason")]
#>      label   estimate  std.error   conf.low conf.high available          reason
#> 1 event_-1 0.04955105 0.09170237 -0.1301823 0.2292844      TRUE intended_target
#> 2  event_0 0.79343581 0.09322092  0.6107262 0.9761455      TRUE intended_target
#> 3  event_1 1.22375601 0.13563479  0.9579167 1.4895953      TRUE intended_target
#> 4  event_2 1.40388077 0.16587612  1.0787695 1.7289920      TRUE intended_target
cdid::ggdid(agg_dynamic)

5. Advanced options and further documentation

Choose the treatment adjustment with est_method. Use "reg" for outcome regression, "ipw" for weighting, or "dr" for both. To adjust for missing outcomes that depend on covariates, set selection = "conditional_mtar" and choose observation weighting, change imputation or their augmented combination with selection_est_method.

Use chain_report(fit) to read the comparisons that identify each effect. If target and control cohorts are observed over different date pairs, the guide describes when cross_pair = TRUE can connect their changes. To inspect fitted equations and coefficient tables, use control = list(keep_nuisance = TRUE) when fitting and then call nuisance_models(fit).

6. When treatment can stop and restart

The example above uses gname: after their first treatment date, units remain treated. The resulting cohort effects can be followed over time and aggregated into an event study.

For a history such as 0, 1, 0, 1, supply current binary treatment through dname instead. This requests a static model: earlier treatment has no lingering effect beyond current status, although effects can differ across units and dates. It compares entrants with units that remain untreated and exiters with units that remain treated, under the corresponding parallel-trends assumptions. Both directions are reported as treatment effects, Y(1) - Y(0).

Keep treatment known at every study date, including rows with missing outcomes. The example below has a treatment effect of 1.5, allows exit and re-entry, and makes observation depend on x. It combines treatment DR (est_method) with augmented missing-outcome correction (selection_est_method). These are separate choices.

set.seed(20261106)
n_st <- 320
t_st <- 4
d_paths <- rbind(
  c(0L, 0L, 0L, 0L),
  c(0L, 1L, 1L, 0L),
  c(1L, 1L, 0L, 1L),
  c(1L, 0L, 0L, 1L),
  c(1L, 1L, 1L, 1L)
)
path_idx <- sample.int(nrow(d_paths), size = n_st, replace = TRUE)
x_st <- rnorm(n_st)
alpha_st <- rnorm(n_st, sd = 0.5)

static_panel <- data.frame(
  id = rep(seq_len(n_st), each = t_st),
  time = rep(seq_len(t_st), times = n_st),
  x = rep(x_st, each = t_st),
  d = as.integer(t(d_paths[path_idx, ]))
)
y_st_latent <- rep(alpha_st, each = t_st) +
  (0.3 + 0.2 * static_panel$x) * static_panel$time +
  1.5 * static_panel$d +
  rnorm(nrow(static_panel), sd = 0.4)
static_panel$y <- ifelse(
  runif(nrow(static_panel)) < plogis(0.8 + 0.4 * static_panel$x),
  y_st_latent,
  NA_real_
)

fit_static <- cdid::att_gt(
  yname = "y",
  tname = "time",
  idname = "id",
  dname = "d",
  xformla = ~ x,
  data = static_panel,
  est_method = "dr",
  selection = "conditional_mtar",
  selection_est_method = "dr",
  selection_model = "pair_logit",
  selection_pooling = "within_group",
  imputation_pooling = "within_group",
  imputation_scale = "per_period",
  outcome_pooling = "separate",
  switchers = "both",
  bstrap = FALSE,
  cband = FALSE
)
summary(fit_static)
#> 
#> Call:
#> cdid::att_gt(yname = "y", tname = "time", idname = "id", dname = "d", 
#>     xformla = ~x, data = static_panel, est_method = "dr", selection = "conditional_mtar", 
#>     selection_est_method = "dr", selection_model = "pair_logit", 
#>     selection_pooling = "within_group", imputation_pooling = "within_group", 
#>     imputation_scale = "per_period", outcome_pooling = "separate", 
#>     switchers = "both", bstrap = FALSE, cband = FALSE)
#> 
#> Reference: Static No-Carryover Entry/Exit/Re-Entry DiD (`dname = "d"`)
#>   Chained estimators: Bellego C., Benatia D. and V. Dortet-Bernadet (2025). "The Chained Difference-in-Differences." Journal of Econometrics 248, 105783. doi:10.1016/j.jeconom.2024.105783.
#>   Static binary transition design: de Chaisemartin C., D'Haultfoeuille X., Pasquier F., Sow D. and G. Vazquez-Bare (2026). "Difference-in-Differences Estimators for Treatments Continuously Distributed at Every Period." Working paper, arXiv:2201.06898v7 (revised 2026-07-22), static binary specialization.
#>   Identification benchmark: static potential outcomes Y_{it}(d_{1:t}) = Y_{it}(d_t), known binary D across all study dates
#>   Treatment comparison method: DR (requested: "dr")
#>   Observation route: augmented (selection = "conditional_mtar", selection_est_method = "dr")
#>   Selection model: pair_logit (pooling = "within_group")
#>   Imputation model: WLS actual-change (pooling = "within_group", scale = "per_period")
#>   Outcome regression pooling: separate
#>   GMM weighting: optimal (requested: "optimal")
#>   Study population: n = 320 units across T = 4 dates (repeat-Y: 284, single-Y: 30, zero-Y: 6)
#> 
#> Transition-Cell Treatment Effects (tau_c = sigma_c * theta_c, sigma_c = 1 - 2 * D_{t-1}):
#>      Cell Time Ref    Direction Switchers Stayers      ATT Std.Error
#>  t2_entry    2   1 entry (0->1)        54      71   2.0491    0.1290
#>   t2_exit    2   1  exit (1->0)        68     127   1.5499    0.1169
#>   t3_exit    3   2  exit (1->0)        67     114   1.3064    0.1309
#>  t4_entry    4   3 entry (0->1)       135      71   1.5078    0.0992
#>   t4_exit    4   3  exit (1->0)        54      60   1.3278    0.1140
#>      [95% Pointwise CI] Status
#>  [  1.7963,   2.3019] *     ok
#>  [  1.3208,   1.7790] *     ok
#>  [  1.0499,   1.5630] *     ok
#>  [  1.3134,   1.7022] *     ok
#>  [  1.1044,   1.5512] *     ok
#> ---
#> Signif. codes: `*` confidence interval/band does not cover 0.
#> 
#> Static Switch-Frequency Aggregate (delta_{A, s} across declared target set A):
#>   Estimate:   1.5313   Std. Error:   0.0591   [95% Pointwise CI:   1.4155,   1.6471]   (Total switchers: 378)
#>   Scope: static switcher-frequency weighted average across the declared transition set A with random switch-share influence function (eq:if-agg); not a cohort or dynamic event-time aggregation
#> 
#> Inference & Support Summary:
#>   Standard errors: analytical
#>   Confidence intervals/bands: pointwise_normal
#>   Clustering: unit-level (320 units)
#>   Role-pair graphs: 60 total positive-count edges retained across all required switcher/stayer role blocks
#>   Qualifications: Asymptotic validity requires compatible link moments, regular interior nuisance roots with inactive probability clipping in population, fixed finite support (T, |A|, m_R), and many independent units/clusters (G -> Inf); clustering changes inference only.
fit_static$aggregate[c("estimate", "se", "ci_lower", "ci_upper", "total_switchers")]
#> $estimate
#> [1] 1.531273
#> 
#> $se
#> [1] 0.05908065
#> 
#> $ci_lower
#> [1] 1.415477
#> 
#> $ci_upper
#> [1] 1.647069
#> 
#> $total_switchers
#> [1] 378

The static model adapts the binary specialization of de Chaisemartin et al. (2026), https://arxiv.org/abs/2201.06898v7, using chained comparisons for missing outcomes. Its switcher-weighted average is stored in fit_static$aggregate; aggte() remains for cohort effects. The cohort options of section 5 (cross_pair = TRUE, pt_assumption = "ctrl" or "all", and gmm_weighting = "within") do not apply to this static model and are refused with dname. See the entry and exit guide in the repository for the model assumptions and other treatment and missing-outcome adjustments.

See the installed help pages (?cdid::att_gt, ?cdid::chain_report, ?cdid::aggte, ?cdid::conditional_did_pretest, ?cdid::reexports) and the repository documentation at https://github.com/dvbn/cdid, especially docs/methods/cross-pair-chaining.md, docs/examples/short-pretreatment-windows.md, docs/help/prepare-data.md, docs/help/investigate-missingness.md, docs/methods/missing-outcomes.md, docs/methods/static-entry-exit.md, and the companion notebook.