diff-diff 2.7.1__tar.gz → 2.7.2__tar.gz

{diff_diff-2.7.1 → diff_diff-2.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diff-diff
-Version: 2.7.1
+Version: 2.7.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
@@ -11,6 +11,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering
 Requires-Dist: numpy>=1.20.0
 Requires-Dist: pandas>=1.3.0
 Requires-Dist: scipy>=1.7.0
@@ -21,12 +23,17 @@ Requires-Dist: black>=23.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
 Requires-Dist: mypy>=1.0 ; extra == 'dev'
 Requires-Dist: maturin>=1.4,<2.0 ; extra == 'dev'
+Requires-Dist: matplotlib>=3.5 ; extra == 'dev'
 Requires-Dist: sphinx>=6.0 ; extra == 'docs'
-Requires-Dist: sphinx-rtd-theme>=1.0 ; extra == 'docs'
+Requires-Dist: pydata-sphinx-theme>=0.15 ; extra == 'docs'
+Requires-Dist: sphinxext-opengraph>=0.9 ; extra == 'docs'
+Requires-Dist: sphinx-sitemap>=2.5 ; extra == 'docs'
+Requires-Dist: nbsphinx>=0.9 ; extra == 'docs'
+Requires-Dist: matplotlib>=3.5 ; extra == 'docs'
 Provides-Extra: dev
 Provides-Extra: docs
-Summary: A library for Difference-in-Differences causal inference analysis
-Keywords: causal-inference,difference-in-differences,econometrics,statistics,treatment-effects
+Summary: Difference-in-Differences causal inference with sklearn-like API. Callaway-Sant'Anna, Synthetic DiD, Honest DiD, event studies, parallel trends.
+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
@@ -38,6 +45,12 @@ Project-URL: Repository, https://github.com/igerber/diff-diff
 
 # diff-diff
 
+[![PyPI version](https://img.shields.io/pypi/v/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![Python versions](https://img.shields.io/pypi/pyversions/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/pypi/dm/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![Documentation](https://readthedocs.org/projects/diff-diff/badge/?version=stable)](https://diff-diff.readthedocs.io/en/stable/)
+
 A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
 
 ## Installation
@@ -1555,7 +1568,7 @@ trop = TROP(
 
 ```python
 TROP(
-    method='twostep',           # Estimation method: 'twostep' (default) or 'joint'
+    method='local',             # Estimation method: 'local' (default) or 'global'
     lambda_time_grid=None,      # Time decay grid (default: [0, 0.1, 0.5, 1, 2, 5])
     lambda_unit_grid=None,      # Unit distance grid (default: [0, 0.1, 0.5, 1, 2, 5])
     lambda_nn_grid=None,        # Nuclear norm grid (default: [0, 0.01, 0.1, 1, 10])
@@ -1568,8 +1581,8 @@ TROP(
 ```
 
 **Estimation methods:**
-- `'twostep'` (default): Per-observation model fitting following Algorithm 2 of the paper. Computes observation-specific weights and fits a model for each treated observation, then averages the individual treatment effects. More flexible but computationally intensive.
-- `'joint'`: Joint weighted least squares optimization. Estimates a single scalar treatment effect τ along with fixed effects and optional low-rank factor adjustment. Faster but assumes homogeneous treatment effects.
+- `'local'` (default): Per-observation model fitting following Algorithm 2 of the paper. Computes observation-specific weights and fits a model for each treated observation, then averages the individual treatment effects. More flexible but computationally intensive.
+- `'global'`: Global weighted least squares optimization. Fits a single model on control observations with global weights, then computes per-observation treatment effects as residuals. Faster but uses global rather than observation-specific weights.
 
 **Convenience function:**
 
@@ -2947,6 +2960,21 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 - **Cunningham, S. (2021).** *Causal Inference: The Mixtape*. Yale University Press. [https://mixtape.scunning.com/](https://mixtape.scunning.com/)
 
+## Citing diff-diff
+
+If you use diff-diff in your research, please cite it:
+
+```bibtex
+@software{diff_diff,
+  title = {diff-diff: Difference-in-Differences Causal Inference for Python},
+  author = {{diff-diff contributors}},
+  url = {https://github.com/igerber/diff-diff},
+  license = {MIT},
+}
+```
+
+See [`CITATION.cff`](CITATION.cff) for the full citation metadata.
+
 ## License
 
 MIT License

{diff_diff-2.7.1 → diff_diff-2.7.2}/README.md

@@ -1,5 +1,11 @@
 # diff-diff
 
+[![PyPI version](https://img.shields.io/pypi/v/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![Python versions](https://img.shields.io/pypi/pyversions/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://img.shields.io/pypi/dm/diff-diff.svg)](https://pypi.org/project/diff-diff/)
+[![Documentation](https://readthedocs.org/projects/diff-diff/badge/?version=stable)](https://diff-diff.readthedocs.io/en/stable/)
+
 A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
 
 ## Installation
@@ -1517,7 +1523,7 @@ trop = TROP(
 
 ```python
 TROP(
-    method='twostep',           # Estimation method: 'twostep' (default) or 'joint'
+    method='local',             # Estimation method: 'local' (default) or 'global'
     lambda_time_grid=None,      # Time decay grid (default: [0, 0.1, 0.5, 1, 2, 5])
     lambda_unit_grid=None,      # Unit distance grid (default: [0, 0.1, 0.5, 1, 2, 5])
     lambda_nn_grid=None,        # Nuclear norm grid (default: [0, 0.01, 0.1, 1, 10])
@@ -1530,8 +1536,8 @@ TROP(
 ```
 
 **Estimation methods:**
-- `'twostep'` (default): Per-observation model fitting following Algorithm 2 of the paper. Computes observation-specific weights and fits a model for each treated observation, then averages the individual treatment effects. More flexible but computationally intensive.
-- `'joint'`: Joint weighted least squares optimization. Estimates a single scalar treatment effect τ along with fixed effects and optional low-rank factor adjustment. Faster but assumes homogeneous treatment effects.
+- `'local'` (default): Per-observation model fitting following Algorithm 2 of the paper. Computes observation-specific weights and fits a model for each treated observation, then averages the individual treatment effects. More flexible but computationally intensive.
+- `'global'`: Global weighted least squares optimization. Fits a single model on control observations with global weights, then computes per-observation treatment effects as residuals. Faster but uses global rather than observation-specific weights.
 
 **Convenience function:**
 
@@ -2909,6 +2915,21 @@ The `HonestDiD` module implements sensitivity analysis methods for relaxing the
 
 - **Cunningham, S. (2021).** *Causal Inference: The Mixtape*. Yale University Press. [https://mixtape.scunning.com/](https://mixtape.scunning.com/)
 
+## Citing diff-diff
+
+If you use diff-diff in your research, please cite it:
+
+```bibtex
+@software{diff_diff,
+  title = {diff-diff: Difference-in-Differences Causal Inference for Python},
+  author = {{diff-diff contributors}},
+  url = {https://github.com/igerber/diff-diff},
+  license = {MIT},
+}
+```
+
+See [`CITATION.cff`](CITATION.cff) for the full citation metadata.
+
 ## License
 
 MIT License

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/__init__.py

@@ -179,7 +179,7 @@ Stacked = StackedDiD
 Bacon = BaconDecomposition
 EDiD = EfficientDiD
 
-__version__ = "2.7.1"
+__version__ = "2.7.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/_backend.py

@@ -23,13 +23,13 @@ try:
         project_simplex as _rust_project_simplex,
         solve_ols as _rust_solve_ols,
         compute_robust_vcov as _rust_compute_robust_vcov,
-        # TROP estimator acceleration (twostep method)
+        # TROP estimator acceleration (local method)
         compute_unit_distance_matrix as _rust_unit_distance_matrix,
         loocv_grid_search as _rust_loocv_grid_search,
         bootstrap_trop_variance as _rust_bootstrap_trop_variance,
-        # TROP estimator acceleration (joint method)
-        loocv_grid_search_joint as _rust_loocv_grid_search_joint,
-        bootstrap_trop_variance_joint as _rust_bootstrap_trop_variance_joint,
+        # TROP estimator acceleration (global method)
+        loocv_grid_search_global as _rust_loocv_grid_search_global,
+        bootstrap_trop_variance_global as _rust_bootstrap_trop_variance_global,
         # SDID weights (Frank-Wolfe matching R's synthdid)
         compute_sdid_unit_weights as _rust_sdid_unit_weights,
         compute_time_weights as _rust_compute_time_weights,
@@ -46,13 +46,13 @@ except ImportError:
     _rust_project_simplex = None
     _rust_solve_ols = None
     _rust_compute_robust_vcov = None
-    # TROP estimator acceleration (twostep method)
+    # TROP estimator acceleration (local method)
     _rust_unit_distance_matrix = None
     _rust_loocv_grid_search = None
     _rust_bootstrap_trop_variance = None
-    # TROP estimator acceleration (joint method)
-    _rust_loocv_grid_search_joint = None
-    _rust_bootstrap_trop_variance_joint = None
+    # TROP estimator acceleration (global method)
+    _rust_loocv_grid_search_global = None
+    _rust_bootstrap_trop_variance_global = None
     # SDID weights (Frank-Wolfe matching R's synthdid)
     _rust_sdid_unit_weights = None
     _rust_compute_time_weights = None
@@ -69,13 +69,13 @@ if _backend_env == 'python':
     _rust_project_simplex = None
     _rust_solve_ols = None
     _rust_compute_robust_vcov = None
-    # TROP estimator acceleration (twostep method)
+    # TROP estimator acceleration (local method)
     _rust_unit_distance_matrix = None
     _rust_loocv_grid_search = None
     _rust_bootstrap_trop_variance = None
-    # TROP estimator acceleration (joint method)
-    _rust_loocv_grid_search_joint = None
-    _rust_bootstrap_trop_variance_joint = None
+    # TROP estimator acceleration (global method)
+    _rust_loocv_grid_search_global = None
+    _rust_bootstrap_trop_variance_global = None
     # SDID weights (Frank-Wolfe matching R's synthdid)
     _rust_sdid_unit_weights = None
     _rust_compute_time_weights = None
@@ -118,13 +118,13 @@ __all__ = [
     '_rust_project_simplex',
     '_rust_solve_ols',
     '_rust_compute_robust_vcov',
-    # TROP estimator acceleration (twostep method)
+    # TROP estimator acceleration (local method)
     '_rust_unit_distance_matrix',
     '_rust_loocv_grid_search',
     '_rust_bootstrap_trop_variance',
-    # TROP estimator acceleration (joint method)
-    '_rust_loocv_grid_search_joint',
-    '_rust_bootstrap_trop_variance_joint',
+    # TROP estimator acceleration (global method)
+    '_rust_loocv_grid_search_global',
+    '_rust_bootstrap_trop_variance_global',
     # SDID weights (Frank-Wolfe matching R's synthdid)
     '_rust_sdid_unit_weights',
     '_rust_compute_time_weights',

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/datasets.py

@@ -266,7 +266,7 @@ def load_castle_doctrine(force_download: bool = False) -> pd.DataFrame:
     ...     outcome="homicide_rate",
     ...     unit="state",
     ...     time="year",
-    ...     cohort="first_treat"
+    ...     first_treat="first_treat"
     ... )
     """
     url = "https://raw.githubusercontent.com/causaldata/causal_datasets/main/castle/castle.csv"
@@ -412,7 +412,7 @@ def load_divorce_laws(force_download: bool = False) -> pd.DataFrame:
     ...     outcome="divorce_rate",
     ...     unit="state",
     ...     time="year",
-    ...     cohort="first_treat"
+    ...     first_treat="first_treat"
     ... )
     """
     # Try to load from causaldata repository
@@ -571,7 +571,7 @@ def load_mpdta(force_download: bool = False) -> pd.DataFrame:
     ...     outcome="lemp",
     ...     unit="countyreal",
     ...     time="year",
-    ...     cohort="first_treat"
+    ...     first_treat="first_treat"
     ... )
     """
     # mpdta is available from the did package documentation

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/staggered.py

@@ -450,10 +450,12 @@ class CallawaySantAnna(
         if self.control_group == "never_treated":
             control_mask = never_treated_mask
         else:  # not_yet_treated
-            # Not yet treated at time t: never-treated OR (first_treat > t AND not cohort g)
-            # Must exclude cohort g since they are the treated group for this ATT(g,t)
+            # Not yet treated at BOTH time t and the base period:
+            # Controls must be untreated at whichever is later, otherwise
+            # their outcome at the base period is contaminated by treatment.
+            nyt_threshold = max(t, base_period_val) + self.anticipation
             control_mask = never_treated_mask | (
-                (unit_cohorts > t + self.anticipation) & (unit_cohorts != g)
+                (unit_cohorts > nyt_threshold) & (unit_cohorts != g)
             )
 
         # Extract outcomes for base and post periods
@@ -616,21 +618,23 @@ class CallawaySantAnna(
                 if base_period_val not in period_to_col or t not in period_to_col:
                     continue
 
-                tasks.append((g, t, period_to_col[base_period_val], period_to_col[t]))
+                tasks.append((g, t, period_to_col[base_period_val], period_to_col[t], base_period_val))
 
         # Process all tasks
         atts = []
         ses = []
         task_keys = []
 
-        for g, t, base_col, post_col in tasks:
+        for g, t, base_col, post_col, base_period_val in tasks:
             treated_mask = cohort_masks[g]
 
             if self.control_group == "never_treated":
                 control_mask = never_treated_mask
             else:
+                # Controls must be untreated at both t and base_period_val
+                nyt_threshold = max(t, base_period_val) + self.anticipation
                 control_mask = never_treated_mask | (
-                    (unit_cohorts > t + self.anticipation) & (unit_cohorts != g)
+                    (unit_cohorts > nyt_threshold) & (unit_cohorts != g)
                 )
 
             y_base = outcome_matrix[:, base_col]
@@ -786,10 +790,10 @@ class CallawaySantAnna(
             if self.control_group == "never_treated":
                 control_mask = never_treated_mask
             else:
-                # For not_yet_treated, control_key includes t
-                ref_t = first_t
+                # Controls must be untreated at both t and base_period_val
+                nyt_threshold = max(first_t, base_period_val) + self.anticipation
                 control_mask = never_treated_mask | (
-                    (unit_cohorts > ref_t + self.anticipation) & (unit_cohorts != first_g)
+                    (unit_cohorts > nyt_threshold) & (unit_cohorts != first_g)
                 )
 
             # For balanced panels, valid_mask is all True so control_valid = control_mask
@@ -846,13 +850,15 @@ class CallawaySantAnna(
                         cho = None
 
             # Process each (g, t) pair in this group
-            for g, t, _, base_col, post_col in tasks:
+            for g, t, bp_val, base_col, post_col in tasks:
                 treated_mask = cohort_masks[g]
 
                 # Recompute control mask for not_yet_treated (varies by g, t)
                 if self.control_group == "not_yet_treated":
+                    # Controls must be untreated at both t and base period
+                    nyt_threshold = max(t, bp_val) + self.anticipation
                     control_mask = never_treated_mask | (
-                        (unit_cohorts > t + self.anticipation) & (unit_cohorts != g)
+                        (unit_cohorts > nyt_threshold) & (unit_cohorts != g)
                     )
 
                 y_base = outcome_matrix[:, base_col]
@@ -1127,8 +1133,19 @@ class CallawaySantAnna(
         n_treated_units = (unit_info[first_treat] > 0).sum()
         n_control_units = (unit_info["_never_treated"]).sum()
 
-        if n_control_units == 0:
-            raise ValueError("No never-treated units found. Check 'first_treat' column.")
+        if n_control_units == 0 and self.control_group == "never_treated":
+            raise ValueError(
+                "No never-treated units found. Check 'first_treat' column. "
+                "Use control_group='not_yet_treated' if all units are eventually treated."
+            )
+        if n_control_units == 0 and self.control_group == "not_yet_treated":
+            # With not_yet_treated, controls are units not yet treated at each
+            # (g, t) pair — never-treated units are not required.
+            if len(treatment_groups) < 2:
+                raise ValueError(
+                    "not_yet_treated control group requires at least 2 treatment "
+                    "cohorts when there are no never-treated units."
+                )
 
         # Pre-compute data structures for efficient ATT(g,t) computation
         precomputed = self._precompute_structures(

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/staggered_results.py

@@ -88,7 +88,7 @@ class CallawaySantAnnaResults:
     n_treated_units : int
         Number of ever-treated units.
     n_control_units : int
-        Number of never-treated units.
+        Number of never-treated units (excludes not-yet-treated dynamic controls).
     event_study_effects : dict, optional
         Effects aggregated by relative time (event study).
     group_effects : dict, optional
@@ -152,7 +152,7 @@ class CallawaySantAnnaResults:
             "",
             f"{'Total observations:':<30} {self.n_obs:>10}",
             f"{'Treated units:':<30} {self.n_treated_units:>10}",
-            f"{'Control units:':<30} {self.n_control_units:>10}",
+            f"{'Never-treated units:':<30} {self.n_control_units:>10}",
             f"{'Treatment cohorts:':<30} {len(self.groups):>10}",
             f"{'Time periods:':<30} {len(self.time_periods):>10}",
             f"{'Control group:':<30} {self.control_group:>10}",

{diff_diff-2.7.1 → diff_diff-2.7.2}/diff_diff/trop.py

@@ -31,8 +31,8 @@ from diff_diff._backend import (
     _rust_unit_distance_matrix,
     _rust_loocv_grid_search,
     _rust_bootstrap_trop_variance,
-    _rust_loocv_grid_search_joint,
-    _rust_bootstrap_trop_variance_joint,
+    _rust_loocv_grid_search_global,
+    _rust_bootstrap_trop_variance_global,
 )
 from diff_diff.trop_results import (
     _LAMBDA_INF,
@@ -63,10 +63,10 @@ class TROP:
 
     Parameters
     ----------
-    method : str, default='twostep'
+    method : str, default='local'
         Estimation method to use:
 
-        - 'twostep': Per-observation model fitting following Algorithm 2 of
+        - 'local': Per-observation model fitting following Algorithm 2 of
           Athey et al. (2025). Computes observation-specific weights and fits
           a model for each treated observation, averaging the individual
           treatment effects. More flexible but computationally intensive.
@@ -77,10 +77,11 @@ class TROP:
           treatment effects as residuals:
           tau_it = Y_it - mu - alpha_i - beta_t - L_it for treated cells.
           ATT is the mean of these effects. For the paper's full
-          per-treated-cell estimator, use ``method='twostep'``.
+          per-treated-cell estimator, use ``method='local'``.
 
-        - 'joint': Deprecated alias for 'global'. Will be removed in a
-          future version.
+        - 'twostep': Deprecated alias for 'local'. Will be removed in v3.0.
+
+        - 'joint': Deprecated alias for 'global'. Will be removed in v3.0.
 
     lambda_time_grid : list, optional
         Grid of time weight decay parameters. 0.0 = uniform weights (disabled).
@@ -138,7 +139,7 @@ class TROP:
 
     def __init__(
         self,
-        method: str = "twostep",
+        method: str = "local",
         lambda_time_grid: Optional[List[float]] = None,
         lambda_unit_grid: Optional[List[float]] = None,
         lambda_nn_grid: Optional[List[float]] = None,
@@ -149,16 +150,24 @@ class TROP:
         seed: Optional[int] = None,
     ):
         # Validate method parameter
-        # 'global' is the preferred name; 'joint' is a deprecated alias
-        valid_methods = ("twostep", "joint", "global")
+        # 'local'/'global' are preferred; 'twostep'/'joint' are deprecated aliases
+        valid_methods = ("local", "twostep", "joint", "global")
         if method not in valid_methods:
             raise ValueError(
                 f"method must be one of {valid_methods}, got '{method}'"
             )
+        if method == "twostep":
+            warnings.warn(
+                "method='twostep' is deprecated and will be removed in v3.0. "
+                "Use method='local' instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            method = "local"
         if method == "joint":
             warnings.warn(
-                "method='joint' is deprecated and will be removed in a future "
-                "version. Use method='global' instead.",
+                "method='joint' is deprecated and will be removed in v3.0. "
+                "Use method='global' instead.",
                 FutureWarning,
                 stacklevel=2,
             )
@@ -556,7 +565,7 @@ class TROP:
     # Joint estimation method
     # =========================================================================
 
-    def _compute_joint_weights(
+    def _compute_global_weights(
         self,
         Y: np.ndarray,
         D: np.ndarray,
@@ -567,7 +576,7 @@ class TROP:
         n_periods: int,
     ) -> np.ndarray:
         """
-        Compute distance-based weights for joint estimation.
+        Compute distance-based weights for global estimation.
 
         Following the reference implementation, weights are computed based on:
         - Time distance: distance to center of treated block
@@ -655,7 +664,7 @@ class TROP:
 
         return delta
 
-    def _solve_joint_model(
+    def _solve_global_model(
         self,
         Y: np.ndarray,
         delta: np.ndarray,
@@ -668,10 +677,10 @@ class TROP:
         """
         n_periods, n_units = Y.shape
         if lambda_nn >= 1e10:
-            mu, alpha, beta = self._solve_joint_no_lowrank(Y, delta)
+            mu, alpha, beta = self._solve_global_no_lowrank(Y, delta)
             L = np.zeros((n_periods, n_units))
         else:
-            mu, alpha, beta, L = self._solve_joint_with_lowrank(
+            mu, alpha, beta, L = self._solve_global_with_lowrank(
                 Y, delta, lambda_nn, self.max_iter, self.tol
             )
         return mu, alpha, beta, L
@@ -718,7 +727,7 @@ class TROP:
 
         return att, treatment_effects, tau_values
 
-    def _loocv_score_joint(
+    def _loocv_score_global(
         self,
         Y: np.ndarray,
         D: np.ndarray,
@@ -731,12 +740,12 @@ class TROP:
         n_periods: int,
     ) -> float:
         """
-        Compute LOOCV score for joint method with specific parameter combination.
+        Compute LOOCV score for global method with specific parameter combination.
 
         Following paper's Equation 5:
         Q(λ) = Σ_{j,s: D_js=0} [τ̂_js^loocv(λ)]²
 
-        For joint method, we exclude each control observation, fit the joint model
+        For global method, we exclude each control observation, fit the global model
         on remaining data, and compute the pseudo-treatment effect at the excluded obs.
 
         Parameters
@@ -766,7 +775,7 @@ class TROP:
             LOOCV score (sum of squared pseudo-treatment effects).
         """
         # Compute global weights (same for all LOOCV iterations)
-        delta = self._compute_joint_weights(
+        delta = self._compute_global_weights(
             Y, D, lambda_time, lambda_unit, treated_periods, n_units, n_periods
         )
 
@@ -779,7 +788,7 @@ class TROP:
             delta_ex[t_ex, i_ex] = 0.0
 
             try:
-                mu, alpha, beta, L = self._solve_joint_model(Y, delta_ex, lambda_nn)
+                mu, alpha, beta, L = self._solve_global_model(Y, delta_ex, lambda_nn)
 
                 # Pseudo treatment effect: τ = Y - μ - α - β - L
                 if np.isfinite(Y[t_ex, i_ex]):
@@ -796,7 +805,7 @@ class TROP:
 
         return tau_sq_sum
 
-    def _solve_joint_no_lowrank(
+    def _solve_global_no_lowrank(
         self,
         Y: np.ndarray,
         delta: np.ndarray,
@@ -806,7 +815,7 @@ class TROP:
 
         Solves: min Σ (1-W)*δ_{it}(Y_{it} - μ - α_i - β_t)²
 
-        The (1-W) masking is already applied to delta by _compute_joint_weights,
+        The (1-W) masking is already applied to delta by _compute_global_weights,
         so treated observations have zero weight and do not affect the fit.
 
         Parameters
@@ -880,7 +889,7 @@ class TROP:
 
         return float(mu), alpha, beta
 
-    def _solve_joint_with_lowrank(
+    def _solve_global_with_lowrank(
         self,
         Y: np.ndarray,
         delta: np.ndarray,
@@ -893,7 +902,7 @@ class TROP:
 
         Solves: min Σ (1-W)*δ_{it}(Y_{it} - μ - α_i - β_t - L_{it})² + λ_nn||L||_*
 
-        The (1-W) masking is already applied to delta by _compute_joint_weights,
+        The (1-W) masking is already applied to delta by _compute_global_weights,
         so treated observations have zero weight and do not affect the fit.
 
         Parameters
@@ -942,7 +951,7 @@ class TROP:
 
             # Step 1: Fix L, solve for (mu, alpha, beta)
             Y_adj = Y_safe - L
-            mu, alpha, beta = self._solve_joint_no_lowrank(Y_adj, delta_masked)
+            mu, alpha, beta = self._solve_global_no_lowrank(Y_adj, delta_masked)
 
             # Step 2: Fix (mu, alpha, beta), update L with FISTA acceleration
             R = Y_safe - mu - alpha[np.newaxis, :] - beta[:, np.newaxis]
@@ -981,11 +990,11 @@ class TROP:
 
         # Final re-solve with converged L (match Rust behavior)
         Y_adj = Y_safe - L
-        mu, alpha, beta = self._solve_joint_no_lowrank(Y_adj, delta_masked)
+        mu, alpha, beta = self._solve_global_no_lowrank(Y_adj, delta_masked)
 
         return mu, alpha, beta, L
 
-    def _fit_joint(
+    def _fit_global(
         self,
         data: pd.DataFrame,
         outcome: str,
@@ -1024,10 +1033,10 @@ class TROP:
         (fixed `treated_periods` across resamples). The treatment timing is
         inferred from the data once and held constant for all bootstrap
         iterations. For staggered adoption designs where treatment timing varies
-        across units, use `method="twostep"` which computes observation-specific
+        across units, use `method="local"` which computes observation-specific
         weights that naturally handle heterogeneous timing.
         """
-        # Data setup (same as twostep method)
+        # Data setup (same as local method)
         all_units = sorted(data[unit].unique())
         all_periods = sorted(data[time].unique())
 
@@ -1097,7 +1106,7 @@ class TROP:
         if n_pre_periods < 2:
             raise ValueError("Need at least 2 pre-treatment periods")
 
-        # Check for staggered adoption (joint method requires simultaneous treatment)
+        # Check for staggered adoption (global method requires simultaneous treatment)
         # Use only observed periods (skip missing) to avoid false positives on unbalanced panels
         first_treat_by_unit = []
         for i in treated_unit_idx:
@@ -1115,7 +1124,7 @@ class TROP:
             raise ValueError(
                 f"method='global' requires simultaneous treatment adoption, but your data "
                 f"shows staggered adoption (units first treated at periods {unique_starts}). "
-                f"Use method='twostep' which properly handles staggered adoption designs."
+                f"Use method='local' which properly handles staggered adoption designs."
             )
 
         # LOOCV grid search for tuning parameters
@@ -1124,7 +1133,7 @@ class TROP:
         best_score = np.inf
         control_mask = D == 0
 
-        if HAS_RUST_BACKEND and _rust_loocv_grid_search_joint is not None:
+        if HAS_RUST_BACKEND and _rust_loocv_grid_search_global is not None:
             try:
                 # Prepare inputs for Rust function
                 control_mask_u8 = control_mask.astype(np.uint8)
@@ -1133,7 +1142,7 @@ class TROP:
                 lambda_unit_arr = np.array(self.lambda_unit_grid, dtype=np.float64)
                 lambda_nn_arr = np.array(self.lambda_nn_grid, dtype=np.float64)
 
-                result = _rust_loocv_grid_search_joint(
+                result = _rust_loocv_grid_search_global(
                     Y, D.astype(np.float64), control_mask_u8,
                     lambda_time_arr, lambda_unit_arr, lambda_nn_arr,
                     self.max_iter, self.tol,
@@ -1170,7 +1179,7 @@ class TROP:
             except Exception as e:
                 # Fall back to Python implementation on error
                 logger.debug(
-                    "Rust LOOCV grid search (joint) failed, falling back to Python: %s", e
+                    "Rust LOOCV grid search (global) failed, falling back to Python: %s", e
                 )
                 best_lambda = None
                 best_score = np.inf
@@ -1193,7 +1202,7 @@ class TROP:
                         ln = 1e10 if np.isinf(lambda_nn_val) else lambda_nn_val
 
                         try:
-                            score = self._loocv_score_joint(
+                            score = self._loocv_score_global(
                                 Y, D, control_obs, lt, lu, ln,
                                 treated_periods, n_units, n_periods
                             )
@@ -1223,11 +1232,11 @@ class TROP:
             lambda_nn = 1e10
 
         # Compute final weights and fit
-        delta = self._compute_joint_weights(
+        delta = self._compute_global_weights(
             Y, D, lambda_time, lambda_unit, treated_periods, n_units, n_periods
         )
 
-        mu, alpha, beta, L = self._solve_joint_model(Y, delta, lambda_nn)
+        mu, alpha, beta, L = self._solve_global_model(Y, delta, lambda_nn)
 
         # Post-hoc tau extraction (per paper Eq. 2)
         att, treatment_effects, tau_values = self._extract_posthoc_tau(
@@ -1258,7 +1267,7 @@ class TROP:
         # Bootstrap variance estimation
         effective_lambda = (lambda_time, lambda_unit, lambda_nn)
 
-        se, bootstrap_dist = self._bootstrap_variance_joint(
+        se, bootstrap_dist = self._bootstrap_variance_global(
             data, outcome, treatment, unit, time,
             effective_lambda, treated_periods
         )
@@ -1300,7 +1309,7 @@ class TROP:
         self.is_fitted_ = True
         return self.results_
 
-    def _bootstrap_variance_joint(
+    def _bootstrap_variance_global(
         self,
         data: pd.DataFrame,
         outcome: str,
@@ -1311,7 +1320,7 @@ class TROP:
         treated_periods: int,
     ) -> Tuple[float, np.ndarray]:
         """
-        Compute bootstrap standard error for joint method.
+        Compute bootstrap standard error for global method.
 
         Uses Rust backend when available for parallel bootstrap (5-15x speedup).
 
@@ -1340,7 +1349,7 @@ class TROP:
         lambda_time, lambda_unit, lambda_nn = optimal_lambda
 
         # Try Rust backend for parallel bootstrap (5-15x speedup)
-        if HAS_RUST_BACKEND and _rust_bootstrap_trop_variance_joint is not None:
+        if HAS_RUST_BACKEND and _rust_bootstrap_trop_variance_global is not None:
             try:
                 # Create matrices for Rust function
                 all_units = sorted(data[unit].unique())
@@ -1359,7 +1368,7 @@ class TROP:
                     .values
                 )
 
-                bootstrap_estimates, se = _rust_bootstrap_trop_variance_joint(
+                bootstrap_estimates, se = _rust_bootstrap_trop_variance_global(
                     Y, D,
                     lambda_time, lambda_unit, lambda_nn,
                     self.n_bootstrap, self.max_iter, self.tol,
@@ -1378,7 +1387,7 @@ class TROP:
 
             except Exception as e:
                 logger.debug(
-                    "Rust bootstrap (joint) failed, falling back to Python: %s", e
+                    "Rust bootstrap (global) failed, falling back to Python: %s", e
                 )
 
         # Python fallback implementation
@@ -1419,7 +1428,7 @@ class TROP:
             ], ignore_index=True)
 
             try:
-                tau = self._fit_joint_with_fixed_lambda(
+                tau = self._fit_global_with_fixed_lambda(
                     boot_data, outcome, treatment, unit, time,
                     optimal_lambda, treated_periods
                 )
@@ -1441,7 +1450,7 @@ class TROP:
         se = np.std(bootstrap_estimates, ddof=1)
         return float(se), bootstrap_estimates
 
-    def _fit_joint_with_fixed_lambda(
+    def _fit_global_with_fixed_lambda(
         self,
         data: pd.DataFrame,
         outcome: str,
@@ -1478,12 +1487,12 @@ class TROP:
         )
 
         # Compute weights (includes (1-W) masking)
-        delta = self._compute_joint_weights(
+        delta = self._compute_global_weights(
             Y, D, lambda_time, lambda_unit, treated_periods, n_units, n_periods
         )
 
         # Fit model on control data and extract post-hoc tau
-        mu, alpha, beta, L = self._solve_joint_model(Y, delta, lambda_nn)
+        mu, alpha, beta, L = self._solve_global_model(Y, delta, lambda_nn)
         att, _, _ = self._extract_posthoc_tau(Y, D, mu, alpha, beta, L)
         return att
 
@@ -1541,9 +1550,9 @@ class TROP:
 
         # Dispatch based on estimation method
         if self.method == "global":
-            return self._fit_joint(data, outcome, treatment, unit, time)
+            return self._fit_global(data, outcome, treatment, unit, time)
 
-        # Below is the twostep method (default)
+        # Below is the local method (default)
         # Get unique units and periods
         all_units = sorted(data[unit].unique())
         all_periods = sorted(data[time].unique())
@@ -2660,10 +2669,18 @@ class TROP:
     def set_params(self, **params) -> "TROP":
         """Set estimator parameters."""
         for key, value in params.items():
+            if key == "method" and value == "twostep":
+                warnings.warn(
+                    "method='twostep' is deprecated and will be removed in "
+                    "v3.0. Use method='local' instead.",
+                    FutureWarning,
+                    stacklevel=2,
+                )
+                value = "local"
             if key == "method" and value == "joint":
                 warnings.warn(
-                    "method='joint' is deprecated and will be removed in a "
-                    "future version. Use method='global' instead.",
+                    "method='joint' is deprecated and will be removed in "
+                    "v3.0. Use method='global' instead.",
                     FutureWarning,
                     stacklevel=2,
                 )

{diff_diff-2.7.1 → diff_diff-2.7.2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "maturin"
 
 [project]
 name = "diff-diff"
-version = "2.7.1"
-description = "A library for Difference-in-Differences causal inference analysis"
+version = "2.7.2"
+description = "Difference-in-Differences causal inference with sklearn-like API. Callaway-Sant'Anna, Synthetic DiD, Honest DiD, event studies, parallel trends."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.9,<3.14"
@@ -18,6 +18,16 @@ keywords = [
     "econometrics",
     "statistics",
     "treatment-effects",
+    "event-study",
+    "staggered-adoption",
+    "parallel-trends",
+    "synthetic-control",
+    "panel-data",
+    "did",
+    "twfe",
+    "callaway-santanna",
+    "honest-did",
+    "sensitivity-analysis",
 ]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
@@ -30,6 +40,8 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Scientific/Engineering",
 ]
 dependencies = [
     "numpy>=1.20.0",
@@ -46,10 +58,15 @@ dev = [
     "ruff>=0.1.0",
     "mypy>=1.0",
     "maturin>=1.4,<2.0",
+    "matplotlib>=3.5",
 ]
 docs = [
     "sphinx>=6.0",
-    "sphinx-rtd-theme>=1.0",
+    "pydata-sphinx-theme>=0.15",
+    "sphinxext-opengraph>=0.9",
+    "sphinx-sitemap>=2.5",
+    "nbsphinx>=0.9",
+    "matplotlib>=3.5",
 ]
 
 [project.urls]

{diff_diff-2.7.1 → diff_diff-2.7.2}/rust/Cargo.lock

@@ -197,7 +197,7 @@ checksum = "930c7171c8df9fb1782bdf9b918ed9ed2d33d1d22300abb754f9085bc48bf8e8"
 
 [[package]]
 name = "diff_diff_rust"
-version = "2.7.1"
+version = "2.7.2"
 dependencies = [
  "blas-src",
  "faer",

{diff_diff-2.7.1 → diff_diff-2.7.2}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "diff_diff_rust"
-version = "2.7.1"
+version = "2.7.2"
 edition = "2021"
 description = "Rust backend for diff-diff DiD library"
 license = "MIT"

{diff_diff-2.7.1 → diff_diff-2.7.2}/rust/src/lib.rs

@@ -42,14 +42,14 @@ fn _rust_backend(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(linalg::solve_ols, m)?)?;
     m.add_function(wrap_pyfunction!(linalg::compute_robust_vcov, m)?)?;
 
-    // TROP estimator acceleration (twostep method)
+    // TROP estimator acceleration (local method)
     m.add_function(wrap_pyfunction!(trop::compute_unit_distance_matrix, m)?)?;
     m.add_function(wrap_pyfunction!(trop::loocv_grid_search, m)?)?;
     m.add_function(wrap_pyfunction!(trop::bootstrap_trop_variance, m)?)?;
 
-    // TROP estimator acceleration (joint method)
-    m.add_function(wrap_pyfunction!(trop::loocv_grid_search_joint, m)?)?;
-    m.add_function(wrap_pyfunction!(trop::bootstrap_trop_variance_joint, m)?)?;
+    // TROP estimator acceleration (global method)
+    m.add_function(wrap_pyfunction!(trop::loocv_grid_search_global, m)?)?;
+    m.add_function(wrap_pyfunction!(trop::bootstrap_trop_variance_global, m)?)?;
 
     // Diagnostics
     m.add_function(wrap_pyfunction!(rust_backend_info, m)?)?;

{diff_diff-2.7.1 → diff_diff-2.7.2}/rust/src/trop.rs

@@ -1081,12 +1081,16 @@ pub fn bootstrap_trop_variance<'py>(
 }
 
 // ============================================================================
-// Joint method implementation
+// Global method implementation
+//
+// Note: Only the #[pyfunction] exports were renamed (joint → global) to match
+// the Python public API. The private Rust helpers below retain their original
+// `*_joint*` names to keep the Rust-only rename scope minimal.
 // ============================================================================
 
-/// Compute global weights for joint method estimation.
+/// Compute global weights for global method estimation.
 ///
-/// Unlike twostep (which computes per-observation weights), joint uses global
+/// Unlike local (which computes per-observation weights), global uses
 /// weights based on:
 /// - Time weights: distance to center of treated block
 /// - Unit weights: RMSE to average treated trajectory over pre-periods
@@ -1196,7 +1200,7 @@ fn compute_joint_weights(
     delta
 }
 
-/// Solve joint TWFE via weighted least squares (no low-rank, no tau).
+/// Solve global TWFE via weighted least squares (no low-rank, no tau).
 ///
 /// Minimizes: min Σ δ_{it}(Y_{it} - μ - α_i - β_t)²
 ///
@@ -1315,7 +1319,7 @@ fn solve_joint_no_lowrank(
     Some((mu, alpha, beta))
 }
 
-/// Solve joint TWFE + low-rank via alternating minimization (no tau).
+/// Solve global TWFE + low-rank via alternating minimization (no tau).
 ///
 /// Minimizes: min Σ δ_{it}(Y_{it} - μ - α_i - β_t - L_{it})² + λ_nn||L||_*
 ///
@@ -1422,12 +1426,12 @@ fn solve_joint_with_lowrank(
     Some((mu, alpha, beta, l))
 }
 
-/// Compute LOOCV score for joint method with specific parameter combination.
+/// Compute LOOCV score for global method with specific parameter combination.
 ///
 /// Following paper's Equation 5:
 /// Q(λ) = Σ_{j,s: D_js=0} [τ̂_js^loocv(λ)]²
 ///
-/// For joint method, we exclude each control observation, fit the joint model
+/// For global method, we exclude each control observation, fit the global model
 /// on remaining data, and compute the pseudo-treatment effect at the excluded obs.
 ///
 /// # Returns
@@ -1502,7 +1506,7 @@ fn loocv_score_joint(
     }
 }
 
-/// Perform LOOCV grid search for joint method using parallel grid search.
+/// Perform LOOCV grid search for global method using parallel grid search.
 ///
 /// Evaluates all combinations of (lambda_time, lambda_unit, lambda_nn) in parallel
 /// and returns the combination with lowest LOOCV score.
@@ -1522,7 +1526,7 @@ fn loocv_score_joint(
 #[pyfunction]
 #[pyo3(signature = (y, d, control_mask, lambda_time_grid, lambda_unit_grid, lambda_nn_grid, max_iter, tol))]
 #[allow(clippy::too_many_arguments)]
-pub fn loocv_grid_search_joint<'py>(
+pub fn loocv_grid_search_global<'py>(
     _py: Python<'py>,
     y: PyReadonlyArray2<'py, f64>,
     d: PyReadonlyArray2<'py, f64>,
@@ -1630,7 +1634,7 @@ pub fn loocv_grid_search_joint<'py>(
     Ok((best_lt, best_lu, best_ln, best_score, n_valid, n_attempted, first_failed))
 }
 
-/// Compute bootstrap variance estimation for TROP joint method in parallel.
+/// Compute bootstrap variance estimation for TROP global method in parallel.
 ///
 /// Performs unit-level block bootstrap, parallelizing across bootstrap iterations.
 /// Uses stratified sampling to preserve treated/control unit ratio.
@@ -1651,7 +1655,7 @@ pub fn loocv_grid_search_joint<'py>(
 #[pyfunction]
 #[pyo3(signature = (y, d, lambda_time, lambda_unit, lambda_nn, n_bootstrap, max_iter, tol, seed))]
 #[allow(clippy::too_many_arguments)]
-pub fn bootstrap_trop_variance_joint<'py>(
+pub fn bootstrap_trop_variance_global<'py>(
     py: Python<'py>,
     y: PyReadonlyArray2<'py, f64>,
     d: PyReadonlyArray2<'py, f64>,
@@ -1737,7 +1741,7 @@ pub fn bootstrap_trop_variance_joint<'py>(
                 }
             }
 
-            // Compute weights and fit joint model
+            // Compute weights and fit global model
             let delta = compute_joint_weights(
                 &y_boot.view(),
                 &d_boot.view(),