diff-diff 3.0.0__tar.gz → 3.0.2__tar.gz

{diff_diff-3.0.0 → diff_diff-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 3.0.0
+Version: 3.0.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Information Analysis
 Classifier: Topic :: Scientific/Engineering
@@ -40,7 +41,7 @@ Summary: Difference-in-Differences causal inference with sklearn-like API. Calla
 Keywords: causal-inference,difference-in-differences,econometrics,statistics,treatment-effects,event-study,staggered-adoption,parallel-trends,synthetic-control,panel-data,did,twfe,callaway-santanna,honest-did,sensitivity-analysis
 Author: diff-diff contributors
 License-Expression: MIT
-Requires-Python: >=3.9, <3.14
+Requires-Python: >=3.9, <3.15
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Documentation, https://diff-diff.readthedocs.io
 Project-URL: Homepage, https://github.com/igerber/diff-diff
@@ -125,6 +126,17 @@ After estimation, call `practitioner_next_steps(results)` for context-aware guid
 
 Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 
+## For Data Scientists
+
+Measuring campaign lift? Evaluating a product launch? diff-diff handles the causal inference so you can focus on the business question.
+
+- **[Which method fits my problem?](docs/practitioner_decision_tree.rst)** - Start from your business scenario (campaign in some markets, staggered rollout, survey data) and find the right estimator
+- **[Getting started for practitioners](docs/practitioner_getting_started.rst)** - End-to-end walkthrough: marketing campaign -> causal estimate -> stakeholder-ready result
+- **[Brand awareness survey tutorial](docs/tutorials/17_brand_awareness_survey.ipynb)** - Full example with complex survey design, brand funnel analysis, and staggered rollouts
+- **Have BRFSS/ACS/CPS individual records?** Use [`aggregate_survey()`](docs/api/prep.rst) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights. The returned second-stage design uses analytic weights (`aweight`), so it works directly with `DifferenceInDifferences`, `TwoWayFixedEffects`, `MultiPeriodDiD`, `SunAbraham`, `ContinuousDiD`, and `EfficientDiD` (estimators marked **Full** in the [survey support matrix](docs/choosing_estimator.rst))
+
+Already know DiD? The [academic quickstart](docs/quickstart.rst) and [estimator guide](docs/choosing_estimator.rst) cover the full technical details.
+
 ## Features
 
 - **sklearn-like API**: Familiar `fit()` interface with `get_params()` and `set_params()`
@@ -135,6 +147,7 @@ Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 - **Panel data support**: Two-way fixed effects estimator for panel designs
 - **Multi-period analysis**: Event-study style DiD with period-specific treatment effects
 - **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), Stacked DiD (Wing, Freedman & Hollingsworth 2024), Efficient DiD (Chen, Sant'Anna & Xie 2025), and Wooldridge ETWFE (2021/2023) estimators for heterogeneous treatment timing
+- **Reversible (non-absorbing) treatments**: de Chaisemartin-D'Haultfœuille `DID_M` estimator for treatments that switch on AND off over time (marketing campaigns, seasonal promotions, on/off policy cycles) — the only library option for non-absorbing treatments
 - **Triple Difference (DDD)**: Ortiz-Villavicencio & Sant'Anna (2025) estimators with proper covariate handling
 - **Synthetic DiD**: Combined DiD with synthetic control for improved robustness
 - **Triply Robust Panel (TROP)**: Factor-adjusted DiD with synthetic weights (Athey et al. 2025)
@@ -146,6 +159,7 @@ Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 - **Pre-trends power analysis**: Roth (2022) minimum detectable violation (MDV) and power curves for pre-trends tests
 - **Power analysis**: MDE, sample size, and power calculations for study design; simulation-based power for any estimator
 - **Data prep utilities**: Helper functions for common data preparation tasks
+- **Survey microdata aggregation**: `aggregate_survey()` rolls individual-level survey data (BRFSS, ACS, CPS, NHANES) into geographic-period panels with design-based precision weights for second-stage DiD
 - **Validated against R**: Benchmarked against `did`, `synthdid`, and `fixest` packages (see [benchmarks](docs/benchmarks.rst))
 
 ## Estimator Aliases
@@ -168,6 +182,7 @@ All estimators have short aliases for convenience:
 | `Bacon` | `BaconDecomposition` | Goodman-Bacon decomposition |
 | `EDiD` | `EfficientDiD` | Efficient DiD |
 | `ETWFE` | `WooldridgeDiD` | Wooldridge ETWFE (2021/2023) |
+| `DCDH` | `ChaisemartinDHaultfoeuille` | de Chaisemartin & D'Haultfœuille (2020) — reversible treatments |
 
 `TROP` already uses its short canonical name and needs no alias.
 
@@ -192,6 +207,7 @@ We provide Jupyter notebook tutorials in `docs/tutorials/`:
 | `13_stacked_did.ipynb` | Stacked DiD (Wing et al. 2024), Q-weights, sub-experiment inspection, trimming, clean control definitions |
 | `15_efficient_did.ipynb` | Efficient DiD (Chen et al. 2025), optimal weighting, PT-All vs PT-Post, efficiency gains, bootstrap inference |
 | `16_survey_did.ipynb` | Survey-aware DiD with complex sampling designs (strata, PSU, FPC, weights), replicate weights, subpopulation analysis, DEFF diagnostics |
+| `17_brand_awareness_survey.ipynb` | Measuring campaign impact on brand awareness with survey data — naive vs. survey-corrected comparison, brand funnel analysis, staggered rollouts, stakeholder communication |
 
 ## Data Preparation
 
@@ -1188,6 +1204,113 @@ EfficientDiD(
 | Covariates | Not yet (Phase 2) | Supported (OR, IPW, DR) |
 | When to choose | Maximum efficiency, PT-All credible | Covariates needed, weaker PT |
 
+### de Chaisemartin-D'Haultfœuille (dCDH) for Reversible Treatments
+
+`ChaisemartinDHaultfoeuille` (alias `DCDH`) is the only library estimator that handles **non-absorbing (reversible) treatments** — treatment can switch on AND off over time. This is the natural fit for marketing campaigns, seasonal promotions, on/off policy cycles.
+
+Ships `DID_M` (= `DID_1` at horizon `l = 1`) plus the full multi-horizon event study `DID_l` for `l = 1..L_max` via the `L_max` parameter. Phase 3 will add covariate adjustment.
+
+```python
+from diff_diff import ChaisemartinDHaultfoeuille
+from diff_diff.prep import generate_reversible_did_data
+
+# Generate a reversible-treatment panel
+data = generate_reversible_did_data(
+    n_groups=80, n_periods=6, pattern="single_switch", seed=42,
+)
+
+# Fit the estimator
+est = ChaisemartinDHaultfoeuille()
+results = est.fit(
+    data,
+    outcome="outcome",
+    group="group",
+    time="period",
+    treatment="treatment",
+)
+results.print_summary()
+
+# Decomposition
+print(f"DID_M (overall):  {results.overall_att:.3f}")
+print(f"DID_+ (joiners):  {results.joiners_att:.3f}")
+print(f"DID_- (leavers):  {results.leavers_att:.3f}")
+print(f"Placebo (DID^pl): {results.placebo_effect:.3f}")
+```
+
+**Parameters:**
+
+```python
+ChaisemartinDHaultfoeuille(
+    alpha=0.05,                   # Significance level
+    n_bootstrap=0,                # 0 = analytical SE only; >0 = multiplier bootstrap
+    bootstrap_weights="rademacher",  # 'rademacher', 'mammen', or 'webb'
+    seed=None,                    # Random seed for bootstrap
+    placebo=True,                 # Auto-compute single-lag placebo
+    twfe_diagnostic=True,         # Auto-compute TWFE decomposition diagnostic
+    drop_larger_lower=True,       # Drop multi-switch groups (matches R DIDmultiplegtDYN)
+    rank_deficient_action="warn", # Used by TWFE diagnostic OLS
+)
+```
+
+**What you get back on the results object:**
+
+| Field | Description |
+|-------|-------------|
+| `overall_att`, `overall_se`, `overall_conf_int` | `DID_M` when `L_max=None`; cost-benefit `delta` when `L_max > 1` (delta-method SE from per-horizon SEs) |
+| `joiners_att`, `leavers_att` | Decomposition into the joiners (`DID_+`) and leavers (`DID_-`) views |
+| `placebo_effect` | Single-lag placebo (`DID_M^pl`) point estimate |
+| `per_period_effects` | Per-period decomposition with explicit A11-violation flags |
+| `twfe_weights`, `twfe_fraction_negative`, `twfe_sigma_fe`, `twfe_beta_fe` | Theorem 1 decomposition diagnostic |
+| `n_groups_dropped_crossers`, `n_groups_dropped_singleton_baseline` | Filter counts (multi-switch groups dropped before estimation; singleton-baseline groups excluded from variance) |
+| `n_groups_dropped_never_switching` | Backwards-compatibility metadata. Never-switching groups participate in the variance via stable-control roles; this field is no longer a filter count. |
+
+**Multi-horizon event study** (Phase 2 - pass `L_max` to `fit()`):
+
+```python
+results = est.fit(data, outcome="outcome", group="group",
+                  time="period", treatment="treatment", L_max=5)
+
+# Per-horizon effects with analytical SE
+for horizon in sorted(results.event_study_effects):
+    e = results.event_study_effects[horizon]
+    print(f"  l={horizon}: DID_l={e['effect']:.3f} (SE={e['se']:.3f})")
+
+# Cost-benefit delta (becomes overall_att when L_max > 1)
+print(f"Cost-benefit delta: {results.cost_benefit_delta['delta']:.3f}")
+
+# Normalized effects: DID^n_l = DID_l / l (for binary treatment)
+for horizon in sorted(results.normalized_effects):
+    print(f"  DID^n_{horizon} = {results.normalized_effects[horizon]['effect']:.3f}")
+
+# Event study DataFrame (includes placebos as negative horizons)
+df = results.to_dataframe("event_study")
+
+# Plot (integrates with plot_event_study)
+from diff_diff import plot_event_study
+plot_event_study(results)
+```
+
+**Standalone TWFE decomposition diagnostic** (without fitting the full estimator):
+
+```python
+from diff_diff import twowayfeweights
+
+diagnostic = twowayfeweights(
+    data, outcome="outcome", group="group", time="period", treatment="treatment",
+)
+print(f"Plain TWFE coefficient: {diagnostic.beta_fe:.3f}")
+print(f"Fraction of negative weights: {diagnostic.fraction_negative:.3f}")
+print(f"sigma_fe (sign-flipping threshold): {diagnostic.sigma_fe:.3f}")
+```
+
+> **Note:** Placebo SE is `NaN` for both the single-lag `DID_M^pl` and the dynamic placebos `DID^{pl}_l`. The point estimates are meaningful for visual pre-trends inspection; formal placebo inference (influence-function derivation) is deferred to a follow-up. See `REGISTRY.md` for the full contract.
+
+> **Note:** By default (`drop_larger_lower=True`), the estimator drops groups whose treatment switches more than once before estimation. This matches R `DIDmultiplegtDYN`'s default and is required for the analytical variance formula to be consistent with the point estimate. Each drop emits an explicit warning.
+
+> **Note:** Phase 1 requires panels with a **balanced baseline** (every group observed at the first global period) and **no interior period gaps**. Late-entry groups (missing the baseline) raise `ValueError`; interior-gap groups are dropped with a warning; terminally-missing groups (early exit / right-censoring) are retained and contribute from their observed periods only. This is a documented deviation from R `DIDmultiplegtDYN`, which supports unbalanced panels — see [`docs/methodology/REGISTRY.md`](docs/methodology/REGISTRY.md) for the rationale, the defensive guards that make terminal missingness safe, and workarounds for unbalanced inputs.
+
+> **Note:** Survey design (`survey_design`), covariate adjustment (`controls`), group-specific linear trends (`trends_linear`), and HonestDiD integration (`honest_did`) are not yet supported. They raise `NotImplementedError` with phase pointers - see [`ROADMAP.md`](ROADMAP.md) for the Phase 3 rollout.
+
 ### Triple Difference (DDD)
 
 Triple Difference (DDD) is used when treatment requires satisfying two criteria: belonging to a treated **group** AND being in an eligible **partition**. The `TripleDifference` class implements the methodology from Ortiz-Villavicencio & Sant'Anna (2025), which correctly handles covariate adjustment (unlike naive implementations).
@@ -2819,7 +2942,7 @@ Returns DataFrame with columns: `unit`, `quality_score`, `outcome_trend_score`,
 
 ## Requirements
 
-- Python 3.9 - 3.13
+- Python 3.9 - 3.14
 - numpy >= 1.20
 - pandas >= 1.3
 - scipy >= 1.7

{diff_diff-3.0.0 → diff_diff-3.0.2}/README.md

@@ -75,6 +75,17 @@ After estimation, call `practitioner_next_steps(results)` for context-aware guid
 
 Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 
+## For Data Scientists
+
+Measuring campaign lift? Evaluating a product launch? diff-diff handles the causal inference so you can focus on the business question.
+
+- **[Which method fits my problem?](docs/practitioner_decision_tree.rst)** - Start from your business scenario (campaign in some markets, staggered rollout, survey data) and find the right estimator
+- **[Getting started for practitioners](docs/practitioner_getting_started.rst)** - End-to-end walkthrough: marketing campaign -> causal estimate -> stakeholder-ready result
+- **[Brand awareness survey tutorial](docs/tutorials/17_brand_awareness_survey.ipynb)** - Full example with complex survey design, brand funnel analysis, and staggered rollouts
+- **Have BRFSS/ACS/CPS individual records?** Use [`aggregate_survey()`](docs/api/prep.rst) to roll respondent-level microdata into a geographic-period panel with inverse-variance precision weights. The returned second-stage design uses analytic weights (`aweight`), so it works directly with `DifferenceInDifferences`, `TwoWayFixedEffects`, `MultiPeriodDiD`, `SunAbraham`, `ContinuousDiD`, and `EfficientDiD` (estimators marked **Full** in the [survey support matrix](docs/choosing_estimator.rst))
+
+Already know DiD? The [academic quickstart](docs/quickstart.rst) and [estimator guide](docs/choosing_estimator.rst) cover the full technical details.
+
 ## Features
 
 - **sklearn-like API**: Familiar `fit()` interface with `get_params()` and `set_params()`
@@ -85,6 +96,7 @@ Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 - **Panel data support**: Two-way fixed effects estimator for panel designs
 - **Multi-period analysis**: Event-study style DiD with period-specific treatment effects
 - **Staggered adoption**: Callaway-Sant'Anna (2021), Sun-Abraham (2021), Borusyak-Jaravel-Spiess (2024) imputation, Two-Stage DiD (Gardner 2022), Stacked DiD (Wing, Freedman & Hollingsworth 2024), Efficient DiD (Chen, Sant'Anna & Xie 2025), and Wooldridge ETWFE (2021/2023) estimators for heterogeneous treatment timing
+- **Reversible (non-absorbing) treatments**: de Chaisemartin-D'Haultfœuille `DID_M` estimator for treatments that switch on AND off over time (marketing campaigns, seasonal promotions, on/off policy cycles) — the only library option for non-absorbing treatments
 - **Triple Difference (DDD)**: Ortiz-Villavicencio & Sant'Anna (2025) estimators with proper covariate handling
 - **Synthetic DiD**: Combined DiD with synthetic control for improved robustness
 - **Triply Robust Panel (TROP)**: Factor-adjusted DiD with synthetic weights (Athey et al. 2025)
@@ -96,6 +108,7 @@ Detailed guide: [`docs/llms-practitioner.txt`](docs/llms-practitioner.txt)
 - **Pre-trends power analysis**: Roth (2022) minimum detectable violation (MDV) and power curves for pre-trends tests
 - **Power analysis**: MDE, sample size, and power calculations for study design; simulation-based power for any estimator
 - **Data prep utilities**: Helper functions for common data preparation tasks
+- **Survey microdata aggregation**: `aggregate_survey()` rolls individual-level survey data (BRFSS, ACS, CPS, NHANES) into geographic-period panels with design-based precision weights for second-stage DiD
 - **Validated against R**: Benchmarked against `did`, `synthdid`, and `fixest` packages (see [benchmarks](docs/benchmarks.rst))
 
 ## Estimator Aliases
@@ -118,6 +131,7 @@ All estimators have short aliases for convenience:
 | `Bacon` | `BaconDecomposition` | Goodman-Bacon decomposition |
 | `EDiD` | `EfficientDiD` | Efficient DiD |
 | `ETWFE` | `WooldridgeDiD` | Wooldridge ETWFE (2021/2023) |
+| `DCDH` | `ChaisemartinDHaultfoeuille` | de Chaisemartin & D'Haultfœuille (2020) — reversible treatments |
 
 `TROP` already uses its short canonical name and needs no alias.
 
@@ -142,6 +156,7 @@ We provide Jupyter notebook tutorials in `docs/tutorials/`:
 | `13_stacked_did.ipynb` | Stacked DiD (Wing et al. 2024), Q-weights, sub-experiment inspection, trimming, clean control definitions |
 | `15_efficient_did.ipynb` | Efficient DiD (Chen et al. 2025), optimal weighting, PT-All vs PT-Post, efficiency gains, bootstrap inference |
 | `16_survey_did.ipynb` | Survey-aware DiD with complex sampling designs (strata, PSU, FPC, weights), replicate weights, subpopulation analysis, DEFF diagnostics |
+| `17_brand_awareness_survey.ipynb` | Measuring campaign impact on brand awareness with survey data — naive vs. survey-corrected comparison, brand funnel analysis, staggered rollouts, stakeholder communication |
 
 ## Data Preparation
 
@@ -1138,6 +1153,113 @@ EfficientDiD(
 | Covariates | Not yet (Phase 2) | Supported (OR, IPW, DR) |
 | When to choose | Maximum efficiency, PT-All credible | Covariates needed, weaker PT |
 
+### de Chaisemartin-D'Haultfœuille (dCDH) for Reversible Treatments
+
+`ChaisemartinDHaultfoeuille` (alias `DCDH`) is the only library estimator that handles **non-absorbing (reversible) treatments** — treatment can switch on AND off over time. This is the natural fit for marketing campaigns, seasonal promotions, on/off policy cycles.
+
+Ships `DID_M` (= `DID_1` at horizon `l = 1`) plus the full multi-horizon event study `DID_l` for `l = 1..L_max` via the `L_max` parameter. Phase 3 will add covariate adjustment.
+
+```python
+from diff_diff import ChaisemartinDHaultfoeuille
+from diff_diff.prep import generate_reversible_did_data
+
+# Generate a reversible-treatment panel
+data = generate_reversible_did_data(
+    n_groups=80, n_periods=6, pattern="single_switch", seed=42,
+)
+
+# Fit the estimator
+est = ChaisemartinDHaultfoeuille()
+results = est.fit(
+    data,
+    outcome="outcome",
+    group="group",
+    time="period",
+    treatment="treatment",
+)
+results.print_summary()
+
+# Decomposition
+print(f"DID_M (overall):  {results.overall_att:.3f}")
+print(f"DID_+ (joiners):  {results.joiners_att:.3f}")
+print(f"DID_- (leavers):  {results.leavers_att:.3f}")
+print(f"Placebo (DID^pl): {results.placebo_effect:.3f}")
+```
+
+**Parameters:**
+
+```python
+ChaisemartinDHaultfoeuille(
+    alpha=0.05,                   # Significance level
+    n_bootstrap=0,                # 0 = analytical SE only; >0 = multiplier bootstrap
+    bootstrap_weights="rademacher",  # 'rademacher', 'mammen', or 'webb'
+    seed=None,                    # Random seed for bootstrap
+    placebo=True,                 # Auto-compute single-lag placebo
+    twfe_diagnostic=True,         # Auto-compute TWFE decomposition diagnostic
+    drop_larger_lower=True,       # Drop multi-switch groups (matches R DIDmultiplegtDYN)
+    rank_deficient_action="warn", # Used by TWFE diagnostic OLS
+)
+```
+
+**What you get back on the results object:**
+
+| Field | Description |
+|-------|-------------|
+| `overall_att`, `overall_se`, `overall_conf_int` | `DID_M` when `L_max=None`; cost-benefit `delta` when `L_max > 1` (delta-method SE from per-horizon SEs) |
+| `joiners_att`, `leavers_att` | Decomposition into the joiners (`DID_+`) and leavers (`DID_-`) views |
+| `placebo_effect` | Single-lag placebo (`DID_M^pl`) point estimate |
+| `per_period_effects` | Per-period decomposition with explicit A11-violation flags |
+| `twfe_weights`, `twfe_fraction_negative`, `twfe_sigma_fe`, `twfe_beta_fe` | Theorem 1 decomposition diagnostic |
+| `n_groups_dropped_crossers`, `n_groups_dropped_singleton_baseline` | Filter counts (multi-switch groups dropped before estimation; singleton-baseline groups excluded from variance) |
+| `n_groups_dropped_never_switching` | Backwards-compatibility metadata. Never-switching groups participate in the variance via stable-control roles; this field is no longer a filter count. |
+
+**Multi-horizon event study** (Phase 2 - pass `L_max` to `fit()`):
+
+```python
+results = est.fit(data, outcome="outcome", group="group",
+                  time="period", treatment="treatment", L_max=5)
+
+# Per-horizon effects with analytical SE
+for horizon in sorted(results.event_study_effects):
+    e = results.event_study_effects[horizon]
+    print(f"  l={horizon}: DID_l={e['effect']:.3f} (SE={e['se']:.3f})")
+
+# Cost-benefit delta (becomes overall_att when L_max > 1)
+print(f"Cost-benefit delta: {results.cost_benefit_delta['delta']:.3f}")
+
+# Normalized effects: DID^n_l = DID_l / l (for binary treatment)
+for horizon in sorted(results.normalized_effects):
+    print(f"  DID^n_{horizon} = {results.normalized_effects[horizon]['effect']:.3f}")
+
+# Event study DataFrame (includes placebos as negative horizons)
+df = results.to_dataframe("event_study")
+
+# Plot (integrates with plot_event_study)
+from diff_diff import plot_event_study
+plot_event_study(results)
+```
+
+**Standalone TWFE decomposition diagnostic** (without fitting the full estimator):
+
+```python
+from diff_diff import twowayfeweights
+
+diagnostic = twowayfeweights(
+    data, outcome="outcome", group="group", time="period", treatment="treatment",
+)
+print(f"Plain TWFE coefficient: {diagnostic.beta_fe:.3f}")
+print(f"Fraction of negative weights: {diagnostic.fraction_negative:.3f}")
+print(f"sigma_fe (sign-flipping threshold): {diagnostic.sigma_fe:.3f}")
+```
+
+> **Note:** Placebo SE is `NaN` for both the single-lag `DID_M^pl` and the dynamic placebos `DID^{pl}_l`. The point estimates are meaningful for visual pre-trends inspection; formal placebo inference (influence-function derivation) is deferred to a follow-up. See `REGISTRY.md` for the full contract.
+
+> **Note:** By default (`drop_larger_lower=True`), the estimator drops groups whose treatment switches more than once before estimation. This matches R `DIDmultiplegtDYN`'s default and is required for the analytical variance formula to be consistent with the point estimate. Each drop emits an explicit warning.
+
+> **Note:** Phase 1 requires panels with a **balanced baseline** (every group observed at the first global period) and **no interior period gaps**. Late-entry groups (missing the baseline) raise `ValueError`; interior-gap groups are dropped with a warning; terminally-missing groups (early exit / right-censoring) are retained and contribute from their observed periods only. This is a documented deviation from R `DIDmultiplegtDYN`, which supports unbalanced panels — see [`docs/methodology/REGISTRY.md`](docs/methodology/REGISTRY.md) for the rationale, the defensive guards that make terminal missingness safe, and workarounds for unbalanced inputs.
+
+> **Note:** Survey design (`survey_design`), covariate adjustment (`controls`), group-specific linear trends (`trends_linear`), and HonestDiD integration (`honest_did`) are not yet supported. They raise `NotImplementedError` with phase pointers - see [`ROADMAP.md`](ROADMAP.md) for the Phase 3 rollout.
+
 ### Triple Difference (DDD)
 
 Triple Difference (DDD) is used when treatment requires satisfying two criteria: belonging to a treated **group** AND being in an eligible **partition**. The `TripleDifference` class implements the methodology from Ortiz-Villavicencio & Sant'Anna (2025), which correctly handles covariate adjustment (unlike naive implementations).
@@ -2769,7 +2891,7 @@ Returns DataFrame with columns: `unit`, `quality_score`, `outcome_trend_score`,
 
 ## Requirements
 
-- Python 3.9 - 3.13
+- Python 3.9 - 3.14
 - numpy >= 1.20
 - pandas >= 1.3
 - scipy >= 1.7

{diff_diff-3.0.0 → diff_diff-3.0.2}/diff_diff/__init__.py

@@ -63,6 +63,7 @@ from diff_diff.power import (
     SimulationMDEResults,
     SimulationPowerResults,
     SimulationSampleSizeResults,
+    SurveyPowerConfig,
     compute_mde,
     compute_power,
     compute_sample_size,
@@ -78,6 +79,7 @@ from diff_diff.pretrends import (
     compute_pretrends_power,
 )
 from diff_diff.prep import (
+    aggregate_survey,
     aggregate_to_cohorts,
     balance_panel,
     create_event_time,
@@ -87,6 +89,7 @@ from diff_diff.prep import (
     generate_event_study_data,
     generate_factor_data,
     generate_panel_data,
+    generate_reversible_did_data,
     generate_staggered_data,
     generate_staggered_ddd_data,
     generate_survey_did_data,
@@ -159,6 +162,16 @@ from diff_diff.efficient_did import (
     EfficientDiDResults,
     EDiDBootstrapResults,
 )
+from diff_diff.chaisemartin_dhaultfoeuille import (
+    ChaisemartinDHaultfoeuille,
+    TWFEWeightsResult,
+    chaisemartin_dhaultfoeuille,
+    twowayfeweights,
+)
+from diff_diff.chaisemartin_dhaultfoeuille_results import (
+    ChaisemartinDHaultfoeuilleResults,
+    DCDHBootstrapResults,
+)
 from diff_diff.trop import (
     TROP,
     TROPResults,
@@ -213,8 +226,9 @@ Stacked = StackedDiD
 Bacon = BaconDecomposition
 EDiD = EfficientDiD
 ETWFE = WooldridgeDiD
+DCDH = ChaisemartinDHaultfoeuille
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",
@@ -222,6 +236,7 @@ __all__ = [
     "MultiPeriodDiD",
     "SyntheticDiD",
     "CallawaySantAnna",
+    "ChaisemartinDHaultfoeuille",
     "ContinuousDiD",
     "SunAbraham",
     "ImputationDiD",
@@ -236,6 +251,7 @@ __all__ = [
     "SDiD",
     "CS",
     "CDiD",
+    "DCDH",
     "SA",
     "BJS",
     "Gardner",
@@ -279,6 +295,12 @@ __all__ = [
     "EfficientDiDResults",
     "EDiDBootstrapResults",
     "EDiD",
+    # ChaisemartinDHaultfoeuille (dCDH)
+    "ChaisemartinDHaultfoeuilleResults",
+    "DCDHBootstrapResults",
+    "TWFEWeightsResult",
+    "chaisemartin_dhaultfoeuille",
+    "twowayfeweights",
     # WooldridgeDiD (ETWFE)
     "WooldridgeDiD",
     "WooldridgeDiDResults",
@@ -327,7 +349,9 @@ __all__ = [
     "generate_staggered_ddd_data",
     "generate_survey_did_data",
     "generate_continuous_did_data",
+    "generate_reversible_did_data",
     "create_event_time",
+    "aggregate_survey",
     "aggregate_to_cohorts",
     "rank_control_units",
     # Honest DiD sensitivity analysis
@@ -345,6 +369,7 @@ __all__ = [
     "SimulationMDEResults",
     "SimulationPowerResults",
     "SimulationSampleSizeResults",
+    "SurveyPowerConfig",
     "compute_mde",
     "compute_power",
     "compute_sample_size",