Merge pull request #49 from igerber/claude/prepare-v1.3.0-release-XmIcZ

Author: igerber

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0] - 2026-01-09
+
+### Added
+- **Triple Difference (DDD) estimator** implementing Ortiz-Villavicencio & Sant'Anna (2025)
+  - `TripleDifference` class for DDD designs where treatment requires two criteria (group AND partition)
+  - `TripleDifferenceResults` dataclass with ATT, SEs, cell means, and diagnostics
+  - `triple_difference()` convenience function for quick estimation
+  - Three estimation methods: regression adjustment (`reg`), inverse probability weighting (`ipw`), and doubly robust (`dr`)
+  - Proper covariate handling (unlike naive DDD implementations that difference two DiDs)
+  - Propensity score trimming for IPW/DR methods
+  - Cluster-robust standard errors support
+  - Tutorial notebook: `docs/tutorials/08_triple_diff.ipynb`
+
+**Reference**: Ortiz-Villavicencio, M., & Sant'Anna, P. H. C. (2025). "Better Understanding Triple Differences Estimators." *Working Paper*. [arXiv:2505.09942](https://arxiv.org/abs/2505.09942)
+
 ## [1.2.1] - 2026-01-08
 
 ### Added
@@ -248,6 +263,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `to_dict()` and `to_dataframe()` export methods
   - `is_significant` and `significance_stars` properties
 
+[1.3.0]: https://github.com/igerber/diff-diff/compare/v1.2.1...v1.3.0
 [1.2.1]: https://github.com/igerber/diff-diff/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/igerber/diff-diff/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/igerber/diff-diff/compare/v1.1.0...v1.1.1

docs/api/index.rst

@@ -18,6 +18,7 @@ Core estimator classes for DiD analysis:
    diff_diff.SyntheticDiD
    diff_diff.CallawaySantAnna
    diff_diff.SunAbraham
+   diff_diff.TripleDifference
 
 Results Classes
 ---------------
@@ -37,6 +38,7 @@ Result containers returned by estimators:
    diff_diff.GroupTimeEffect
    diff_diff.SunAbrahamResults
    diff_diff.SABootstrapResults
+   diff_diff.TripleDifferenceResults
 
 Visualization
 -------------
@@ -177,6 +179,7 @@ Detailed documentation by module:
 
    estimators
    staggered
+   triple_diff
    results
    visualization
    diagnostics

docs/api/triple_diff.rst

@@ -0,0 +1,131 @@
+Triple Difference (DDD)
+=======================
+
+Triple Difference estimator for designs where treatment requires two criteria.
+
+This module implements the methodology from Ortiz-Villavicencio & Sant'Anna (2025),
+which correctly handles covariate adjustment in DDD designs. Unlike naive implementations
+that difference two DiDs, this approach provides valid estimates when identification
+requires conditioning on covariates.
+
+**When to use DDD instead of DiD:**
+
+DDD allows for violations of parallel trends that are:
+
+- Group-specific (e.g., economic shocks affecting treatment states)
+- Partition-specific (e.g., trends affecting women everywhere)
+
+As long as these biases are additive, DDD differences them out. The key assumption
+is that the *differential* trend between eligible and ineligible units would be
+the same across groups.
+
+**Reference:** Ortiz-Villavicencio, M., & Sant'Anna, P. H. C. (2025). Better Understanding
+Triple Differences Estimators. *Working Paper*. `arXiv:2505.09942 <https://arxiv.org/abs/2505.09942>`_
+
+.. module:: diff_diff.triple_diff
+
+TripleDifference
+----------------
+
+Main estimator class for Triple Difference designs.
+
+.. autoclass:: diff_diff.TripleDifference
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~TripleDifference.fit
+      ~TripleDifference.get_params
+      ~TripleDifference.set_params
+
+TripleDifferenceResults
+-----------------------
+
+Results container for Triple Difference estimation.
+
+.. autoclass:: diff_diff.TripleDifferenceResults
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~TripleDifferenceResults.summary
+      ~TripleDifferenceResults.print_summary
+      ~TripleDifferenceResults.to_dict
+      ~TripleDifferenceResults.to_dataframe
+
+Convenience Function
+--------------------
+
+.. autofunction:: diff_diff.triple_difference
+
+Estimation Methods
+------------------
+
+The estimator supports three estimation methods:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 35 50
+
+   * - Method
+     - Description
+     - When to use
+   * - ``"dr"``
+     - Doubly robust
+     - Recommended. Consistent if either outcome or propensity model is correct
+   * - ``"reg"``
+     - Regression adjustment
+     - Simple outcome regression with full interactions
+   * - ``"ipw"``
+     - Inverse probability weighting
+     - When propensity score model is well-specified
+
+Example Usage
+-------------
+
+Basic usage::
+
+    from diff_diff import TripleDifference
+
+    ddd = TripleDifference(estimation_method='dr')
+    results = ddd.fit(
+        data,
+        outcome='wages',
+        group='policy_state',       # 1=state enacted policy, 0=control state
+        partition='female',         # 1=women (affected by policy), 0=men
+        time='post'                 # 1=post-policy, 0=pre-policy
+    )
+    results.print_summary()
+
+With covariates::
+
+    results = ddd.fit(
+        data,
+        outcome='wages',
+        group='policy_state',
+        partition='female',
+        time='post',
+        covariates=['age', 'education', 'experience']
+    )
+
+Using the convenience function::
+
+    from diff_diff import triple_difference
+
+    results = triple_difference(
+        data,
+        outcome='wages',
+        group='policy_state',
+        partition='female',
+        time='post',
+        estimation_method='dr'
+    )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "diff-diff"
-version = "1.2.1"
+version = "1.3.0"
 description = "A library for Difference-in-Differences causal inference analysis"
 readme = "README.md"
 license = "MIT"