diff-diff 0.1.0__tar.gz

diff_diff-0.1.0/PKG-INFO

@@ -0,0 +1,421 @@
+Metadata-Version: 2.4
+Name: diff-diff
+Version: 0.1.0
+Summary: A library for Difference-in-Differences causal inference analysis
+Author: diff-diff contributors
+License: MIT
+Project-URL: Homepage, https://github.com/igerber/diff-diff
+Project-URL: Documentation, https://github.com/igerber/diff-diff#readme
+Project-URL: Repository, https://github.com/igerber/diff-diff
+Project-URL: Issues, https://github.com/igerber/diff-diff/issues
+Keywords: causal-inference,difference-in-differences,econometrics,statistics,treatment-effects
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+
+# diff-diff
+
+A Python library for Difference-in-Differences (DiD) causal inference analysis with an sklearn-like API and statsmodels-style outputs.
+
+## Installation
+
+```bash
+pip install diff-diff
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/igerber/diff-diff.git
+cd diff-diff
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from diff_diff import DifferenceInDifferences
+
+# Create sample data
+data = pd.DataFrame({
+    'outcome': [10, 11, 15, 18, 9, 10, 12, 13],
+    'treated': [1, 1, 1, 1, 0, 0, 0, 0],
+    'post': [0, 0, 1, 1, 0, 0, 1, 1]
+})
+
+# Fit the model
+did = DifferenceInDifferences()
+results = did.fit(data, outcome='outcome', treatment='treated', time='post')
+
+# View results
+print(results)  # DiDResults(ATT=3.5000*, SE=1.2583, p=0.0367)
+results.print_summary()
+```
+
+Output:
+```
+======================================================================
+          Difference-in-Differences Estimation Results
+======================================================================
+
+Observations:                        8
+Treated units:                       4
+Control units:                       4
+R-squared:                      0.9123
+
+----------------------------------------------------------------------
+Parameter         Estimate     Std. Err.     t-stat      P>|t|
+----------------------------------------------------------------------
+ATT                 3.5000       1.2583      2.782      0.0367
+----------------------------------------------------------------------
+
+95% Confidence Interval: [0.3912, 6.6088]
+
+Signif. codes: '***' 0.001, '**' 0.01, '*' 0.05, '.' 0.1
+======================================================================
+```
+
+## Features
+
+- **sklearn-like API**: Familiar `fit()` interface with `get_params()` and `set_params()`
+- **Pythonic results**: Easy access to coefficients, standard errors, and confidence intervals
+- **Multiple interfaces**: Column names or R-style formulas
+- **Robust inference**: Heteroskedasticity-robust (HC1) and cluster-robust standard errors
+- **Panel data support**: Two-way fixed effects estimator for panel designs
+
+## Usage
+
+### Basic DiD with Column Names
+
+```python
+from diff_diff import DifferenceInDifferences
+
+did = DifferenceInDifferences(robust=True, alpha=0.05)
+results = did.fit(
+    data,
+    outcome='sales',
+    treatment='treated',
+    time='post_policy'
+)
+
+# Access results
+print(f"ATT: {results.att:.4f}")
+print(f"Standard Error: {results.se:.4f}")
+print(f"P-value: {results.p_value:.4f}")
+print(f"95% CI: {results.conf_int}")
+print(f"Significant: {results.is_significant}")
+```
+
+### Using Formula Interface
+
+```python
+# R-style formula syntax
+results = did.fit(data, formula='outcome ~ treated * post')
+
+# Explicit interaction syntax
+results = did.fit(data, formula='outcome ~ treated + post + treated:post')
+
+# With covariates
+results = did.fit(data, formula='outcome ~ treated * post + age + income')
+```
+
+### Including Covariates
+
+```python
+results = did.fit(
+    data,
+    outcome='outcome',
+    treatment='treated',
+    time='post',
+    covariates=['age', 'income', 'education']
+)
+```
+
+### Fixed Effects
+
+Use `fixed_effects` for low-dimensional categorical controls (creates dummy variables):
+
+```python
+# State and industry fixed effects
+results = did.fit(
+    data,
+    outcome='sales',
+    treatment='treated',
+    time='post',
+    fixed_effects=['state', 'industry']
+)
+
+# Access fixed effect coefficients
+state_coefs = {k: v for k, v in results.coefficients.items() if k.startswith('state_')}
+```
+
+Use `absorb` for high-dimensional fixed effects (more efficient, uses within-transformation):
+
+```python
+# Absorb firm-level fixed effects (efficient for many firms)
+results = did.fit(
+    data,
+    outcome='sales',
+    treatment='treated',
+    time='post',
+    absorb=['firm_id']
+)
+```
+
+Combine covariates with fixed effects:
+
+```python
+results = did.fit(
+    data,
+    outcome='sales',
+    treatment='treated',
+    time='post',
+    covariates=['size', 'age'],           # Linear controls
+    fixed_effects=['industry'],            # Low-dimensional FE (dummies)
+    absorb=['firm_id']                     # High-dimensional FE (absorbed)
+)
+```
+
+### Cluster-Robust Standard Errors
+
+```python
+did = DifferenceInDifferences(cluster='state')
+results = did.fit(
+    data,
+    outcome='outcome',
+    treatment='treated',
+    time='post'
+)
+```
+
+### Two-Way Fixed Effects (Panel Data)
+
+```python
+from diff_diff.estimators import TwoWayFixedEffects
+
+twfe = TwoWayFixedEffects()
+results = twfe.fit(
+    panel_data,
+    outcome='outcome',
+    treatment='treated',
+    time='year',
+    unit='firm_id'
+)
+```
+
+## Working with Results
+
+### Export Results
+
+```python
+# As dictionary
+results.to_dict()
+# {'att': 3.5, 'se': 1.26, 'p_value': 0.037, ...}
+
+# As DataFrame
+df = results.to_dataframe()
+```
+
+### Check Significance
+
+```python
+if results.is_significant:
+    print(f"Effect is significant at {did.alpha} level")
+
+# Get significance stars
+print(f"ATT: {results.att}{results.significance_stars}")
+# ATT: 3.5000*
+```
+
+### Access Full Regression Output
+
+```python
+# All coefficients
+results.coefficients
+# {'const': 9.5, 'treated': 1.0, 'post': 2.5, 'treated:post': 3.5}
+
+# Variance-covariance matrix
+results.vcov
+
+# Residuals and fitted values
+results.residuals
+results.fitted_values
+
+# R-squared
+results.r_squared
+```
+
+## Checking Assumptions
+
+### Parallel Trends
+
+**Simple slope-based test:**
+
+```python
+from diff_diff.utils import check_parallel_trends
+
+trends = check_parallel_trends(
+    data,
+    outcome='outcome',
+    time='period',
+    treatment_group='treated'
+)
+
+print(f"Treated trend: {trends['treated_trend']:.4f}")
+print(f"Control trend: {trends['control_trend']:.4f}")
+print(f"Difference p-value: {trends['p_value']:.4f}")
+```
+
+**Robust distributional test (Wasserstein distance):**
+
+```python
+from diff_diff.utils import check_parallel_trends_robust
+
+results = check_parallel_trends_robust(
+    data,
+    outcome='outcome',
+    time='period',
+    treatment_group='treated',
+    unit='firm_id',              # Unit identifier for panel data
+    pre_periods=[2018, 2019],    # Pre-treatment periods
+    n_permutations=1000          # Permutations for p-value
+)
+
+print(f"Wasserstein distance: {results['wasserstein_distance']:.4f}")
+print(f"Wasserstein p-value: {results['wasserstein_p_value']:.4f}")
+print(f"KS test p-value: {results['ks_p_value']:.4f}")
+print(f"Parallel trends plausible: {results['parallel_trends_plausible']}")
+```
+
+The Wasserstein (Earth Mover's) distance compares the full distribution of outcome changes, not just means. This is more robust to:
+- Non-normal distributions
+- Heterogeneous effects across units
+- Outliers
+
+**Equivalence testing (TOST):**
+
+```python
+from diff_diff.utils import equivalence_test_trends
+
+results = equivalence_test_trends(
+    data,
+    outcome='outcome',
+    time='period',
+    treatment_group='treated',
+    unit='firm_id',
+    equivalence_margin=0.5       # Define "practically equivalent"
+)
+
+print(f"Mean difference: {results['mean_difference']:.4f}")
+print(f"TOST p-value: {results['tost_p_value']:.4f}")
+print(f"Trends equivalent: {results['equivalent']}")
+```
+
+## API Reference
+
+### DifferenceInDifferences
+
+```python
+DifferenceInDifferences(
+    robust=True,      # Use HC1 robust standard errors
+    cluster=None,     # Column for cluster-robust SEs
+    alpha=0.05        # Significance level for CIs
+)
+```
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `fit(data, outcome, treatment, time, ...)` | Fit the DiD model |
+| `summary()` | Get formatted summary string |
+| `print_summary()` | Print summary to stdout |
+| `get_params()` | Get estimator parameters (sklearn-compatible) |
+| `set_params(**params)` | Set estimator parameters (sklearn-compatible) |
+
+**fit() Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `data` | DataFrame | Input data |
+| `outcome` | str | Outcome variable column name |
+| `treatment` | str | Treatment indicator column (0/1) |
+| `time` | str | Post-treatment indicator column (0/1) |
+| `formula` | str | R-style formula (alternative to column names) |
+| `covariates` | list | Linear control variables |
+| `fixed_effects` | list | Categorical FE columns (creates dummies) |
+| `absorb` | list | High-dimensional FE (within-transformation) |
+
+### DiDResults
+
+**Attributes:**
+
+| Attribute | Description |
+|-----------|-------------|
+| `att` | Average Treatment effect on the Treated |
+| `se` | Standard error of ATT |
+| `t_stat` | T-statistic |
+| `p_value` | P-value for H0: ATT = 0 |
+| `conf_int` | Tuple of (lower, upper) confidence bounds |
+| `n_obs` | Number of observations |
+| `n_treated` | Number of treated units |
+| `n_control` | Number of control units |
+| `r_squared` | R-squared of regression |
+| `coefficients` | Dictionary of all coefficients |
+| `is_significant` | Boolean for significance at alpha |
+| `significance_stars` | String of significance stars |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `summary(alpha)` | Get formatted summary string |
+| `print_summary(alpha)` | Print summary to stdout |
+| `to_dict()` | Convert to dictionary |
+| `to_dataframe()` | Convert to pandas DataFrame |
+
+## Requirements
+
+- Python >= 3.9
+- numpy >= 1.20
+- pandas >= 1.3
+- scipy >= 1.7
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black diff_diff tests
+ruff check diff_diff tests
+```
+
+## License
+
+MIT License