feat(twfeweights): plot_twfe_weights() + full docs surface

Plotting (replacing upstream's ggtwfeweights S3 methods) and every
documentation surface the new API owes.

plot_twfe_weights(result, kind="auto"|"weights"|"balance") lives beside
plot_bacon in visualization/_diagnostic.py and dispatches on either result
type. The weights view puts weight on x and ATT(g,t) on y with zero lines, so
negative-weight cells sit visibly left of the axis; the balance view plots
unweighted against implicitly-weighted covariate differences with a
no-improvement diagonal. "auto" picks balance when a balance table is
present.

Docs: a REGISTRY.md section carrying the weight equations, the cross-surface
identity, the tolerance table with per-gate rationale, and eleven explicit
Note/Deviation-from-R entries - including the fixest zero-column segfault and
its root cause, the annihilated-covariate drop, and the 0/0-cell limit, so
the two places we deliberately differ from R are recorded rather than
discovered later by a reviewer. Two paragraphs separate this surface from
`twowayfeweights` (dCDH, weights (unit, time) cells) and from
BaconDecomposition (decomposes into 2x2 comparisons), since all three are
"TWFE weight" diagnostics and the distinction is the thing a reader most
needs.

Also: docs/api/twfe_weights.rst with runnable examples, four api/index.rst
registrations (2 result classes, the plot, 2 functions, toctree),
doc-deps.yaml group + sources entries, a README one-liner in Diagnostics &
Sensitivity, llms.txt catalog entry, llms-full.txt API + result blocks, a
references.rst sub-entry naming the upstream package and its MIT copyright,
and a changelog.d fragment.

This closes the doc-deps gate the attgt_weights commit left red.

Verified: 14378 tests collect clean; docs IA, doc-deps integrity, diagnostic
roster, guides, changelog-fragment, serialization and all visualization
suites green (903 passed, 43 skipped).

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

README.md

@@ -130,6 +130,7 @@ Full guide: `diff_diff.get_llm_guide("practitioner")`.
 - [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html) - Cattaneo, Jansson & Ma (2020) density-discontinuity test (`RDDensityTest`): rddensity 3.0 parity, robust bias-corrected inference, unrestricted/restricted models, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)
 - [Placebo Tests](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html) - placebo timing, group, permutation, leave-one-out
+- [TWFE Weight Diagnostics](https://diff-diff.readthedocs.io/en/stable/api/twfe_weights.html) - Baker, Callaway, Cunningham, Goodman-Bacon & Sant'Anna (2025) implicit weights on ATT(g,t): `attgt_weights(cs_result, aggregation='twfe'|'overall'|'simple')` shows what a TWFE regression (vs ATT^O / ATT^simple) implicitly puts on each group-time effect, including negative weights; `decompose_twfe_weights(panel, method='fwl')` re-derives the estimate from its building blocks with the pre-trend-violation contribution and implicit covariate balance. Ported from Brantly Callaway's `twfeweights` R package (MIT)
 - [Honest DiD](https://diff-diff.readthedocs.io/en/stable/api/honest_did.html) - Rambachan & Roth (2023) sensitivity analysis: robust CI under PT violations, breakdown values
 - [Pre-Trends Power Analysis](https://diff-diff.readthedocs.io/en/stable/api/pretrends.html) - Roth (2022) minimum detectable violation and power curves
 - [Power Analysis](https://diff-diff.readthedocs.io/en/stable/api/power.html) - analytical and simulation-based MDE, sample size, power curves for study design

changelog.d/20260831-twfe-weight-diagnostics.md

@@ -0,0 +1,33 @@
+### Added
+- **TWFE weight diagnostics** (port of Brantly Callaway's `twfeweights` R
+  package, MIT): what a two-way fixed effects regression *implicitly* weights
+  on staggered-adoption data.
+  - `attgt_weights(results, aggregation="twfe"|"overall"|"simple")` reports the
+    weight a TWFE regression, ATT^O, or ATT^simple places on each ATT(g,t),
+    plus the negative-weight share. Takes a fitted `CallawaySantAnnaResults`
+    (reading cohort masses off its aggregation bookkeeping, so no raw panel is
+    needed); a `(gt_frame, data=, unit=, time=, first_treat=)` fallback
+    consumes `result.to_dataframe("group_time")` verbatim. Returns
+    `ATTGTWeightsResult`. `aggregation="twfe"` requires
+    `base_period="universal"` and `control_group="never_treated"`, matching
+    the restrictions R enforces.
+  - `decompose_twfe_weights(data, outcome=, unit=, time=, first_treat=,
+    method="fwl", covariates=, base_period="first_period"|"gmin1")` re-derives
+    the estimate from its ATT(g,t) building blocks and returns
+    `TWFEDecompositionResult` with `pretrend_bias` — the contribution of
+    pre-treatment cells, i.e. of parallel-trends violations rather than of
+    treatment. With `balance_covariates=`, `result.covariate_balance()`
+    reports whether the implicit weights actually balance those covariates.
+  - `plot_twfe_weights()` renders either view.
+
+  Names are deliberately separate from the existing `twowayfeweights` /
+  `TWFEWeightsResult` (de Chaisemartin & D'Haultfoeuille) surface, which
+  weights (unit, time) cells rather than ATT(g,t) parameters.
+
+  Validated against R `twfeweights` 0.9.0 output on three fixtures (`mpdta`
+  plus two simulated panels); goldens at
+  `benchmarks/data/twfeweights_golden.json`, regenerated by
+  `benchmarks/R/generate_twfeweights_golden.R`. R is never needed to run the
+  test suite. Methodology: Baker, Callaway, Cunningham, Goodman-Bacon &
+  Sant'Anna (2025); Callaway & Sant'Anna (2021) for the ATT^O / ATT^simple
+  weights.

diff_diff/__init__.py

@@ -329,6 +329,7 @@
     plot_sensitivity,
     plot_staircase,
     plot_synth_weights,
+    plot_twfe_weights,
 )
 from diff_diff.wooldridge import WooldridgeDiD
 from diff_diff.wooldridge_results import WooldridgeDiDResults
@@ -488,6 +489,7 @@ def __getattr__(name: str) -> _Any:
     "SieveLearner",
     # Visualization
     "plot_bacon",
+    "plot_twfe_weights",
     "plot_event_study",
     "plot_group_effects",
     "plot_sensitivity",

diff_diff/guides/llms-full.txt

@@ -1503,6 +1503,44 @@ results.print_summary()
 plot_bacon(results)
 ```
 
+### TWFE Weight Diagnostics
+
+What a TWFE regression implicitly weights on staggered data. Distinct from
+`twowayfeweights` (dCDH), which weights (unit, time) cells: these weight
+ATT(g,t) parameters. Ported from Brantly Callaway's `twfeweights` R package
+(MIT); methodology Baker, Callaway, Cunningham, Goodman-Bacon & Sant'Anna
+(2025).
+
+```python
+attgt_weights(
+    results,                        # CallawaySantAnnaResults, or a (g,t) frame
+    aggregation="twfe",             # "twfe" | "overall" (ATT^O) | "simple"
+    data=None, unit=None, time=None, first_treat=None,   # frame path only
+    weights=None,                   # unit-level sampling weights
+) -> ATTGTWeightsResult
+
+decompose_twfe_weights(
+    data,                           # balanced long panel (it re-estimates)
+    outcome=, unit=, time=, first_treat=,
+    method="fwl",
+    covariates=None,
+    base_period="first_period",     # or "gmin1"
+    balance_covariates=None,        # enables result.covariate_balance()
+    weights=None,
+) -> TWFEDecompositionResult
+
+plot_twfe_weights(result, kind="auto")   # "weights" | "balance"
+```
+
+`aggregation="twfe"` requires a fit with `base_period="universal"` and
+`control_group="never_treated"`; it raises otherwise. ATT^O and ATT^simple
+weights are non-negative and sum to one, so comparing `implied_att` across
+the three aggregations shows what the TWFE specification costs.
+
+`decompose_twfe_weights` takes the raw panel rather than a fitted result
+because it re-estimates. It is tied to `attgt_weights` by an identity:
+`attgt_weights(cs, aggregation="twfe").implied_att == decompose_twfe_weights(panel, ...).estimate`.
+
 ### StaggeredTripleDifference
 
 DEPRECATED in 3.9, removed in 4.0 (ledger row M-013). Use
@@ -1967,6 +2005,33 @@ Returned by `BaconDecomposition.fit()` (and the deprecated `bacon_decompose()` w
 
 **Methods:** `summary()`, `print_summary()`, `to_dataframe()`
 
+### ATTGTWeightsResult
+
+Diagnostic result from `attgt_weights`. No inference quintet - the
+decomposition is an algebraic identity.
+
+- `weights`: DataFrame with `group`, `time`, `post`, `weight`, `att`
+- `implied_att`: `sum(weight * att)` - the TWFE coefficient when
+  `aggregation="twfe"`
+- `n_negative`, `negative_weight_share`: the staggered-TWFE pathology
+- `aggregation`, `source`, `control_group`, `base_period`, `n_cells`
+- `summary()`, `to_dataframe()`, `to_dict()`
+
+### TWFEDecompositionResult
+
+Diagnostic result from `decompose_twfe_weights`.
+
+- `cells`: DataFrame with `group`, `time`, `post`, `att`, `weight`, `ess`,
+  `remainder`
+- `estimate` == `decomposition` + `remainder`
+- `pretrend_bias`: contribution of PRE-treatment cells, i.e. of
+  parallel-trends violations rather than of treatment
+- `post_only`, `effective_sample_size`, `covariates`, `base_period`
+- `covariate_balance(level="summary"|"cell", standardize=True,
+  post_only=True)`: implicit-weight covariate balance; raises when
+  `balance_covariates=` was not requested
+- `summary()`, `to_dataframe()`, `to_dict()`
+
 ### Comparison2x2
 
 Individual 2x2 DiD comparison (used in BaconDecompositionResults).

diff_diff/guides/llms.txt

@@ -90,6 +90,7 @@ The site is organized into 5 sections, each with a landing page:
 - [Manipulation Testing](https://diff-diff.readthedocs.io/en/stable/api/regression_discontinuity.html): Cattaneo, Jansson & Ma (2020) density-discontinuity manipulation test (`RDDensityTest`), parity with R rddensity 3.0 - boundary-adaptive local polynomial density estimation at the cutoff, robust bias-corrected inference, unrestricted/restricted models, jackknife/plugin variances, data-driven bandwidths, mass-point adjustment
 - [Parallel Trends Testing](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html): Simple and Wasserstein-robust parallel trends tests, equivalence testing (TOST)
 - [Placebo Tests](https://diff-diff.readthedocs.io/en/stable/api/diagnostics.html): Placebo timing, group, permutation, and leave-one-out diagnostics
+- [TWFE Weight Diagnostics](https://diff-diff.readthedocs.io/en/stable/api/twfe_weights.html): Baker et al. (2025) implicit weights on ATT(g,t) - `attgt_weights(results, aggregation='twfe'|'overall'|'simple')` takes a fitted `CallawaySantAnnaResults` (raw ATT(g,t) frame + panel as fallback) and returns the weight each estimand places on each group-time effect, with the negative-weight share; `decompose_twfe_weights(data, outcome=, unit=, time=, first_treat=, method='fwl', covariates=)` re-derives the TWFE estimate from its ATT(g,t) building blocks with `pretrend_bias`, and `result.covariate_balance()` reports implicit-weight covariate balance. Plot with `plot_twfe_weights`. R `twfeweights` 0.9.0 output parity
 - [Honest DiD](https://diff-diff.readthedocs.io/en/stable/api/honest_did.html): Rambachan & Roth (2023) sensitivity analysis — robust CI under parallel trends violations, breakdown values
 - [Pre-Trends Power Analysis](https://diff-diff.readthedocs.io/en/stable/api/pretrends.html): Roth (2022) Section II.A-B no-individually-significant (NIS) box-probability pretest power + minimum detectable violation; `pretest_form='nis'` (default) implements the paper's primary form, `pretest_form='wald'` retained as paper-supported alternative (Propositions 1+3+4 all apply); linear-violation MDV in Roth's γ units when relative-time labels are threaded through `fit()`; full Σ_22 routing on non-bootstrap CallawaySantAnna and SunAbraham adapters and on admitted CS-/StackedDiD-sourced `aggregate('event_study')` containers (StackedDiD persists its ES VCV in every inference mode)
 - [Power Analysis](https://diff-diff.readthedocs.io/en/stable/api/power.html): Analytical and simulation-based power analysis — MDE, sample size, power curves for study design

diff_diff/visualization/__init__.py

@@ -15,6 +15,7 @@
 from diff_diff.visualization._diagnostic import (
     plot_bacon,
     plot_sensitivity,
+    plot_twfe_weights,
 )
 from diff_diff.visualization._event_study import (
     PlottableResults,
@@ -48,6 +49,7 @@
     "plot_group_effects",
     "plot_sensitivity",
     "plot_bacon",
+    "plot_twfe_weights",
     "plot_power_curve",
     "plot_pretrends_power",
     # New public functions

diff_diff/visualization/_diagnostic.py

@@ -817,3 +817,176 @@ def _render_bacon_plotly(
         fig.show()
 
     return fig
+
+
+def plot_twfe_weights(
+    results: Any,
+    *,
+    kind: str = "auto",
+    standardize: bool = True,
+    absolute_value: bool = True,
+    figsize: Tuple[float, float] = (10, 6),
+    title: Optional[str] = None,
+    xlabel: Optional[str] = None,
+    ylabel: Optional[str] = None,
+    post_color: str = "#2563eb",
+    pre_color: str = "#dc2626",
+    markersize: int = 80,
+    alpha: float = 0.8,
+    annotate: bool = False,
+    ax: Optional[Any] = None,
+    show: bool = True,
+) -> Any:
+    """Visualize implicit TWFE weights on ATT(g, t), or their covariate balance.
+
+    Two views, matching upstream's ``ggtwfeweights`` methods:
+
+    - ``kind="weights"`` plots weight against ATT(g, t), one point per
+      group-time cell, coloured by pre/post. Points to the LEFT of the
+      vertical zero line carry negative weight - the staggered-TWFE
+      pathology.
+    - ``kind="balance"`` plots unweighted against implicitly-weighted
+      covariate differences. Points near zero on the vertical axis are
+      covariates the implicit weights balance.
+
+    Parameters
+    ----------
+    results : ATTGTWeightsResult or TWFEDecompositionResult
+        Output of :func:`diff_diff.attgt_weights` or
+        :func:`diff_diff.decompose_twfe_weights`.
+    kind : {"auto", "weights", "balance"}, default "auto"
+        ``"auto"`` picks ``"balance"`` when the result carries a balance
+        table and ``"weights"`` otherwise.
+    standardize : bool, default True
+        Balance view: divide differences by the pooled standard deviation.
+    absolute_value : bool, default True
+        Balance view: plot absolute differences, so "closer to zero is
+        better" reads the same for every covariate.
+    figsize : tuple, default (10, 6)
+        Figure size in inches. Ignored when ``ax`` is supplied.
+    title, xlabel, ylabel : str, optional
+        Overrides for the defaults chosen per ``kind``.
+    post_color, pre_color : str
+        Colors for post- and pre-treatment cells (weights view).
+    markersize : int, default 80
+        Scatter marker area.
+    alpha : float, default 0.8
+        Marker opacity.
+    annotate : bool, default False
+        Label each point with its ``(group, time)`` or covariate name.
+    ax : matplotlib Axes, optional
+        Axes to draw on. A new figure is created when omitted.
+    show : bool, default True
+        Call ``plt.show()`` before returning.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+
+    Raises
+    ------
+    ValueError
+        On an unknown ``kind``, or when ``kind="balance"`` is requested for a
+        result that carries no balance table.
+
+    Examples
+    --------
+    >>> import diff_diff  # doctest: +SKIP
+    >>> w = diff_diff.attgt_weights(cs_result)  # doctest: +SKIP
+    >>> diff_diff.plot_twfe_weights(w)  # doctest: +SKIP
+    """
+    if kind not in ("auto", "weights", "balance"):
+        raise ValueError(f"kind must be one of ['auto', 'weights', 'balance'], got {kind!r}")
+    has_balance = getattr(results, "balance", None) is not None
+    if kind == "auto":
+        kind = "balance" if has_balance else "weights"
+    if kind == "balance" and not has_balance:
+        raise ValueError(
+            "this result carries no covariate balance table, so kind='balance' "
+            "has nothing to plot. Recompute with "
+            "decompose_twfe_weights(..., balance_covariates=[...])."
+        )
+
+    from diff_diff.visualization._common import _require_matplotlib
+
+    plt = _require_matplotlib()
+    if ax is None:
+        _, ax = plt.subplots(figsize=figsize)
+
+    if kind == "weights":
+        table = getattr(results, "weights", None)
+        if table is None:
+            table = results.cells
+        post = table["post"].to_numpy().astype(bool)
+        weight = table["weight"].to_numpy()
+        att = table["att"].to_numpy()
+        ax.axhline(0, color="0.4", linewidth=1.2, zorder=1)
+        ax.axvline(0, color="0.4", linewidth=1.2, zorder=1)
+        for mask, color, label in (
+            (post, post_color, "post-treatment"),
+            (~post, pre_color, "pre-treatment"),
+        ):
+            if mask.any():
+                ax.scatter(
+                    weight[mask],
+                    att[mask],
+                    s=markersize,
+                    alpha=alpha,
+                    color=color,
+                    label=label,
+                    zorder=3,
+                )
+        if annotate:
+            for w, a, g, t in zip(weight, att, table["group"], table["time"]):
+                ax.annotate(
+                    f"({g}, {t})", (w, a), fontsize=8, xytext=(4, 4), textcoords="offset points"
+                )
+        ax.set_xlabel(xlabel or "Implicit weight")
+        ax.set_ylabel(ylabel or "ATT(g, t)")
+        default_title = "Implicit weights on group-time effects"
+        n_negative = int((weight < 0).sum())
+        if n_negative:
+            default_title += f"  ({n_negative} negative)"
+        ax.set_title(title or default_title)
+        ax.legend(frameon=False)
+    else:
+        balance = results.covariate_balance(level="summary", standardize=standardize)
+        suffix = "_std_diff" if standardize else "_diff"
+        unweighted = balance["unweighted" + suffix].to_numpy(dtype=float)
+        weighted = balance["weighted" + suffix].to_numpy(dtype=float)
+        if absolute_value:
+            unweighted = np.abs(unweighted)
+            weighted = np.abs(weighted)
+        ax.axhline(0, color="0.4", linewidth=1.2, zorder=1)
+        ax.scatter(
+            unweighted,
+            weighted,
+            s=markersize,
+            alpha=alpha,
+            color=post_color,
+            zorder=3,
+        )
+        limit = float(np.nanmax(np.abs(np.concatenate([unweighted, weighted]))) or 1.0)
+        ax.plot(
+            [0, limit],
+            [0, limit],
+            color="0.6",
+            linestyle="--",
+            linewidth=1.0,
+            zorder=2,
+            label="no improvement",
+        )
+        if annotate:
+            for x, y, name in zip(unweighted, weighted, balance["covariate"]):
+                ax.annotate(
+                    str(name), (x, y), fontsize=8, xytext=(4, 4), textcoords="offset points"
+                )
+        kindword = "standardized " if standardize else ""
+        ax.set_xlabel(xlabel or f"Unweighted {kindword}difference")
+        ax.set_ylabel(ylabel or f"Implicitly-weighted {kindword}difference")
+        ax.set_title(title or "Covariate balance under the implicit weights")
+        ax.legend(frameon=False)
+
+    if show:
+        plt.show()
+    return ax

docs/api/index.rst

@@ -76,6 +76,8 @@ Result containers returned by estimators:
    diff_diff.TwoStageBootstrapResults
    diff_diff.SpilloverDiDResults
    diff_diff.BaconDecompositionResults
+   diff_diff.ATTGTWeightsResult
+   diff_diff.TWFEDecompositionResult
    diff_diff.wooldridge_results.WooldridgeDiDResults
    diff_diff.lpdid_results.LPDiDResults
    diff_diff.changes_in_changes_results.ChangesInChangesResults
@@ -119,6 +121,7 @@ Plotting functions and plot builders:
    diff_diff.plot_honest_event_study
    diff_diff.RDPlot
    diff_diff.plot_bacon
+   diff_diff.plot_twfe_weights
    diff_diff.plot_power_curve
    diff_diff.plot_pretrends_power
 
@@ -138,6 +141,8 @@ Placebo tests and model diagnostics:
    diff_diff.leave_one_out_test
    diff_diff.run_all_placebo_tests
    diff_diff.PlaceboTestResults
+   diff_diff.attgt_weights
+   diff_diff.decompose_twfe_weights
    diff_diff.RDDensityTest
 
 Panel Profiling
@@ -400,6 +405,7 @@ Diagnostics & Inference
    honest_did
    power
    pretrends
+   twfe_weights
 
 Reporting
 ~~~~~~~~~